[saucam]

What

A loop pursues one objective until the daemon's own checks pass, then delivers the result as one commit on its own branch.
The worker agent never decides it is done: loop_report only asks for verification; the daemon snapshots the candidate, runs every check itself, records the evidence, and commits exactly the tree it verified.

codeoid loop start "Fix the failing checkout test" --workdir ~/src/shop --check "bun test src/checkout" --test --wait

User guide: docs/loops.md. Design: docs/loop-engineering-design.md.

How

• Controller (src/daemon/loops/service.ts): compare-and-set transitions, attempts scheduled only through the dispatcher, pause / resume / steer / cancel, restart reconciliation, attempt and time budgets (daemon downtime and approval waits are not charged), a takeover prompt for replacement workers.
• Verification (host.ts, materialize.ts):
  • The candidate is the run's base with the worktree laid over it; secret-looking files are withheld and setup's files excluded.
  • It is written out from hash-verified git objects into a daemon-made check directory, prepared once by the trusted setup recipe on the committed base, then sealed.
  • Every check runs in a fresh copy of the sealed directory at the same path, and whatever a check or setup leaves running is reaped before the next.
  • Delivery is one commit on the base holding the verified tree.
• Hardening: every daemon git call is pinned to the run's repository (GIT_DIR / GIT_COMMON_DIR / GIT_WORK_TREE), with hooks, filter drivers, fsmonitor, replace refs and network off, and gets an agent's environment, never the daemon's credentials (git-env.ts, also adopted by forks, setup, fleet and packs). No session but the run's worker can get a working directory in its worktree (create, fork, import, dispatch, routines, pipelines, skill grants).
• Surfaces: codeoid loop … CLI, web loops panel and run detail, TUI /loop and /loops, protocol loop.* messages with schemas.

Known limits (documented)

• The worker and the checks run as the user, unsandboxed; reaping is best-effort (Linux), not a sandbox.
• Repositories with files stored through a configured git filter (Git LFS, git-crypt) are refused; checkout conversions (eol, working-tree-encoding) aren't applied in the check directory.
• Protected inputs, hidden checks and cannot_satisfy verification are the next milestone.

Review

Audited over 16 rounds by independent security and correctness reviewers until neither found anything significant; every finding has a regression test (src/daemon/loops/*.test.ts, src/tests/loops-e2e.test.ts, src/tests/git-env.test.ts, src/tests/kill-marked.test.ts).
Full suite: 4161 pass / 0 fail; web 732 pass.

Follow-up stacked on this: loop watches (CI-failure and review-comment triggers).

🤖 Generated with Claude Code