outfitter-dispatch 0.2.1__tar.gz → 0.7.0__tar.gz

{outfitter_dispatch-0.2.1 → outfitter_dispatch-0.7.0}/.gitignore

@@ -27,3 +27,5 @@ dist/
 # Local Claude settings (per-machine; e.g. bg-isolation opt-out for Graphite stacking)
 .claude/settings.local.json
 .claude/worktrees/
+# Staged launch sessions (runtime artifacts, local only).
+.agents/sessions/

{outfitter_dispatch-0.2.1 → outfitter_dispatch-0.7.0}/AGENTS.md

@@ -14,6 +14,7 @@ just test        # pytest
 just lint        # ruff check
 just fmt         # ruff format
 just typecheck   # mypy --strict
+just scenario -- tests/scenarios/basic_coordination.toml
 just run -- ...   # run the dispatch CLI in-tree
 uv run dispatch --help
 uv run dispatchd --help
@@ -33,6 +34,8 @@ dispatch owns one `codex app-server` subprocess (stdio JSONL, shared `~/.codex`)
 - `docs/usage/` — operator docs for the CLI, MCP, triggers, and plugin setup.
 - `.agents/plans/v0/` — phased plan (`PLAN.md`) + references (`REFS.md`); tracked.
 - `spikes/` — App Server probe scripts; seed of the integration suite.
+- `tests/fixtures/` — small named App Server, JSONL, CLI-smoke, and registry fixtures.
+- `tests/scenarios/` — live agent workflow fixtures run intentionally with `just scenario`.
 - `.agents/notes/` — working notes, session recaps, learnings; **gitignored, local only**.
 - `skills/` — first-party Codex skills for operating dispatch (`dispatch`) and dispatch-backed direct messages (`dm`).
 - `plugins/dispatch/` — workspace-local Codex plugin bundle exposing the skills and MCP server.
@@ -43,12 +46,14 @@ Read `docs/development/design.md` and `.agents/plans/v0/PLAN.md` before implemen
 
 Use the project language consistently:
 
-- **lane** — a managed Codex thread (own or attached). Not "thread", "agent", or "unit" in user-facing text.
+- **lane** — internal term for a managed Codex thread (own or attached) with registry state.
+- **thread** — user-facing Codex conversation/session. Public CLI/help/docs should prefer "thread" unless the managed-lane authority distinction matters.
+- **ref** — dispatch-local short stable selector for a managed lane. Full Codex thread ids are always accepted; titles and `@handles` are mutable labels.
 - **op** — one authored operation (input/output/intent/examples/handler). The contract unit. Not "command" or "tool" (those are surface projections of an op).
 - **surface** — a derived rendering of the op registry: CLI, MCP, remote. Surfaces are projected, never hand-written per-op.
 - **trigger** — an automated when→action→lane binding (time or event). Not "rule" (collides with agent rules), "automation", or "job".
 - **daemon** (`dispatchd`) — the long-lived host owning the app-server and core; the CLI is a thin client to it.
-- **register/registry** — the durable store of lanes and triggers.
+- **register/registry** — the durable store of lanes, refs, sync state, and triggers.
 
 ## Core rules (summary; full detail in `.claude/rules/`)
 
@@ -62,6 +67,8 @@ Use the project language consistently:
 - **App Server access only via `client/`.** Never spawn or speak to `codex app-server` outside the client layer. See [client rules](.claude/rules/client.md).
 - **Async core, sync CLI.** The daemon is asyncio end-to-end; the CLI is a thin sync client over the control socket. No blocking calls in the loop (use `aiosqlite`, asyncio subprocess, `run_in_executor`). See [python-conventions](.claude/rules/python-conventions.md).
 - **Never touch the user's live state in tests.** Integration tests use a real ephemeral app-server with an isolated `CODEX_HOME` and `ephemeral:true` lanes.
+- **Fixtures should be exercised.** Add checked-in cases under `tests/fixtures/` only when a test loads them; prefer Python builders over binary SQLite fixtures.
+- **Live scenarios are opt-in.** Scenario fixtures start real isolated Dispatch/Codex daemons and make model calls; keep them small, synthetic, low-effort, and outside `just check`.
 
 ## Source control
 

