git:20260919.5555b53 to git:20260919.c6c5106

- description: Orbit — the task/audit/dispatch layer for AI coding agents. Use for anything touching a task ID, `.orbit/`, `orbit` CLI or `orbit.*` MCP tools, the docs corpus, friction records, jobs and `jrun-*` runs, routines, auto-tasks, the sweep clock, worktree GC, task publication and recovery, federated MCP, the dashboard, or setting Orbit up on a machine or repository. Covers both doing work through Orbit and configuring Orbit so that work runs unattended.

- Orbit governs AI coding agents: every change is a task, every task carries an

- audit trail, and work dispatches into sandboxed parallel runs. Durable

- operations go through the registered tool surface — never direct lifecycle

- subcommands, never a rebuild from source.

-

- This file is the router. It carries only what every Orbit call needs; each

- reference below is loaded on demand.

-

- ## Tool Invocation

-

- Use the connected, authoritative MCP server for durable work. First call

- `orbit_workspace_list`, select the intended workspace, and copy its selector

- into workspace-scoped calls. A direct server returns `ws_*` IDs; a federated

- server returns host-qualified `selector` values. Never infer authority from

- cwd or silently substitute a different machine's local store.

-

- Registered CLI tools use `orbit tool run orbit.task.add --input '{...}'`;

- MCP uses `orbit_task_add({...})`. Dots become underscores, but **CLI tool

- registration does not imply MCP exposure**. Discover the connected server's

- `tools/list` before calling. Use CLI administration on the intended host only

- when the operation and authority are available and authorized.

-

- Include `model` (`codex`, `claude`, `gemini`, or `grok`) on calls whose schema

- supports attribution. This is the agent family, not the crew or model ID.

- Follow each advertised schema for other fields; examples in these references

- use placeholders that must be replaced, not sent literally.

-

- Read [tool-surface.md](references/tool-surface.md) for the actual capability

- split, routing, structured examples, and missing-operation handling. Filesystem

- inspection and CLI-only diagnostics in these references refer to the host that

- owns the selected workspace. They do not authorize local shadow records.

-

- A plain `orbit_task_show` returns full detail; `field`/`fields` project it.

- If an activity already injected a task snapshot, use that envelope first.

-

- ## Lifecycle

-

- ```text

- proposed → backlog → in-progress → review → done

- ↘ rejected

-

- someday → backlog | in-progress

- blocked → backlog | in-progress

- review → backlog | in-progress | rejected

- rejected → backlog | in-progress (reconsider)

- any open status → blocked | archived

- ```

-

- Every status change goes through this table, whether you send it as

- `orbit.task.update` or as `task.start`/`task.approve`. Two rules are enforced

- and cannot be worked around from a tool call:

-

- - **`in-progress` needs a plan.** Starting from `proposed`, `someday`, or

- `blocked` requires a non-empty execution plan; send it on the same call.

- - **`done` is reachable only from `review`,** and needs completion evidence:

- a non-empty `execution_summary`, or a `job_run_id` whose run succeeded.

-

- `done` and `archived` are terminal, and a `rejected` task may only be

- reconsidered back to `backlog` or `in-progress`. A regression in delivered work

- is a *new* task with a `regression_from` relation — not a reopened one.

-

- Creating a task does not authorize dispatch or completion. Follow the user's

- approval and repository delivery policy. Use `blocked` when execution cannot

- safely continue. Provenance follows the surface: `orbit tool run ...` is

- agent-driven, bare `orbit task ...` is human-driven — and only a human can

- override the table, from the bare CLI with `orbit task update <id> --status

- <status> --force` or from the dashboard's status dropdown (off-table targets

- sit under a `force` group and take one confirmation). Either way the override

- is recorded in task history as a `forced` event. `orbit.task.update` and the

- MCP surface have no `force`.

-

- ## Common Mistakes — DO NOT

- | Mistake | Why it fails | Correct form |

- |---------|-------------|--------------|

- | `cargo run -- tool run ...` | Rebuilds from source instead of using the installed binary | `orbit tool run ...` |

- | `orbit task show <id>` | Direct CLI subcommands skip agent provenance tracking | `orbit tool run orbit.task.show --input '{"id":"<id>"}'` |

- | Editing task/friction projections or runtime evidence under `.orbit/` | File edits bypass the canonical store and audit contract | The matching registered tool; versioned config/resources are a separate admin surface |

