agent-conveyor 0.1.0

package/dist/state/status.js

@@ -0,0 +1,40 @@
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { defaultDbPath, loadJsonSync, statusPath } from "./files.js";
+export function latestStatusSync(name, options = {}) {
+    const fallback = loadJsonSync(statusPath(name, options), {});
+    const dbPath = options.dbPath ?? defaultDbPath(options);
+    if (!existsSync(dbPath)) {
+        return fallback;
+    }
+    let database;
+    try {
+        database = new DatabaseSync(dbPath, { readOnly: true });
+        const row = database.prepare(`
+      select statuses.state, statuses.current_task, statuses.next_action,
+             statuses.blocker, statuses.created_at
+      from statuses
+      join workers on workers.id = statuses.worker_id
+      where workers.name = ?
+      order by statuses.id desc
+      limit 1
+    `).get(name);
+        if (!row) {
+            return fallback;
+        }
+        return {
+            blocker: row.blocker,
+            current_task: row.current_task ?? undefined,
+            last_update: row.created_at,
+            next_action: row.next_action ?? undefined,
+            state: row.state,
+        };
+    }
+    catch {
+        return fallback;
+    }
+    finally {
+        database?.close();
+    }
+}
+//# sourceMappingURL=status.js.map

package/dist/state/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/state/status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAkBrE,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,UAAsE,EAAE;IAExE,MAAM,QAAQ,GAAG,YAAY,CAAe,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,QAAkC,CAAC;IACvC,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC;;;;;;;;KAQ5B,CAAC,CAAC,GAAG,CAAC,IAAI,CAA0B,CAAC;QAEtC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,OAAO;YACL,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,SAAS;YAC3C,WAAW,EAAE,GAAG,CAAC,UAAU;YAC3B,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,SAAS;YACzC,KAAK,EAAE,GAAG,CAAC,KAAK;SACjB,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;YAAS,CAAC;QACT,QAAQ,EAAE,KAAK,EAAE,CAAC;IACpB,CAAC;AACH,CAAC"}

package/docs/typescript-migration/cli-contract.md

