@kbediako/codex-orchestrator 0.1.37 → 0.2.0

package/docs/public/downstream-setup.md

@@ -0,0 +1,106 @@
+# Downstream Setup
+
+This guide is the downstream-safe setup path shipped in the npm package.
+
+## Contract
+
+- Once per machine: install Codex CLI, authenticate, install bundled skills, and register delegation or DevTools wiring.
+- Once per repo: seed the CO templates, review the generated config, and start using task-scoped runs.
+- CO currently targets Codex CLI `0.123.0`; newer candidates stay evidence-gated in the version policy.
+- CO-196 posture lineage remains unchanged: npm is the supported baseline because it is the simplest supported CLI install path, and marketplace packaging is an additive registration path for newer Codex releases that expose `codex plugin marketplace add` and `codex plugin marketplace remove`.
+
+## Once per machine
+
+1. Install CO:
+   ```bash
+   npm i -g @kbediako/codex-orchestrator
+   ```
+2. Authenticate Codex:
+   ```bash
+   codex login
+   # If browser auth is unavailable:
+   codex login --device-auth
+   ```
+3. Install bundled skills and register delegation or DevTools wiring:
+   ```bash
+   codex-orchestrator setup --yes
+   ```
+4. Check readiness:
+   ```bash
+   codex-orchestrator doctor --format json
+   ```
+
+## Codex plugin marketplace install
+
+Use this when you want Codex to discover and enable CO from the plugin browser, while keeping npm available as the baseline CLI install path.
+
+1. Add the packaged marketplace root:
+   ```bash
+   codex plugin marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
+   ```
+2. Open `/plugins` inside Codex.
+3. Install `Codex Orchestrator`.
+4. Restart Codex if the plugin does not appear immediately.
+
+The shipped marketplace files are:
+
+- `.agents/plugins/marketplace.json`
+- `plugins/codex-orchestrator/.codex-plugin/plugin.json`
+- `plugins/codex-orchestrator/.mcp.json`
+- `plugins/codex-orchestrator/launcher.mjs`
+
+- Launcher behaviour: The plugin entry points at `plugins/codex-orchestrator`, and its launcher reads the `codex-orchestrator` marketplace entry in `${CODEX_HOME:-~/.codex}/config.toml` to locate the recorded source checkout before it execs the packaged CO CLI there via `node`. Local-directory sources run from the recorded source path. Git-backed sources run from Codex's installed checkout under `${CODEX_HOME:-~/.codex}/.tmp/marketplaces/codex-orchestrator`, so the MCP registration path stays independent of a second `codex-orchestrator` path entry after install.
+- Local-directory add: Run `codex plugin marketplace add <repository-root>` against the repository root that contains those files instead of the npm install directory.
+- Git-backed add: Pass a Git identifier or URL such as `owner/repo[@ref]`, an HTTPS Git URL, or an SSH Git URL rather than a local path.
+- When to re-run add: Re-run `codex plugin marketplace add ...` if you move or replace a local-directory source, or if you remove Codex's installed marketplace checkout and want to restore the Git-backed install. `codex plugin marketplace add --help` currently documents local directories plus Git-backed sources such as `owner/repo[@ref]`, HTTPS Git URLs, and SSH Git URLs.
+
+## Rollback and removal
+
+- Uninstall the plugin from the Codex plugin browser when you want to remove it completely.
+- Set the plugin entry in `${CODEX_HOME:-~/.codex}/config.toml` to `enabled = false` when you want to keep it installed but turn it off.
+- Remove the marketplace registration if you no longer want Codex to read the shipped marketplace source:
+  ```bash
+  codex plugin marketplace remove codex-orchestrator
+  ```
+- Remove the npm install when you no longer want the standalone CLI or when you no longer need it as the marketplace source:
+  ```bash
+  npm uninstall -g @kbediako/codex-orchestrator
+  ```
+
+## Once per repo
+
+1. Seed the repo:
+   ```bash
+   codex-orchestrator init codex --cwd /path/to/repo
+   ```
+2. Review the generated files:
+   - `AGENTS.md`
+   - `.codex/config.toml`
+   - `.codex/providers/README.md`
+   - `.codex/providers/provider.env.example`
+   - `.codex/providers/control.example.json`
+   - `codex.orchestrator.json`
+3. Start with a task-scoped flow:
+   ```bash
+   codex-orchestrator flow --task <task-id>
+   ```
+
+## Version-Specific Notes
+
+- `codex exec` now accepts both a prompt argument and piped stdin; piped stdin is appended as a `<stdin>` block.
+- `codex login --device-auth` is available for environments where browser sign-in is not practical.
+- CO keeps review-wrapper prompt transport explicit and artifact-backed; do not assume every `codex review` code path matches `codex exec`.
+
+## First-run checks
+
+Use these before asking a reviewer to trust a new repo:
+
+```bash
+codex-orchestrator doctor --format json
+codex-orchestrator flow --task <task-id>
+NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review --task <task-id>
+```
+
+## Provider onboarding
+
+For Linear and Telegram setup, continue with [provider-onboarding.md](provider-onboarding.md).