- | Inventing a task ID | IDs are allocated by the store | `orbit.task.add` returns it |

- ## References

- **Working through Orbit** — doing the work itself:

- | Reference | Read it for |

- | [concepts.md](references/concepts.md) | What each Orbit noun means and how they nest. Read this first if the vocabulary is new. |

- | [tool-surface.md](references/tool-surface.md) | MCP versus CLI, workspace routing, authority, discovery, and common calls. |

- | [task-authoring.md](references/task-authoring.md) | Writing a task someone else can execute without guessing. |

- | [task-execution.md](references/task-execution.md) | Carrying a task from pickup to verified implementation and handoff. |

- | [task-review.md](references/task-review.md) | Reviewing someone else's work against its acceptance criteria. |

- | [search.md](references/search.md) | Finding prior tasks, docs, and frictions by topic, path, or related task. |

- | [docs-corpus.md](references/docs-corpus.md) | Authoring and registering the markdown corpus agents retrieve from. |

- | [friction.md](references/friction.md) | Recording what made the work harder than it should have been. |

- | [orchestration.md](references/orchestration.md) | Driving a backlog through: `orbit run ship`, `run auto`, and keeping parallel runs from colliding. |

- | [workflows.md](references/workflows.md) | Jobs, activities, and the `orbit run` surface. |

- | [run-debugging.md](references/run-debugging.md) | A `jrun-*` run that failed, stuck, or was cancelled. |

- | [common-failures.md](references/common-failures.md) | Matching a known failure signature to its remedy, once the failing step is identified. |

- | [operational-logs.md](references/operational-logs.md) | Host-level incidents: sweep service failures, tracing warnings, missing log output. |

-

- **Setting Orbit up** — configuring a machine or repository so work runs well.

- Use these references to configure the host and workspace. Scheduled automation

- is seeded disabled and requires deliberate enablement:

- | Reference | Read it for |

- |---|---|

- | [setup/first-run.md](references/setup/first-run.md) | Zero to a working workspace: install, host identity and task prefix, `workspace init`, MCP client registration, verification. |

- | [setup/linux-sandbox.md](references/setup/linux-sandbox.md) | Linux Bubblewrap/AppArmor prerequisite, capability probe, sandbox guarantees, and supported remediation before dispatch. |

- | [setup/configuration.md](references/setup/configuration.md) | `orbit config` keys, crews and executors, policies and filesystem profiles, environment passthrough. |

- | [setup/automation.md](references/setup/automation.md) | The scheduler: OS clock → `orbit sweep` → routines → jobs. The seven seeded routines and the order to enable them. |

- | [setup/auto-tasks.md](references/setup/auto-tasks.md) | Recurring work as data — definitions that mint tasks on a schedule, instead of new code. |

- | [setup/publication.md](references/setup/publication.md) | Publish task snapshots to a dedicated Git repository, inspect them, and restore on the owning authority. |

- | [setup/maintenance.md](references/setup/maintenance.md) | Worktree GC, `orbit doctor` repairs, log retention, audit pruning, upgrades. Skipping the first is what breaks busy workspaces. |

- | [setup/multi-host.md](references/setup/multi-host.md) | More than one machine: task-ID namespaces, independent per-host schedules, and what syncs versus what stays local. |

- | [setup/remote-access.md](references/setup/remote-access.md) | Reaching another machine's Orbit: the dashboard, `web connect`, and MCP over SSH or a socket. |

- ## Start here

- - New to Orbit, or `.orbit/` is absent → [concepts.md](references/concepts.md), then [setup/first-run.md](references/setup/first-run.md).

- - Preparing Linux for dispatch → [setup/linux-sandbox.md](references/setup/linux-sandbox.md) before starting an agent.

- - Given a task ID → [task-execution.md](references/task-execution.md).

- - Asked to create work → [task-authoring.md](references/task-authoring.md).

- - "Why didn't this fire / run / clean up?" → [setup/automation.md](references/setup/automation.md), then [setup/maintenance.md](references/setup/maintenance.md).

- - A run id in hand → [run-debugging.md](references/run-debugging.md).

- - Task backups, publication, or recovery → [setup/publication.md](references/setup/publication.md).

- - Multiple hosts, missing tools, or permission denials → [tool-surface.md](references/tool-surface.md), then [setup/remote-access.md](references/setup/remote-access.md).