@@ -0,0 +1,147 @@
+# TypeScript Migration CLI Contract
+
+This contract freezes the current Python CLI surface before TypeScript migration.
+The TypeScript CLI must preserve this surface unless a Judge receipt explicitly
+approves and documents a diff.
+
+## Public Entry Points
+
+- `conveyor` package-installed command from `pyproject.toml`.
+- `workerctl` package-installed compatibility command from `pyproject.toml`.
+- `bin/conveyor` local wrapper.
+- `bin/workerctl` local wrapper.
+- `scripts/workerctl` repository-local entry point.
+- `python -m workerctl` until Python compatibility is retired by an explicit
+  migration decision.
+
+Program name behavior must preserve both `conveyor` and `workerctl`. The Python
+implementation currently selects the name from `CONVEYOR_CLI_PROG`, the
+invoked filename, or defaults to `conveyor`.
+
+## Command Inventory
+
+Source of truth: `scripts/workerctl --help` and `workerctl/cli.py`.
+
+The top-level command inventory to preserve is:
+
+```text
+create
+start
+start-test
+dashboard
+dispatch
+enqueue-notify-manager
+enqueue-nudge-worker
+enqueue-continue-iteration
+loop-templates
+loop-status
+loop-triggers
+loop-evidence
+ralph-loop-presets
+doctor
+doctor-self
+qa-plan
+qa-run
+create-disposable-binding
+install-skills
+db-doctor
+import-compat
+tasks
+criteria
+criteria-plan
+handoff
+worker-ack
+manager-ack
+runs
+telemetry
+manager-config
+manager-permission
+epilogue
+continuation
+continuation-reviewer
+record-decision
+register-worker
+start-worker
+start-manager
+pair
+register-manager
+deregister
+sessions
+discover
+search
+bind
+unbind
+ingest
+tail
+session-inbox
+manager-inbox
+worker-inbox
+session-nudge
+session-interrupt
+request-worker-compact
+compact-worker
+cycle
+divergences
+commands
+prune
+stop-task
+finish-task
+reconcile
+transcript-capture
+transcript-show
+transcript-prune
+audit
+mutation-audit
+replay
+export-task
+list
+capture
+status
+update-status
+idle-check
+events
+classify
+interrupt
+nudge
+open
+open-worker
+open-manager
+stop
+```
+
+`discover` and `search` are aliases and must remain compatible.
+
+## Behavioral Requirements
+
+- Preserve existing exit codes for success, argparse usage errors, and
+  `WorkerError`/`CodexSessionError`/`IngestError` failure paths.
+- Preserve JSON output shapes for commands that currently offer `--json`.
+- Preserve plain-text first lines for `conveyor --help` and `workerctl --help`:
+  `usage: conveyor` and `usage: workerctl`.
+- Preserve direct argv execution style. Do not route user-provided command text
+  through shell interpolation.
+- Preserve local `PATH` installer assumptions that `bin/conveyor` and
+  `bin/workerctl` are executable.
+- Preserve `--path` database override semantics on commands that currently
+  accept it.
+- Preserve `--dry-run` behavior on mutating or side-effecting commands that
+  currently expose dry-run.
+- Preserve no-judgment Dispatch boundary: Dispatch routes mechanical side
+  effects and must not decide task success, merge readiness, or acceptance
+  criteria truth.
+
+## Contract Drift Disproof Gate
+
+Before switching public entry points to TypeScript, run or produce an equivalent
+artifact for:
+
+```bash
+scripts/workerctl --help
+CONVEYOR_CLI_PROG=conveyor scripts/workerctl --help
+CONVEYOR_CLI_PROG=workerctl scripts/workerctl --help
+rg -n "add_parser\\(|set_defaults\\(" workerctl/cli.py
+```
+
+The TypeScript implementation must have an adjudicated command/flag diff against
+the Python surface. Unreviewed missing commands, missing aliases, changed JSON
+shape, or changed help program name block migration completion.

package/docs/typescript-migration/dashboard-contract.md

@@ -0,0 +1,76 @@
+# TypeScript Migration Dashboard Contract
+
+The dashboard is already TypeScript and must remain green throughout the CLI
+migration.
+
+## Current TS Patterns To Preserve
+
+- Root package uses ESM (`"type": "module"`).
+- Dashboard runtime uses `tsx dashboard/server/index.ts`.
+- Dashboard tests use native `node:test` through
+  `dashboard/scripts/run-tests.mjs`.
+- Local TS imports use explicit `.ts` extensions.
+- `dashboard/tsconfig.json` is strict, no-emit, and dashboard-scoped.
+- Workerctl dashboard integration builds argv arrays directly and avoids shell
+  interpolation.
+- PTY/tmux attach validates unsafe session names before spawning.
+- Dashboard server tolerates optional audit/snapshot telemetry failures where
+  current behavior does.
+
+## Current Dashboard Test Coverage
+
+`dashboard/server/workerctl.test.ts` currently covers:
+
+- workerctl argv builders
+- snapshot/audit/telemetry/task commands
+- bind/create/pair/nudge/interrupt/finish/export args
+- Dispatch correlation chains
+- inbox delivery and consumption evidence
+- blocked loop policy
+- Dispatch heartbeat and health summaries
+- terminal session name safety
+- resize/control message parsing
+
+The TS CLI migration must not remove this coverage or make dashboard tests pass
+by stubbing out meaningful CLI behavior.
+
+## Shared Code Boundary
+
+Future shared TS CLI code should be introduced in a separate distributable
+boundary, such as `src/**`, and imported by dashboard code only where it remains
+browser/server-safe. Do not import `dashboard/server/index.ts` from CLI code.
+Avoid dragging Vite/React/browser dependencies into the CLI runtime.
+
+## T012 Runtime Boundary
+
+T012 moves the dashboard's default workerctl path to the Node CLI command
+`conveyor`. The dashboard may still accept an explicit `--workerctl-path` such
+as `scripts/workerctl` for local compatibility, but default dashboard JSON
+subprocesses should no longer depend on the Python wrapper.
+
+The dashboard command builder must construct direct argv arrays for the same
+CLI contracts users can run from `conveyor`: discovery, telemetry snapshots,
+audit, replay, task listing/creation, bind, pair, cycle, session nudge,
+session interrupt, finish, and export. Do not reintroduce dashboard-only
+`--ts-runtime` allowlists; migrated dashboard command targets are owned by the
+default TypeScript runtime.
+
+## Verification
+
+Required checks after dashboard-facing changes:
+
+```bash
+npm test -- --runInBand
+npm run build
+```
+
+For frontend/dashboard user-facing changes, add browser inspection or screenshot
+evidence according to `docs/agent-evidence-playbook.md`.
+
+## Contract Drift Disproof Gate
+
+The strongest dashboard-specific failure mode is a TS CLI refactor that leaves
+unit tests green but breaks live dashboard command execution or PTY safety.
+Disproof requires both argv/terminal tests and, for dashboard behavior changes,
+an actual dashboard or browser-backed check that the page can still issue safe
+commands through the expected executable.