package/docs/public/provider-onboarding.md

@@ -0,0 +1,173 @@
+# Provider Onboarding
+
+This guide is the downstream-safe provider contract for Linear and Telegram.
+
+## Contract
+
+- Once per machine: install CO, authenticate Codex, and confirm `codex-orchestrator doctor --format json` works.
+- Once per repo: seed `.codex/providers/` with `codex-orchestrator init codex`.
+- Runtime env carries secrets and provider bindings.
+- Control policy carries `dispatch_pilot` and `transport_mutating_controls`.
+- Linear and Telegram should both have a machine-checkable readiness signal before live smoke.
+
+## Generated scaffolding
+
+`codex-orchestrator init codex` seeds:
+
+- `.codex/providers/README.md`
+- `.codex/providers/provider.env.example`
+- `.codex/providers/control.example.json`
+
+Use those files as the starting point for your repo-specific provider setup.
+
+## Environment variables
+
+Recommended Linear env:
+
+- `CO_LINEAR_API_TOKEN`
+- `CO_LINEAR_WORKSPACE_ID`
+- `CO_LINEAR_TEAM_ID`
+- `CO_LINEAR_PROJECT_ID`
+- `CO_LINEAR_WEBHOOK_SECRET`
+
+Supported Linear token fallbacks:
+
+- `CO_LINEAR_API_KEY`
+- `LINEAR_API_KEY`
+
+Telegram env:
+
+- `CO_TELEGRAM_POLLING_ENABLED`
+- `CO_TELEGRAM_BOT_TOKEN`
+- `CO_TELEGRAM_ALLOWED_CHAT_IDS`
+- `CO_TELEGRAM_ENABLE_MUTATIONS`
+- `CO_TELEGRAM_POLL_INTERVAL_MS`
+- `CO_TELEGRAM_PUSH_ENABLED`
+- `CO_TELEGRAM_PUSH_INTERVAL_MS`
+
+## Control policy
+
+Keep the provider policy explicit.
+
+`dispatch_pilot` should declare a Linear source and stay advisory-first:
+
+```json
+{
+  "feature_toggles": {
+    "dispatch_pilot": {
+      "enabled": true,
+      "source": {
+        "provider": "linear",
+        "live": true,
+        "workspace_id": "workspace-id",
+        "team_id": "team-id",
+        "project_id": "project-id"
+      }
+    }
+  }
+}
+```
+
+Telegram mutation policy should be explicit too:
+
+```json
+{
+  "feature_toggles": {
+    "transport_mutating_controls": {
+      "enabled": true,
+      "allowed_transports": ["telegram"]
+    }
+  }
+}
+```
+
+Nested `coordinator.dispatch_pilot` and `coordinator.transport_mutating_controls` remain valid compatibility paths.
+
+## Readiness
+
+`codex-orchestrator doctor --format json` is the machine-checkable readiness surface.
+
+Expect it to tell you:
+
+- whether delegation and DevTools wiring are present
+- whether Linear credentials and binding env are populated
+- whether `CO_LINEAR_WEBHOOK_SECRET` is present
+- whether Telegram polling, token, and allowlist env are populated
+- whether repo scaffolding under `.codex/providers/` exists
+
+## Smoke flow
+
+Use this minimal smoke flow:
+
+1. Check readiness:
+   ```bash
+   codex-orchestrator doctor --format json
+   ```
+2. Start the host in a dedicated terminal and keep it running:
+   ```bash
+   codex-orchestrator control-host --format json
+   ```
+   This prints a startup readiness payload and then keeps the host alive.
+3. In another terminal, inspect the current status snapshot:
+   ```bash
+   codex-orchestrator co-status --format json
+   ```
+4. Telegram read-only smoke:
+   - send `/help` from an allowlisted chat
+   - confirm the bot replies
+5. Linear advisory smoke:
+   - confirm the status snapshot reaches `dispatch_pilot.status=ready`
+   - confirm the selected tracked issue resolves from the configured workspace, team, or project binding
+
+## Help surfaces
+
+Use these commands when onboarding an operator:
+
+```bash
+codex-orchestrator doctor --help
+codex-orchestrator control-host --help
+codex-orchestrator co-status --help
+```
+
+`control-host --format json` is a persistent host startup handshake, not a one-shot status dump.
+
+## macOS launchd supervision
+
+On macOS, use the shipped supervision surface instead of a copied local shell wrapper:
+
+1. Make sure the `codex-orchestrator` currently on `PATH` is current enough to expose `control-host supervise`:
+   - source-checkout operator: from the checkout root, run `npm link` so the active `codex-orchestrator` bin points at this checkout's `bin/codex-orchestrator.js`
+   - packaged/global install operator: upgrade the active package (for example `npm install -g @kbediako/codex-orchestrator@latest`) before attempting the migration
+   - verify the active CLI with:
+   ```bash
+   codex-orchestrator control-host supervise status --format json
+   ```
+   If the current machine is still on the legacy shim rollout, the JSON status now reports that rollout mode and that migration is still required.
+2. Install the LaunchAgent-backed supervisor from the repo root:
+   ```bash
+   codex-orchestrator control-host supervise install --format json
+   ```
+   This rewrites the existing `com.kbediako.co.control-host` LaunchAgent in place, replacing the legacy shim rollout when present, and records the active package's `bin/codex-orchestrator.js` bootstrap as the managed entrypoint.
+3. Inspect the current launchd, rollout mode, config, and restart-reason state:
+   ```bash
+   codex-orchestrator control-host supervise status --format json
+   ```
+4. Restart the supervised host after config or env changes:
+   ```bash
+   codex-orchestrator control-host supervise restart --format json
+   ```
+   The restart payload records the previously tracked supervised child pid (`previous_child_pid`), the newly observed supervised child pid when available (`child_pid`), and `cleanup.result`. If launchd leaves the old supervised tree alive, the payload fails closed unless CO can force-clean that exact stale control-host process group first; any forced cleanup also records the orphaned process-group and descendant pids in `cleanup`.
+5. Remove the generated LaunchAgent, config, state, and logs:
+   ```bash
+   codex-orchestrator control-host supervise uninstall --format json
+   ```
+
+`control-host supervise status --format json` is the machine-checkable operator surface for whether the LaunchAgent is still on the legacy shim rollout or the managed packaged rollout, whether migration is still required, whether launchd is loaded, which supervised control-host child pid is currently recorded, and what last restart reason or health state the supervisor recorded.
+
+When a replacement host encounters an already-running owner during a restart race, inspect:
+
+```bash
+codex-orchestrator co-status --format json
+```
+
+The `polling.control_host_owner` payload carries the duplicate/stale owner diagnostic path plus owner pid/token metadata. Treat that owner diagnostic as control-host evidence, not as a provider-worker list: detached `provider-linear-worker` issue processes run independently in their own issue workspaces and are not the restart cleanup target.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.37",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Kbediako/CO"
+    "url": "git+https://github.com/Kbediako/CO.git"
   },
   "homepage": "https://github.com/Kbediako/CO#readme",
   "bugs": {
@@ -12,10 +12,13 @@
   },
   "type": "module",
   "bin": {
-    "codex-orchestrator": "dist/bin/codex-orchestrator.js",
-    "codex-orch": "dist/bin/codex-orchestrator.js"
+    "codex-orchestrator": "bin/codex-orchestrator.js",
+    "codex-orch": "bin/codex-orchestrator.js"
   },
   "files": [
+    ".agents/plugins/marketplace.json",
+    "plugins/**",
+    "bin/codex-orchestrator.js",
     "dist/bin/**",
     "dist/orchestrator/**",
     "dist/packages/**",
@@ -27,7 +30,8 @@
     "templates/**",
     "skills/**",
     "codex.orchestrator.json",
-    "docs/assets/setup.gif",
+    "docs/public/downstream-setup.md",
+    "docs/public/provider-onboarding.md",
     "README.md",
     "LICENSE"
   ],