{outfitter_dispatch-0.2.1 → outfitter_dispatch-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: outfitter-dispatch
-Version: 0.2.1
+Version: 0.7.0
 Summary: Local control plane for orchestrating Codex agent lanes over the Codex App Server.
 Project-URL: Homepage, https://github.com/outfitter-dev/dispatch
 Project-URL: Repository, https://github.com/outfitter-dev/dispatch
@@ -32,6 +32,8 @@ uv tool install outfitter-dispatch
 dispatch --help
 dispatchd --help
 dispatch doctor
+dispatch up --json
+dispatch down --json
 ```
 
 From a source checkout:
@@ -40,34 +42,62 @@ From a source checkout:
 uv sync
 uv run dispatch --help
 uv run dispatch doctor --no-app-server
-uv run dispatch up
+uv run dispatch models --no-refresh
+uv run dispatch up --json
 uv run dispatch daemon status
 ```
 
-Open an owned lane, send it work, and inspect the daemon:
+Create an owned managed thread, send it work, and inspect the daemon:
 
 ```bash
 uv run dispatch new \
   --name docs \
   --cwd /path/to/dispatch \
+  --goal "Finish the docs review." \
   --text "Please summarize the current stack state."
-uv run dispatch lane tail "@[dispatch] docs" --limit 20
-uv run dispatch goal set "@[dispatch] docs" "Finish the docs review."
+uv run dispatch list
+uv run dispatch get <dispatch-ref>
+uv run dispatch tail <dispatch-ref> --limit 20
 uv run dispatch daemon log --limit 10
-uv run dispatch down
+uv run dispatch down --json
 ```
 
-Use owned lanes for writes. Existing desktop Codex threads can be attached, but v0 treats
-attached lanes as observe-only: mutating commands such as `send`, `stop`, `lane archive`,
-`goal set`, `goal clear`, `lane fork`, `lane rollback`, and `lane compact` are blocked by
-ADR-0005.
+For durable or parallel launches, point `new` at a launch packet directory and
+preview it without side effects: `dispatch new --name lane-a --cwd /repo --packet
+./packet --dry-run --json`, then `--stage all` to write durable session files under
+`.agents/sessions/<ref>/`. See [`docs/usage/README.md`](docs/usage/README.md) for
+packet layout, file/stdin inputs, and staging.
+
+Use owned managed threads for turn-writing work. Existing desktop Codex threads can be attached as
+managed threads, but ADR-0005 blocks turn-writing and history-mutating commands such
+as `send`, `stop`, `goal set`, and `goal clear` on attached lanes by default. A
+local operator can explicitly opt in with `[policy] allow_attached_writes = true`
+in `~/.dispatch/config.toml`; `list --json` and `get --json` expose
+`writable`, `capabilities`, and `write_locked_reason` so scripts can tell which
+lanes can receive writes. Every managed thread has a dispatch-local `ref`; full
+Codex thread UUIDs remain accepted everywhere.
+Titles and `@handles` are mutable convenience labels, not stable identity. Metadata
+lifecycle actions (`rename`, `archive`, `restore`) can target managed refs or raw
+unmanaged Codex thread ids, and `search` can span both. Attach is metadata-only by
+default; use `dispatch sync <selector>` when you want dispatch to refresh its local
+indexed view of an attached thread.
+
+`new` reports whether the first message was accepted by the App Server, not whether
+assistant work completed. Use `get` to inspect the latest turn state and persisted
+App Server errors, or `watch` for a bounded live event sample. Slash commands in
+`--text` are plain text; use `--goal` when creating a native App Server goal.
+Use `dispatch models` before pinning model or service-tier presets; Dispatch
+resolves aliases such as `fast` from the live App Server model catalog and keeps
+omitted model/tier values on Codex defaults.
 
 For the operator guide, CLI/MCP examples, triggers, and plugin setup, start at
 [`docs/usage/README.md`](docs/usage/README.md).
 
 Start troubleshooting with `dispatch doctor`. It checks PATH visibility, the Codex CLI
 and auth footprint, daemon socket/pidfile state, registry schema/integrity, packaged
-skills/plugin assets, and a low-risk Codex App Server initialize smoke.
+skills/plugin assets, and a low-risk Codex App Server initialize smoke. If doctor reports
+an old registry schema, stop the daemon and run `dispatch registry migrate` before
+starting it again.
 
 ## Agent And Plugin Support
 

outfitter_dispatch-0.7.0/README.md

@@ -0,0 +1,103 @@
+# dispatch
+
+Local control plane for orchestrating Codex agent lanes over the Codex App Server.
+One authored contract per operation, projected to CLI + MCP (+ remote later) with no drift.
+
+## Quick Start
+
+Install the CLI from PyPI:
+
+```bash
+uv tool install outfitter-dispatch
+dispatch --help
+dispatchd --help
+dispatch doctor
+dispatch up --json
+dispatch down --json
+```
+
+From a source checkout:
+
+```bash
+uv sync
+uv run dispatch --help
+uv run dispatch doctor --no-app-server
+uv run dispatch models --no-refresh
+uv run dispatch up --json
+uv run dispatch daemon status
+```
+
+Create an owned managed thread, send it work, and inspect the daemon:
+
+```bash
+uv run dispatch new \
+  --name docs \
+  --cwd /path/to/dispatch \
+  --goal "Finish the docs review." \
+  --text "Please summarize the current stack state."
+uv run dispatch list
+uv run dispatch get <dispatch-ref>
+uv run dispatch tail <dispatch-ref> --limit 20
+uv run dispatch daemon log --limit 10
+uv run dispatch down --json
+```
+
+For durable or parallel launches, point `new` at a launch packet directory and
+preview it without side effects: `dispatch new --name lane-a --cwd /repo --packet
+./packet --dry-run --json`, then `--stage all` to write durable session files under
+`.agents/sessions/<ref>/`. See [`docs/usage/README.md`](docs/usage/README.md) for
+packet layout, file/stdin inputs, and staging.
+
+Use owned managed threads for turn-writing work. Existing desktop Codex threads can be attached as
+managed threads, but ADR-0005 blocks turn-writing and history-mutating commands such
+as `send`, `stop`, `goal set`, and `goal clear` on attached lanes by default. A
+local operator can explicitly opt in with `[policy] allow_attached_writes = true`
+in `~/.dispatch/config.toml`; `list --json` and `get --json` expose
+`writable`, `capabilities`, and `write_locked_reason` so scripts can tell which
+lanes can receive writes. Every managed thread has a dispatch-local `ref`; full
+Codex thread UUIDs remain accepted everywhere.
+Titles and `@handles` are mutable convenience labels, not stable identity. Metadata
+lifecycle actions (`rename`, `archive`, `restore`) can target managed refs or raw
+unmanaged Codex thread ids, and `search` can span both. Attach is metadata-only by
+default; use `dispatch sync <selector>` when you want dispatch to refresh its local
+indexed view of an attached thread.
+
+`new` reports whether the first message was accepted by the App Server, not whether
+assistant work completed. Use `get` to inspect the latest turn state and persisted
+App Server errors, or `watch` for a bounded live event sample. Slash commands in
+`--text` are plain text; use `--goal` when creating a native App Server goal.
+Use `dispatch models` before pinning model or service-tier presets; Dispatch
+resolves aliases such as `fast` from the live App Server model catalog and keeps
+omitted model/tier values on Codex defaults.
+
+For the operator guide, CLI/MCP examples, triggers, and plugin setup, start at
+[`docs/usage/README.md`](docs/usage/README.md).
+
+Start troubleshooting with `dispatch doctor`. It checks PATH visibility, the Codex CLI
+and auth footprint, daemon socket/pidfile state, registry schema/integrity, packaged
+skills/plugin assets, and a low-risk Codex App Server initialize smoke. If doctor reports
+an old registry schema, stop the daemon and run `dispatch registry migrate` before
+starting it again.
+
+## Agent And Plugin Support
+
+This repo ships first-party skills in [`skills/`](skills/):
+
+- [`skills/dispatch/SKILL.md`](skills/dispatch/SKILL.md) teaches agents how to operate
+  dispatch safely.
+- [`skills/dm/SKILL.md`](skills/dm/SKILL.md) is the dispatch-backed "dispatch message"
+  workflow for short inter-lane messages.
+
+The workspace-local Codex plugin bundle lives at [`plugins/dispatch/`](plugins/dispatch/),
+with a marketplace entry in [`.agents/plugins/marketplace.json`](.agents/plugins/marketplace.json).
+Restart Codex if the plugin does not appear immediately.
+
+## Project Docs
+
+- [`docs/development/design.md`](docs/development/design.md) - architecture and design notes.
+- [`docs/adrs/`](docs/adrs/) - accepted architecture decisions.
+- [`docs/research/`](docs/research/) - verified Codex App Server findings.
+- [`.agents/plans/v0/RETRO.md`](.agents/plans/v0/RETRO.md) - v0 execution ledger and
+  verification record.
+
+For contributors, [`AGENTS.md`](AGENTS.md) is the canonical fieldguide.

{outfitter_dispatch-0.2.1 → outfitter_dispatch-0.7.0}/justfile

@@ -6,6 +6,7 @@ check:
     uv run ruff format --check .
     uv run mypy src tests
     uv run pytest
+    rm -f dist/*.whl dist/*.tar.gz
     uv build
     uv run python scripts/check_package_contents.py
 
@@ -17,6 +18,14 @@ test *args:
 test-int *args:
     uv run pytest -m integration {{args}}
 
+# Smoke-test the published PyPI package from a clean temporary DISPATCH_HOME.
+pypi-smoke *args:
+    uv run python scripts/check_pypi_smoke.py {{args}}
+
+# Run a live agent scenario against an isolated DISPATCH_HOME/CODEX_HOME.
+scenario *args:
+    uv run python scripts/run_scenario.py {{args}}
+
 # Lint with ruff.
 lint:
     uv run ruff check .

{outfitter_dispatch-0.2.1 → outfitter_dispatch-0.7.0}/plugins/dispatch/README.md

@@ -8,16 +8,25 @@ This workspace-local plugin exposes:
   `dispatch mcp`.
 
 The MCP server and skills expose the same derived operation registry as the CLI,
-including lane creation/messaging, bounded tails, native goals, history controls,
-triggers, schemas, and daemon status/log reads.
+including managed-thread creation/messaging, dispatch refs, persisted `tail`,
+bounded live `watch`, native goals, triggers, schemas, model catalog reads, and
+daemon status/log reads.
+`new --goal` creates native App Server goal state; `/goal ...` in message text is
+plain text and should not be used as a goal substitute. `new` also accepts launch
+packets (`--packet DIR`), file/stdin inputs (`--goal-file`/`--input-file`/
+`--output-schema-file`, `-` for stdin), a mutation-free `--dry-run`, and durable
+staging (`--stage all|<parts>` → `.agents/sessions/<ref>/`).
+Use `dispatch models` or the MCP daemon-read `models` op before pinning explicit
+model/service-tier presets.
 
 Run `dispatch doctor` after installing or upgrading dispatch. It verifies the CLI
 entrypoints, Codex CLI/auth footprint, daemon socket/pidfile state, registry
 schema/integrity, packaged skills/plugin assets, and a low-risk App Server
 initialize smoke. Use `dispatch doctor --no-app-server` when you only want local
-install checks.
+install checks. If doctor reports an old registry schema, run `dispatch down`,
+`dispatch registry migrate`, then `dispatch up`.
 
-Run `dispatch up` before MCP tool calls that need the daemon. `dispatch mcp`
+Run `dispatch up --json` before MCP tool calls that need the daemon. `dispatch mcp`
 serves the derived tools over stdio; the daemon remains the executor.
 
 `skills` is a symlink to the repo-root [`../../skills`](../../skills) tree so the plugin