package/docs/typescript-migration/package-install-contract.md

@@ -0,0 +1,98 @@
+# TypeScript Migration Package And Install Contract
+
+The npm package name is `agent-conveyor`.
+
+As of the pre-board and T001 checks:
+
+- `npm whoami` returned `neonwatty`.
+- `npm view agent-conveyor name version --json` returned npm E404.
+- The pre-migration `package.json` was private dashboard tooling, not a
+  publishable CLI package.
+- The pre-migration `pyproject.toml` was the authoritative package metadata for
+  the Python package.
+
+The package name must be re-checked near final packaging and before any publish
+handoff because registry state can change.
+
+## Historical Python Package Contract
+
+Before the TypeScript packaging tranche, install docs used the Python package
+path: `pipx install agent-conveyor`, followed by `conveyor install-skills` and
+`conveyor doctor`. That path is retained here only as historical contract
+context for migration review, not as the current primary install instruction.
+
+The historical Python metadata exposed:
+
+- package name `agent-conveyor`
+- console script `conveyor`
+- compatibility console script `workerctl`
+- bundled `workerctl/assets/skills/**/*`
+
+The historical wheel package smoke proved:
+
+- wheel builds
+- installed `conveyor --help` starts with `usage: conveyor`
+- installed `workerctl --help` starts with `usage: workerctl`
+- `install-skills --json` installs expected skills
+- installed `codex-review/scripts/codex-review` is executable
+- installed `manage-codex-workers` skill does not contain stale copyable legacy
+  command text
+
+## Current npm Package Contract
+
+The TypeScript migration now produces an npm package that:
+
+- is named `agent-conveyor`
+- is not `private`
+- declares supported Node engines
+- exposes `bin.conveyor`
+- exposes `bin.workerctl`
+- includes built CLI code
+- includes required dashboard assets if dashboard remains part of the package
+- includes top-level `skills/**` bundled skill assets
+- preserves executable mode for the installed `codex-review` helper
+- excludes `scripts/workerctl`, `workerctl/**/*.py`, and
+  `dist/cli/python-bridge.*`
+- avoids automatic npm publish from local scripts or CI unless explicitly
+  approved by the operator
+
+## Runtime Cutover Boundary
+
+The npm package exposes the Node `conveyor` and `workerctl` bins without the
+Python bridge or packaged Python runtime. The source tree can still retain the
+historical Python implementation and compatibility tests, but normal npm
+package operation must be TypeScript-owned.
+
+## Tarball Smoke Contract
+
+Before any public publish, the board must prove a local tarball install:
+
+```bash
+npm pack --json
+tmp_prefix="$(mktemp -d)"
+npm install -g --prefix "$tmp_prefix" ./agent-conveyor-*.tgz
+PATH="$tmp_prefix/bin:$PATH" conveyor --help
+PATH="$tmp_prefix/bin:$PATH" workerctl --help
+CODEX_HOME="$(mktemp -d)" PATH="$tmp_prefix/bin:$PATH" conveyor install-skills --json
+```
+
+The smoke must inspect:
+
+- both commands resolve from `PATH`
+- both help first lines are correct
+- installed skill files exist
+- `codex-review/scripts/codex-review` is executable
+- no Python runtime, Python bridge, or `scripts/workerctl` files are packed
+- npm tarball contents include only intended package files
+
+## Docs And CI Contract
+
+Docs and CI must use npm as the primary path. Stale Python package publish or
+install commands may remain only as historical migration notes or temporary
+compatibility instructions with explicit labels.
+
+## Publish Constraint
+
+Preparing package metadata, tarball, install smoke, CI, and docs is approved.
+Publishing `agent-conveyor` to npm is not approved for autonomous overnight work
+and must remain a blocked/operator-approved final action.