@@ -49,8 +53,12 @@
     "docs:archive-implementation": "node scripts/implementation-docs-archive.mjs",
     "docs:archive-tasks": "node scripts/tasks-archive.mjs",
     "docs:freshness": "node scripts/docs-freshness.mjs --check",
+    "docs:freshness:maintain": "node scripts/docs-freshness-maintain.mjs --check",
+    "done-closeout:check": "node scripts/done-closeout-provenance-check.mjs --check",
+    "repo:stewardship": "node scripts/repo-stewardship-audit.mjs --check",
     "docs:sync": "node --loader ts-node/esm scripts/docs-hygiene.ts --sync",
     "ci:cloud-canary": "node scripts/cloud-canary-ci.mjs",
+    "canary:js-repl-usage": "node scripts/js-repl-usage-matrix.mjs",
     "canary:runtime": "node scripts/runtime-mode-canary.mjs",
     "prelint": "node scripts/build-patterns-if-needed.mjs",
     "lint": "eslint orchestrator/src orchestrator/tests packages/orchestrator/src packages/orchestrator/tests packages/shared adapters evaluation/harness evaluation/tests --ext .ts,.tsx",
@@ -58,11 +66,14 @@
     "pack:smoke": "node scripts/pack-smoke.mjs",
     "prepack": "npm run clean:dist && npm run build && npm run pack:audit",
     "setup:design-tools": "node --loader ts-node/esm scripts/setup-design-tools.ts",
