Skip to main content

arc drain

arc drain is a long-running process that watches the work ledger and dispatches ready work to an idle peer until the ready set is empty.

arc drain is a real CLI process, not a chat turn — killing whatever session started it does not stop draining unless this process itself is killed. It subscribes to /dev/code-agents (or the path you pass with --subscribe-path), and on each wake it claims ready work from the work ledger and execs /dev/code-agents/.actions/run with the claimed work. An empty ready set exits 0; arc drain never creates ledger rows itself, it only consumes them.

Usage

bash
arc drain --cwd <dir> [options]
  • --cwd <dir> (required, no default): working directory passed to /dev/code-agents/.actions/run. Must not be the daemon's own project checkout
  • --work-root <path>: work collection root, i.e. which AFS path holds the work records (default /work)
  • --subscribe-path <path>: AFS path prefix to subscribe for wakes, e.g. /dev/code-agents or /settled (default /dev/code-agents)
  • --engine <id>: restrict dispatch to this engine id (default: first idle dispatch target)
  • --peer <id>: restrict dispatch to this peer id (default: first idle online peer)

Global flags (see Overview): --json, --view, --instance / -i (which local ARC instance; omit for default), and --home (instance root; to pick which instance, use --instance). --standalone is also global (ad-hoc mode: load AFS from the current directory's local config instead of a running daemon). Drain is normally left against the default instance unless you pass --instance.

arc drain expects the target instance's daemon to already be up (e.g. via arc service start). Letting drain auto-start it instead boots a leaner AFS that skips the default /work mount, so it fails with No module found for path: /work in namespace 'default' before ever reaching the ledger.

Example (empty ready set, daemon already running)

bash
$ arc drain --cwd /path/to/a/work/tree
ready set empty

Press Ctrl-C (SIGINT) or send SIGTERM to stop draining; either aborts the current wait cleanly.

Example (missing the required flag)

bash
$ arc drain
ERROR: --cwd is required (no default — must not be the daemon's own project checkout)