package/docs/typescript-migration/qa-gate-matrix.md

@@ -0,0 +1,103 @@
+# TypeScript Migration QA Gate Matrix
+
+The migration must preserve the existing evidence ladder from
+`docs/agent-evidence-playbook.md`: name the strongest realistic failure mode,
+run or inspect evidence that would expose it, and record residual risk.
+
+## Deterministic Local Gates
+
+Current baseline before the migration board:
+
+| Gate | Command | Current baseline |
+| --- | --- | --- |
+| Python unit tests | `python3 -m unittest discover -s tests -v` | pass, 645 tests |
+| ResourceWarning gate | `scripts/check-resource-warnings` | pass, 645 tests |
+| Python compile gate | `python3 -m py_compile scripts/workerctl scripts/check-resource-warnings workerctl/*.py` | pass |
+| Node/dashboard tests | `npm test -- --runInBand` | pass, 161 tests |
+| Dashboard build | `npm run build` | pass |
+| TypeScript migration audit | `npm run migration:audit:final` | pass after package cutover; npm tarball has no Python runtime/bridge files |
+| Shell syntax | `bash -n scripts/live-smoke scripts/live-smoke-repeat scripts/package-smoke scripts/release-check scripts/rc-check` | pass |
+
+While Python remains in the repository, the Python gates remain required. A
+TypeScript replacement may retire them only after equivalent TypeScript gates
+and package smoke prove the migrated command surface no longer imports or
+executes Python for the migrated paths.
+
+## Release-Candidate Gate
+
+`scripts/rc-check --skip-live-smoke-repeat` currently runs:
+
+- Python unittest.
+- ResourceWarning gate.
+- Python compile gate.
+- TypeScript migration audit.
+- Dashboard tests.
+- Dashboard build.
+- Smoke script syntax checks.
+
+The TypeScript migration must keep an equivalent deterministic RC gate. Broad
+CLI, Dispatch, dashboard, or packaging changes should use the RC gate before
+PR/merge claims.
+
+## Package And Release Gates
+
+Current gates are Python wheel/sdist based:
+
+- `scripts/package-smoke`
+- `scripts/release-check`
+- `.github/workflows/publish.yml`
+- `docs/package-release.md`
+
+The migration must replace these with npm tarball semantics while preserving:
+
+- `conveyor --help`
+- `workerctl --help`
+- `install-skills --json`
+- bundled `manage-codex-workers` and `codex-review` assets
+- executable `codex-review/scripts/codex-review`
+- stale command text guard for installed skills
+- TypeScript migration audit receipt; Board 13/14 must use
+  `npm run migration:audit:final` after Python runtime removal.
+
+## Live And Manual QA Gates
+
+Live gates depend on local `tmux`, `codex`, and environment state:
+
+- `scripts/live-smoke`
+- `scripts/live-smoke-repeat 3`
+- `scripts/workerctl sessions --state active`
+- `scripts/workerctl reconcile --stale-cycles-seconds 1`
+
+Manual and receipt-driven gates include:
+
+- `docs/manual-qa-checklist.md`
+- `docs/qa/README.md`
+- `docs/qa/evidence-template.md`
+- `conveyor qa-run ralph-loop-guardrails`
+- `conveyor qa-run generic-loop-template`
+- `conveyor qa-run generic-loop-template-browser`
+- `conveyor qa-run test-coverage-loop`
+- `conveyor qa-run adversarial-triggers`
+- `conveyor qa-run build-clear-loop`
+
+If live Codex/tmux is unavailable, record that as a specific blocker for the
+live gate and continue deterministic local work.
+
+## CI Gates
+
+Current CI:
+
+- `.github/workflows/test.yml` uses macOS, Node 24, `npm ci`,
+  `scripts/rc-check --skip-live-smoke-repeat`, and `scripts/package-smoke`.
+- `.github/workflows/live-smoke.yml` runs `scripts/live-smoke` only when Codex
+  CLI is available.
+- `.github/workflows/publish.yml` verifies the npm package artifact on manual
+  dispatch and must not become an automatic npm publish path during autonomous
+  overnight work.
+
+## Strongest QA Failure Mode
+
+The migration can appear done while the test suite only proves the dashboard or
+new TS happy path. Completion is blocked until the QA matrix proves CLI,
+database, tmux/Codex ingest, Dispatch, skill install, packaging, dashboard, and
+docs/release contracts are either preserved or explicitly adjudicated.