-    "test": "npm run test:orchestrator",
-    "test:orchestrator": "vitest run --config vitest.config.core.ts",
-    "test:adapters": "vitest run --passWithNoTests --config vitest.config.ts adapters",
-    "test:evaluation": "vitest run --passWithNoTests --config vitest.config.ts evaluation/tests",
-    "eval:test": "vitest run evaluation/tests",
+    "test": "npm run test:core --",
+    "test:core": "vitest run --config vitest.config.core.ts",
+    "test:all": "node scripts/run-test-all.mjs",
+    "test:orchestrator": "npm run test:core --",
+    "test:adapters": "vitest run --passWithNoTests --config vitest.config.adapters.ts",
+    "test:evaluation": "vitest run --passWithNoTests --config vitest.config.evaluation.ts",
+    "eval:test": "npm run test:evaluation --",
+    "eval:provider-adoption": "node scripts/provider-linear-adoption-eval.mjs",
     "test:watch": "vitest",
     "review": "node --loader ts-node/esm scripts/run-review.ts",
     "pr:watch-merge": "node scripts/pr-monitor-merge.mjs",
@@ -126,5 +137,13 @@
     "ink": "^4.4.1",
     "js-yaml": "^4.1.0",
     "react": "^18.3.1"
-  }
+  },
+  "description": "Codex-driven orchestration CLI with auditable manifests, downstream repo bootstrapping, and delegation MCP workflows.",
+  "main": "dist/orchestrator/src/cli/orchestrator.js",
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "keywords": [],
+  "author": ""
 }

package/plugins/codex-orchestrator/.codex-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "name": "codex-orchestrator",
+  "version": "0.2.0",
+  "description": "Codex Orchestrator plugin metadata for the packaged CO runtime.",
+  "author": {
+    "name": "Kbediako",
+    "url": "https://github.com/Kbediako"
+  },
+  "homepage": "https://github.com/Kbediako/CO#readme",
+  "repository": "https://github.com/Kbediako/CO",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "mcp",
+    "orchestrator"
+  ],
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Codex Orchestrator",
+    "shortDescription": "Register CO's MCP orchestration server in Codex.",
+    "longDescription": "Connect Codex to Codex Orchestrator's MCP server for auditable task flows, manifests, and delegation workflows.",
+    "developerName": "Kbediako",
+    "category": "Productivity",
+    "capabilities": [
+      "MCP",
+      "Automation"
+    ],
+    "screenshots": []
+  }
+}

package/plugins/codex-orchestrator/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "templateVersion": 1,
+  "mcpServers": {
+    "codex-orchestrator": {
+      "command": "node",
+      "args": [
+        "./launcher.mjs",
+        "mcp",
+        "serve"
+      ]
+    }
+  }
+}