package/docs/typescript-migration/sqlite-state-contract.md

@@ -0,0 +1,92 @@
+# TypeScript Migration SQLite And State Contract
+
+This contract freezes the current Python state model and SQLite compatibility
+surface before TypeScript migration.
+
+## State Root
+
+- Default state root is `.codex-workers` under the invocation cwd.
+- `WORKERCTL_STATE_ROOT` overrides the default root.
+- Current Python code captures invocation cwd at import time; any TypeScript
+  replacement must preserve the observable default cwd behavior or record a
+  Judge-approved intentional diff.
+
+## Compatibility Files
+
+The SQLite database is the richer source of truth, but legacy compatibility
+files remain part of the contract:
+
+- `config.json`
+- `status.json`
+- `events.jsonl`
+- `transcript.txt`
+- `capture-meta.json`
+
+The status read path must preserve the current fallback behavior: prefer SQLite
+status rows when available, but tolerate JSON-only legacy status fixtures.
+
+## SQLite Contract
+
+Current schema version: `22`.
+
+The TypeScript implementation must preserve:
+
+- `PRAGMA foreign_keys = ON`
+- WAL journal mode behavior
+- busy timeout behavior
+- refusal to open a database with a future unsupported schema version
+- migration self-healing behavior covered by the Python test suite
+- required tables, indexes, triggers, check constraints, and foreign keys
+
+Required table groups include:
+
+- sessions and workers/managers
+- tasks and bindings
+- statuses and terminal/transcript captures
+- prompts, acknowledgements, handoffs, continuations, and configs
+- manager cycles and phase spans
+- runs, telemetry events, and telemetry FTS
+- durable commands, attempts, routed notifications, and command budgets
+- acceptance criteria
+- Codex events and ingest offsets
+- audit/export/replay support tables
+
+## Parity Evidence Required
+
+Before TypeScript owns database creation or migration, create a Python-empty DB
+and a TypeScript-empty DB in temp state roots and compare:
+
+- `PRAGMA user_version`
+- `.schema`
+- table names
+- index names
+- trigger names
+- critical PRAGMAs
+
+Unreviewed diffs block the migration. A schema v23 bump is allowed only as a
+separate Judge-approved migration task with backwards-compatibility tests.
+
+## Fixture Requirements
+
+The TypeScript port needs deterministic fixtures for:
+
+- JSON-only status fallback.
+- Existing SQLite status preferred over stale JSON status.
+- Future schema version rejection.
+- v4/v5/v6/v21-style migration cases currently covered in Python tests.
+- `WORKERCTL_STATE_ROOT` isolation.
+- Append-only events behavior.
+- Acceptance criteria uniqueness and status/source constraints.
+
+## Contract Drift Disproof Gate
+
+Useful commands:
+
+```bash
+WORKERCTL_STATE_ROOT="$(mktemp -d)" scripts/workerctl db-doctor --json
+python3 -m unittest tests.test_workerctl.DatabaseTests tests.test_workerctl.SessionsSchemaTests tests.test_workerctl.CodexEventsSchemaTests -v
+python3 -m py_compile workerctl/*.py
+```
+
+Completion is blocked if the TypeScript-created schema differs from the
+Python-created schema without a recorded Judge decision.

package/docs/typescript-migration/t005-runtime-parity.md

@@ -0,0 +1,47 @@
+# T005 Runtime Parity Audit
+
+T005 ports the tmux, Codex rollout discovery, JSONL ingest, and classifier
+runtime layer into TypeScript without switching the public CLI command handlers
+away from the compatibility bridge yet.
+
+## Ported TypeScript Surfaces
+
+| Python source | TypeScript source | Proof |
+| --- | --- | --- |
+| `workerctl/tmux.py` command builders, permission text, paste-buffer cleanup, session pane targeting | `src/runtime/tmux.ts` | `src/runtime/runtime.test.ts` covers argument order, liveness checks, permission normalization, cleanup on failure, pane targets, and side-effect audit flags. |
+| `workerctl/codex_session.py` session metadata, native pid selection, lsof rollout lookup, discovery result shape | `src/runtime/codex-session.ts` | `src/runtime/runtime.test.ts` covers metadata parsing, lsof path extraction, pid-to-native-child selection, and end-to-end discovery with fixtures. |
+| `workerctl/ingest.py` JSONL parser and one-session ingest cycle | `src/runtime/ingest.ts` | `src/runtime/runtime.test.ts` covers offsets, malformed complete lines, partial trailing lines, event persistence, heartbeat/offset update, telemetry, idempotent re-ingest, appended partial completion, and shrink refusal. |
+| `workerctl/classify.py` startup and busy-wait classifier | `src/runtime/classify.ts` | `src/runtime/runtime.test.ts` covers Python classifier scenarios: trust, ready, working, empty, error, MCP startup, rate limit, Enter confirmation, trust prompt, plan prompt, active approval, historical approval negative control, fresh status suppression, and recent-event long-running suppression. |
+
+## Bridge Decision
+
+Public `conveyor` and `workerctl` command handlers still intentionally route
+through `src/cli/python-bridge.ts` for T005. That preserves the frozen CLI
+contract while the runtime modules move to TypeScript in testable pieces.
+
+The remaining command-handler migration belongs to T006/T007:
+
+- T006 owns lifecycle, Dispatch, inbox, audit/replay/export, and
+  dashboard-facing CLI behavior.
+- T007 owns npm package/install/release/CI/docs conversion and final tarball
+  behavior.
+
+This means T005 is complete when the TypeScript runtime helpers pass local
+gates and the Python compatibility suite still passes. It does not claim that
+the public CLI no longer executes Python.
+
+## Strongest Failure Mode
+
+The strongest realistic T005 failure mode is a false sense of migration
+progress: helper functions pass in TypeScript, but a live/public command path
+silently changes tmux target selection, rollout offsets, classifier decisions,
+or CLI error behavior.
+
+Disproof evidence:
+
+- Node runtime tests exercise the TypeScript behavior directly.
+- The full Python compatibility suite still passes under an isolated state
+  root, proving the bridge-backed public CLI behavior was not regressed.
+- `npm run build` proves the TypeScript helper API compiles into the package.
+- The GoalBuddy board keeps T006/T007 queued for public command-handler and
+  package-routing migration before final completion.