oh-my-copilot 5.6.2 → 5.8.0

package/docs/MIGRATION.md

@@ -8,6 +8,8 @@ This guide covers all migration paths for oh-my-copilot. Find your current versi
 
 - [Unreleased: Team Instance Ownership](#unreleased-team-instance-ownership)
 - [Unreleased: Cancellation Scope](#unreleased-cancellation-scope)
+- [v5.7.0 → v5.8.0: SDK Team Transport](#v570--v580-sdk-team-transport)
+- [v5.6.2 → v5.7.0: Smoke Harness](#v562--v570-smoke-harness)
 - [v5.6.1 → v5.6.2: Postinstall Hook](#v561--v562-postinstall-hook)
 - [v5.5.0 → v5.6.1: Fork Upgrade Guide](#v550--v561-fork-upgrade-guide)
 - [v5.1.0 → v5.5.0: Fork Upgrade Guide](#v510--v550-fork-upgrade-guide)
@@ -122,6 +124,194 @@ locations and descendants of system temp/OS roots are never used as roots.
 
 ---
 
+## v5.7.0 → v5.8.0: SDK Team Transport
+
+Fork **v5.8.0** adds an experimental headless SDK transport for `omg team`,
+factory chains on Copilot, faster Copilot hooks and a Copilot smoke job in CI.
+There is nothing to migrate: no config, command or skill is renamed or
+removed, and every default is unchanged. The team transport stays `pane`, the
+SessionEnd budget under Claude Code stays 300 ms, and the CI smoke job skips
+without its secret.
+
+- Update with `npm install -g oh-my-copilot@5.8.0` or
+  `copilot plugin update oh-my-copilot@omc`.
+
+### Adopting `--transport sdk`
+
+The transport is experimental and opt-in. It needs `copilot` on PATH and the
+optional SDK, installed the same way as for smoke tier 2:
+
+```bash
+npm i -g @github/copilot-sdk --omit=optional --ignore-scripts
+omg team 2:copilot --transport sdk "<task>"
+```
+
+To opt in for every team, set it in `.copilot/omg.jsonc`:
+
+```jsonc
+{
+  "team": {
+    "transport": "sdk",
+    "sdk": { "maxCreditsPerWorker": 10 }
+  }
+}
+```
+
+- **`team.sdk.maxCreditsPerWorker`** caps each worker (default 10, a
+  positive number; env `OMC_TEAM_SDK_MAX_CREDITS`). At the cap the host aborts
+  the turn, takes no more prompts, and `omg team status` shows the worker as
+  `capped`.
+- **Permissions are a policy, not a sandbox.** There is no allow-all. The
+  host allows writes only in the worker's worktree and the team state root,
+  and MCP calls only to the plugin server. The shell check is a denylist: it
+  blocks team control other than `team api`, `omg smoke`, `tmux`/`psmux`,
+  `git push`, and the `shell(<prefix>)` entries of `workerDenyTools`, but a
+  command built indirectly, such as a script file or an alias, is not caught.
+- **Excluded tools.** `task`, `run_dynamic_workflow`,
+  `dynamic_workflows_manage`, `write_agent`, `read_agent`, `list_agents`,
+  `search_code_subagent` and the plugin's `host_smoke` are removed from each
+  worker session.
+- **Rejected at start:** `--auto-merge`, non-copilot workers, scaling, and an
+  explicitly assigned reviewer-contract role (`critic`, `code-reviewer`,
+  `security-reviewer`, `test-engineer`). Keep those teams on `pane`.
+
+Details are in
+[Headless SDK workers](./REFERENCE.md#headless-sdk-workers---transport-sdk-experimental).
+
+### Factory chains on Copilot
+
+Software-factory chains now run past their first link on Copilot CLI. Before,
+a Copilot link got a random session id (Copilot has no `--session-id`), its
+SessionEnd found no ledger, and the chain stopped silently after one link.
+Nothing to configure:
+
+- The spawner (factory listener or SessionEnd worker) sets
+  `OMC_CHAIN_LINK=<link id>` on each Copilot link. SessionEnd resolves the
+  link as `OMC_CHAIN_LINK`, then the host session id, and trusts the variable
+  only when it names a `host: "copilot"` ledger bound to the ending session
+  by that link's SessionStart, so a nested session cannot end its parent's
+  link. A duplicate SessionEnd gets the same chain back. Claude links keep
+  `--session-id`.
+- Copilot's SessionEnd reason `complete` now counts as success, so route keys
+  such as `success:*` match a finished Copilot link.
+- Link ledgers record `chainLink`, `host`, `createdAt` and `parentLink`, and
+  each link's SessionEnd closes its ledger once (`closedAt`, `hostSessionId`,
+  `outcome`, `decision`). The watchdog skips a closed ledger only when it
+  advanced the chain or left a stop marker, and `omg factory status` lists
+  each chain's links.
+- A ledger's `maxStageVisits` now applies to the whole chain, not just the
+  first link; values above 99 clamp to 99 (before, they fell back to 2 on
+  later links).
+- Under a dev plugin root (`omg --plugin-dir`), Copilot links get
+  `--plugin-dir` too, and the SessionEnd worker forwards `OMC_PLUGIN_ROOT`,
+  unless the root overlaps the link's working directory.
+- `omg smoke copilot --tier 2 --scenario chain` runs a real two-link chain
+  (about 2 premium requests). It is opt-in and not part of `all`.
+
+Copilot fires `sessionEnd` after every turn, so a link that a Stop hook
+continues into a second turn hands off after its first turn; the closed
+ledger prevents a second hand-off. Ledgers written by an older version have
+no `host` field: a Copilot link
+spawned before the upgrade still ends its chain after one link. Guardrails
+(serial lock, daily cap), `COPILOT_ALLOW_ALL=false` and the AFK permission
+profile are unchanged. See
+[Factory chains on Copilot](./REFERENCE.md#factory-chains-on-copilot).
+
+### Hook environment knobs
+
+Under Copilot the SessionEnd foreground budget is now 1500 ms and the audited
+generic hooks run in a Worker thread. Claude Code is unchanged. Two variables
+tune this:
+
+| Variable | Effect |
+| --- | --- |
+| `OMC_SESSION_END_BUDGET_MS` | Overrides the SessionEnd foreground budget on both hosts, an integer from 1 to 60000. Default 1500 under Copilot, 300 under Claude Code. |
+| `OMC_COPILOT_HOOK_WORKER=0` | Turns off Worker routing under Copilot, so every generic hook takes the child path again. |
+
+See [SessionEnd](./HOOKS.md#sessionend) in the hooks reference.
+
+### CI secret for the Copilot smoke job
+
+The new `smoke` job in `.github/workflows/ci.yml` needs the repository secret
+`COPILOT_GITHUB_TOKEN`, a fine-grained personal access token of a user with
+an active Copilot subscription and the "Copilot Requests" account
+permission. Without it the job passes with a skip notice. With it, PRs and
+branch pushes run the free static checks, and pushed `v*` tags also run the
+default scenarios, about 2 premium requests billed to that user. Setup is in
+[DEVELOPERS.md](DEVELOPERS.md#tier-2-in-ci).
+
+---
+
+## v5.6.2 → v5.7.0: Smoke Harness
+
+Fork **v5.7.0** adds a headless smoke harness and ports upstream
+oh-my-claudecode `dev` 486b85bbb..bcaceb136. There is nothing to migrate: no
+config, command or skill is renamed or removed.
+
+- Update with `npm install -g oh-my-copilot@5.7.0` or
+  `copilot plugin update oh-my-copilot@omc`.
+
+### Adopting `omg smoke copilot` and `host_smoke`
+
+Build first (`npm run build`); the MCP check spawns
+`dist/mcp/standalone-server.js`.
+
+| Tier | Command | Cost |
+| --- | --- | --- |
+| 0 | `omg smoke copilot --tier 0` | Free, no model call |
+| 1 | `omg smoke copilot --tier 1` | 1 premium request |
+| 2 static | `omg smoke copilot --sdk-static` | Free, no model call |
+| 2 | `omg smoke copilot --tier 2 [--scenario all]` | About 1 premium request per scenario; the default `smoke` + `guardrail` costs about 2 |
+
+`--max-credits` (default and minimum 30) caps a run. The CLI has no opt-in
+gate. The MCP tool `host_smoke` has two, set as env vars on the MCP server:
+
+- **`OMC_SMOKE_ALLOW_LIVE=1`** allows `{ "tier": 1 }` and tier 2 with
+  scenarios. `{ "tier": 2, "scenarios": [] }` runs the free static checks
+  without it.
+- **`OMC_SMOKE_ALLOW_ANY_ROOT=1`** allows a `pluginRoot` other than the
+  server's own package root.
+
+`OMC_DISABLE_TOOLS=smoke` hides the tool. From vitest, `npm run test:live`
+runs tier 0 whenever the `copilot` binary resolves. It runs tier 1 only with
+`OMC_LIVE_SMOKE=1` and the tier 2 scenarios only with `OMC_LIVE_SMOKE=2`.
+Details are in
+[DEVELOPERS.md](DEVELOPERS.md#headless-smoke-against-a-local-build).
+
+### Optional SDK for tier 2
+
+`@github/copilot-sdk` is an optional peer dependency; installing
+oh-my-copilot never pulls it in. Install it only if you want tier 2:
+
+```bash
+npm i -g @github/copilot-sdk --omit=optional --ignore-scripts
+```
+
+`--ignore-scripts` avoids a CMake source build on Windows. If a global
+install still adds the SDK's bundled platform runtime (about 128 MB), delete
+it; tier 2 always uses the installed `copilot` binary.
+
+### `OMC_HOOK_FAIL_CLOSED=1`
+
+The variable is opt-in and unset by default. Without it, the Copilot hook
+adapter turns a hook's non-zero exit into `0` plus one `[omg-hook]` stderr
+line, and a hook that times out in `scripts/run.cjs` exits `0`, so hooks fail
+open. With `OMC_HOOK_FAIL_CLOSED=1` the adapter keeps the hook's exit code,
+and a hook timeout in `scripts/run.cjs` exits `124`. Exit `2` on
+PermissionRequest means deny in both modes. The smoke harness sets the
+variable for its own sessions.
+
+### Team env passthrough on POSIX (#4236)
+
+`OMC_TEAM_WORKER_ENV_PASSTHROUGH` keeps the same configuration. On POSIX tmux
+teams its values are no longer inlined into the worker pane's command line.
+They are written to a private `0600` file in a `0700` directory, which the
+pane's `/bin/sh` sources and removes before it execs the login shell. Nothing
+changes for you, but the values no longer appear in `ps` output or tmux
+`pane_start_command`.
+
+---
+
 ## v5.6.1 → v5.6.2: Postinstall Hook
 
 Fork **v5.6.2** ports upstream oh-my-claudecode `dev` 4280efb1f..486b85bbb.
@@ -240,9 +430,10 @@ it there.
 
 ### Known limitations
 
-- **Copilot factory chains stop after one link.** Copilot CLI has no
-  `--session-id`, so the next link cannot be pinned; `omg factory status` and
-  the watchdog report the stalled chain.
+- **Copilot factory chains stop after one link** (fixed in v5.8.0, see
+  [Factory chains on Copilot](#factory-chains-on-copilot)).
+  Copilot CLI has no `--session-id`, so the next link cannot be pinned;
+  `omg factory status` and the watchdog report the stalled chain.
 - **git-guardrails under Copilot on Windows is not live-verified.** The hook
   is projected and unit-tested, but its PreToolUse payload has not been
   exercised in a live Copilot session on Windows. Plant a violation (for

package/docs/REFERENCE.md

@@ -2,7 +2,7 @@
 
 Complete reference for oh-my-copilot. For quick start, see the main [README.md](../README.md).
 
-For v5.6.2, the plugin ships 20 agents, 61 skills, 21 command files, and one configured MCP server exposing exactly 55 tools.
+For v5.8.0, the plugin ships 20 agents, 61 skills, 21 command files, and one configured MCP server exposing exactly 56 tools.
 
 ---
 
@@ -139,6 +139,7 @@ If both configurations exist, **project-scoped takes precedence** over global:
 | `OMC_FREE_MEMORY_THRESHOLD` | `256` | Free memory threshold in MB. Gate blocks operations when free memory falls below this. Set to negative value to disable. |
 | `OMC_MAX_SIBLING_SESSIONS` | `8` | Maximum concurrent OMC sessions before gating expensive operations. Set to negative value to disable. |
 | `OMC_HOST_LOAD_GATE_DISABLED` | _(unset)_ | Set to any value to disable the host load gate entirely. |
+| `OMC_CHAIN_LINK` | _(set by the spawner)_ | Internal. The chain-link id of a Copilot factory link, set on the spawned `copilot` process by the factory listener or the SessionEnd worker. Do not set it yourself: SessionEnd only trusts it when it names a `host: "copilot"` ledger, and a finished link is a no-op. See [Factory chains on Copilot](#factory-chains-on-copilot). |
 
 #### Host Load Gate
 
@@ -609,12 +610,22 @@ omg ask claude --agent-prompt executor --prompt "create an implementation plan"
 ```bash
 omg team 2:codex "review auth flow"
 omg team status review-auth-flow
+omg team status review-auth-flow --json
+omg team status --json             # auto-resolves the team name when exactly one team is active
 omg team shutdown review-auth-flow --force
 omg team api claim-task --input '{"team_name":"auth-review","task_id":"1","worker":"worker-1"}' --json
 ```
 
 Supported entrypoints: direct start (`omg team [N:agent] "<task>"`), `status`, `shutdown`, and `api`.
 
+`team status [team-name] --json` prints the same status data as the human-readable
+report (team/instance id, phase, workspace/worktree mode, worker list with worktree
+metadata, SDK worker fields — provider liveness, state, turns, credits, premium
+requests — task counts, and leader guidance) as a single JSON document instead of
+text, with `ok: false` when no team state is found. `--json` can appear before or
+after the team name and is never mistaken for one; when the team name is omitted
+and exactly one team is active, it is resolved automatically.
+
 Startup reserves the team name for an immutable instance. Shutdown and job cleanup
 require matching instance and worker-launch evidence; `--force` skips graceful
 waits but does not bypass ownership checks. Missing or corrupt evidence preserves
@@ -676,6 +687,16 @@ Worker panes run unattended, so each provider launches with its own auto-approve
 
 - `disableExternalLLM` / `OMC_SECURITY=strict` allows only the current host CLI's workers. See [SECURITY.md](../SECURITY.md).
 
+#### Headless SDK workers (`--transport sdk`, experimental)
+
+`omg team 2:copilot --transport sdk "<task>"` (or `team.transport: "sdk"`) runs each copilot worker as a detached `omg team sdk-host` process that owns one `@github/copilot-sdk` session, with no pane and no multiplexer. It needs `@github/copilot-sdk` installed (`npm i -g @github/copilot-sdk --omit=optional --ignore-scripts`).
+
+- **No allow-all.** The host answers every permission request. Writes are allowed only inside the worker's worktree and the team state root. Reads also allow the plugin root. MCP calls are allowed only to the plugin server.
+- **The shell policy is a denylist, not a sandbox.** It rejects team control other than `team api`, `omg smoke`, `tmux`/`psmux` and `git push`, plus `shell(<prefix>)` entries of `workerDenyTools`, including quoted spellings such as `"omg" team shutdown`. A command built indirectly (a script file, an alias, `Invoke-Expression`, an encoded command) is not caught. Treat the write-path check, the credit cap and the per-worker `COPILOT_HOME` as the boundaries.
+- **Sub-agent tools are removed**: `task`, `run_dynamic_workflow`, `dynamic_workflows_manage`, `write_agent`, `read_agent`, `list_agents`, `search_code_subagent` and the plugin's `host_smoke`.
+- **Credit cap.** `team.sdk.maxCreditsPerWorker` (default 10, must be a positive number; env `OMC_TEAM_SDK_MAX_CREDITS`) is enforced by the host: at the cap it aborts the turn and takes no more prompts, and `omg team status` shows the worker as `capped` with a reassign recommendation.
+- **Unsupported under sdk:** `--auto-merge`, non-copilot workers, scaling, dead-worker recovery, and an **explicitly** assigned reviewer role with a verdict contract (`critic`, `code-reviewer`, `security-reviewer`, `test-engineer` — set directly via a task's `role` or via `team.roleRouting`); startup rejects them. A contract role merely *inferred* from task text (with no explicit assignment) is not rejected: the role is dropped and the worker runs as a plain executor instead, since an SDK host never exits between turns and so could never have its verdict file read anyway.
+
 ### `omg session search`
 
 ```bash
@@ -732,6 +753,73 @@ omg lookout scan --strict   # exit 1 when review is recommended (for scripts)
 - `--json` emits the full report; exit codes: `0` for every successful non-strict scan and for strict scans without a review-recommended verdict, `1` for `--strict` with a review-recommended verdict, `2` for a usage/scan error
 - High-risk verdicts pair with approval gates and checkpoints: `omg graph run --approval-mode remote --checkpoint`, `omg checkpoint create`
 
+### `omg factory`
+
+`omg factory init` seeds the project route table `.omg/factory-routes.json`, `omg factory listen` runs the HMAC-verified tracker intake daemon, and `omg factory status [--json]` is the read-only chain audit. A chain is a series of headless AFK links: when a link's session ends, the SessionEnd hook routes its `outcome:reason` through the route table and the detached SessionEnd worker spawns the next link. Guardrails apply per link: one active link per intent (serial lock) and a daily cap of 10 (`OMC_DAILY_CHAIN_LIMIT`).
+
+#### Factory chains on Copilot
+
+Each link has a chain-link id and a ledger `.omg/state/factory/chain-<id>.json`, written by whoever spawns the link (the listener for the first link, the SessionEnd worker for later ones). The SessionEnd hook must find that ledger, so the link id has to reach the ending session:
+
+- **Claude Code** pins it with `--session-id <id>`; the host session id is the link id.
+- **Copilot CLI** has no `--session-id`, so the spawner sets `OMC_CHAIN_LINK=<id>` on the `copilot` process. Copilot passes its env to hook processes, and SessionEnd resolves the link as `OMC_CHAIN_LINK` first, then the host session id.
+
+The link's own SessionStart binds the link to its host session: the first session that starts with `OMC_CHAIN_LINK` naming an open Copilot ledger records itself as `boundSessionId` (an exclusive `chain-<id>.json.bind` file). `OMC_CHAIN_LINK` is trusted at SessionEnd only when `chain-<id>.json` exists, records `host: "copilot"` and `chainLink: <id>`, is bound to the ending host session, and the ending session is not a Claude session (`CLAUDE_CODE_ENTRYPOINT` unset). A nested session that inherited the variable (a verify command's `copilot -p`, an MCP child, a team worker) therefore cannot end its parent's link. Otherwise SessionEnd falls back to the host session id and records `chain-link-rejected` in `chain-decisions.jsonl`. A link is decided once: a duplicate SessionEnd of the same host session gets the chain it enqueued back (`already-closed`, `replayed: enqueued`), so whichever hook's manifest wins still carries the chain, and the one job per host session spawns it once. A concurrent duplicate waits briefly for the deciding hook (`chain-<id>.json.claim`), then records `duplicate-session-end`. So setting the variable alone can neither inject a chain nor replay a finished link. If the hand-off fails after the decision, the ledger's `decision` is corrected to `manifest-unavailable`, `worker-spawn-failed`, or `enqueued-failed`, and the stored chain is dropped so it is never replayed. The detached SessionEnd worker never forwards `OMC_CHAIN_LINK`: the chain identity rides the durable manifest payload, and every spawned link gets its own value. `COPILOT_ALLOW_ALL` stays forced to `false` on every link, and the AFK permission profile is unchanged.
+
+| Ledger field | Meaning |
+|---|---|
+| `chainLink`, `host`, `createdAt`, `parentLink` | Written at spawn: the link id, `copilot` or `claude`, and the link that spawned it. |
+| `boundSessionId`, `boundAt` | Copilot only: the host session that started the link. |
+| `closedAt`, `hostSessionId`, `endReason`, `outcome`, `decision`, `enqueuedChain` | Written once by the link's SessionEnd. The watchdog skips a closed ledger only when its decision advanced the chain or left a stop marker (`enqueued`, `chain-terminal`, `chain-loop-capped`, `human-gate`, `no-route` on failure); a link dropped by a guardrail, an invalid ledger, or an error is still flagged. |
+| `maxStageVisits` | Stage-visit cap, carried from the first ledger to every later link (default 2, values above 99 clamp to 99). |
+
+Copilot's SessionEnd reason for a finished `-p` link is `complete` (CLI 1.0.91), which counts as `success` alongside Claude's `other`, `prompt_input_exit`, and `logout`; route keys such as `success:*` match both hosts. When OMC runs from a dev plugin root (`omg --plugin-dir`, which sets `OMC_PLUGIN_ROOT`), Copilot links also get `--plugin-dir <root>`, and the SessionEnd worker forwards `OMC_PLUGIN_ROOT`, so every link loads the same plugin. The root is dropped when it overlaps the link's working directory, because an AFK link may write there and could rewrite the plugin's hooks; a chain over the plugin's own repo needs the plugin installed. On Windows a root containing `%` is dropped as well. Limitation: Copilot fires `sessionEnd` after every turn, also in `-p` mode, so a link that a Stop hook keeps going into a second turn hands off after its first turn. The closed ledger stops later turns from enqueuing again, but the next link may start while this one still runs. A single-prompt link is not affected. `omg factory status` lists each intent's links in spawn order with host, link id, and closeout, for example `环 2 link-2 [copilot] link=<id> 已结束 success→chain-loop-capped session=<host session>`.
+
+### `omg smoke copilot`
+
+Headless smoke check of a plugin root against the real GitHub Copilot CLI, in a throwaway `COPILOT_HOME`. Use it on a local build before opening a PR or tagging a release.
+
+```bash
+omg smoke copilot                     # tier 0: load check, no model call
+omg smoke copilot --tier 1            # tier 0 + one live session, prompt on stdin (one premium request)
+omg smoke copilot --plugin-root /path/to/oh-my-copilot --json
+omg smoke copilot --tier 1 --keep-home --delegate --model <id> --max-credits 30 --timeout 180000
+omg smoke copilot --sdk-static        # tier 2 SDK static checks only, no model call
+omg smoke copilot --tier 2            # tier 2 default scenarios smoke,guardrail (~2 premium requests, 1 per scenario)
+omg smoke copilot --tier 2 --scenario skill,delegate   # or --scenario all
+omg smoke copilot --tier 2 --scenario chain            # opt-in: a real two-link factory chain (~2 premium requests)
+```
+
+- **Tier 0** checks: `plugin.manifest`, `plugin.hooks`, `copilot.binary`, `copilot.plugin_list`, `copilot.skill_list`, `copilot.agents`, `mcp.list_tools`. `mcp.list_tools` spawns `dist/mcp/standalone-server.js`, so run `npm run build` first.
+- **Tier 1** adds `session.exit`, `session.events`, `hooks.*` (including `hooks.adapter_errors`), `plugins.loaded`, `mcp.server_loaded`, `state.written`, and with `--delegate` `subagent.selected`. Hooks run with `OMC_HOOK_FAIL_CLOSED=1`; a `hook.end` without `success: true` fails its check, and `hooks.adapter_errors` fails on any `[omg-hook]` error line.
+- **Tier 2** drives the installed `copilot` binary through the optional peer `@github/copilot-sdk` (install it with `npm i -g @github/copilot-sdk --omit=optional --ignore-scripts`; a nested `@github/copilot-sdk-<platform>` runtime package is unused and can be deleted, see [DEVELOPERS.md](./DEVELOPERS.md#tier-2--sdk-scenarios)). It runs the tier 0 checks, then the SDK static checks `sdk.available`, `sdk.runtime`, `sdk.plugins`, `sdk.skills`, `sdk.agents`, `sdk.mcp`, `sdk.tools_excluded` (our `<server>-host_smoke` tool is absent from the session's tool list), then the chosen scenarios. It does not run the tier 1 `-p` session. `--sdk-static` runs no scenario and makes no model call.
+- **Tier 2 scenarios** yield checks prefixed `scn.<name>.`. Each one also gets `scn.<name>.exit`, `scn.<name>.adapter_errors` (fails on any `[omg-hook]` or `[run.cjs]` hook stderr line, such as a hook timeout), and `scn.<name>.cost`. Each scenario costs about one premium request, so the default run costs about two.
+
+| Scenario | Prompt exercises | Key checks |
+|---|---|---|
+| `smoke` (default) | a plain reply, no tools | `scn.smoke.reply`, `scn.smoke.hooks`, `scn.smoke.no_tools` |
+| `guardrail` (default) | `git push --force` with `OMC_GIT_GUARDRAILS=1` against a bare remote | `scn.guardrail.denied`, `scn.guardrail.no_push`, `scn.guardrail.hooks` |
+| `skill` | `/oh-my-copilot:plan` | `scn.skill.invoked` |
+| `delegate` | a hand-off to `oh-my-copilot:architect` | `scn.delegate.selected`, `scn.delegate.hooks`, `scn.delegate.completed` |
+| `chain` (opt-in, never in `all`) | two real `copilot -p` factory links: link 1 replies with one token, link 2 runs the project skill `/chain-ack` | `scn.chain.link1`, `scn.chain.spawned`, `scn.chain.inherited`, `scn.chain.closed`, `scn.chain.premium` |
+
+- **`chain` scenario.** It does not use an SDK session. It seeds the sandbox with `omg factory init` plus a `success:*` route to stage `link-2`, pre-writes link 1's ledger, and spawns link 1 like a factory link (AFK profile, `--plugin-dir`, `OMC_CHAIN_LINK`). The chain then runs itself through the SessionEnd hook and worker, and stops at the stage-visit cap after link 2. The checks read the ledgers, decisions, stop marker, and both link sessions' `events.jsonl`: link 1 was resolved by `OMC_CHAIN_LINK`, link 2 was spawned and ended under its own inherited identity, the chain closed out (`loop-capped:link-2`, no open ledger), and both links together cost at most 2 premium requests. The links run on the CLI's default model without `--max-ai-credits`, because a factory link's argv carries no credit cap, so `--max-credits` does not bound them. `--timeout` applies to link 1 and again to the wait for link 2.
+
+- **Tier 2 report** adds `sdk` (SDK version, runtime version, protocol version), `cost` (premium requests and credits summed over scenarios), and `artifacts.events` with one events JSONL path per scenario. Human output groups the `sdk.*` checks and each scenario's `scn.<name>.*` checks under a heading.
+- **Model:** `--model` is optional. Copilot auto-selects when it is omitted (1.0.91 picked `mai-code-1.1-flash`); explicit ids may be rejected as unavailable.
+- **Auth:** tier 1 reuses the login identity from your Copilot config, so `copilot /login` is enough. When a login is found the session drops `GH_TOKEN` and `GITHUB_TOKEN`, which would otherwise shadow it. `COPILOT_GITHUB_TOKEN` always passes through, and without a stored login (CI) all three do.
+- `--max-credits` must be at least 30, the Copilot CLI minimum. At tier 1 it is passed as `--max-ai-credits`. At tier 2 it caps the whole run: the runtime also gets `--max-ai-credits`, a scenario whose credits pass what is left is aborted, and the remaining scenarios fail with `skipped: credit cap reached`. `--model` applies to tiers 1 and 2. `--timeout` applies per subprocess at tier 0, to the session at tier 1, and per scenario at tier 2; the MCP check is fixed at 10 s.
+- Under a test runner (`VITEST` or `NODE_ENV=test`), a run that would call a model is refused with one `cli.guard` check before anything is spawned, unless `OMC_LIVE_SMOKE=1` (tier 1) or `OMC_LIVE_SMOKE=2` (tier 2 scenarios) is set.
+- Exit codes: `0` all checks pass, `1` a check failed or an option was invalid, `2` skipped because the `copilot` binary or, at tier 2, `@github/copilot-sdk` did not resolve and nothing else failed. Resolution order is PATH, then `COPILOT_CLI_PATH`, then the WinGet install location on Windows, so a `copilot` on PATH wins over `COPILOT_CLI_PATH`.
+- `--json` always prints a `SmokeReport`, with one `cli.error` check for invalid options. `--keep-home` keeps the temp homes and project and reports them as `artifacts.listHome` (tier 0) and `artifacts.copilotHome` (tier 1).
+- The same check is exposed as the MCP tool `host_smoke` (arguments `tier`, `pluginRoot`, `model`, `maxCredits`, `timeoutMs`, `keepHome`, `delegate`, `scenarios`). It returns the report JSON with `isError` set when any check fails. Tier 1 and tier 2 with scenarios need `OMC_SMOKE_ALLOW_LIVE=1` in the MCP server env; tier 2 with `scenarios: []` is free and needs no opt-in, and a `pluginRoot` other than the server's own package root needs `OMC_SMOKE_ALLOW_ANY_ROOT=1`. To call it from Claude Code against a local build, register the standalone server:
+
+```bash
+claude mcp add omg-dev -- node C:/Code/OMC/dist/mcp/standalone-server.js
+```
+
+`OMC_DISABLE_TOOLS=smoke` hides `host_smoke`. See [DEVELOPERS.md](./DEVELOPERS.md#headless-smoke-against-a-local-build) for the developer workflow.
+
 ### Graph approval gates (remote approvals)
 
 Graph runtime `human-approval` nodes support two gate styles via `omg graph run`:
@@ -1438,6 +1526,12 @@ From a shell, `omg doctor conflicts` checks for configuration conflicts. Among i
 - **Legacy `COPILOT_CONFIG_DIR`**: warns when it is set. OMC reads only `COPILOT_HOME`, Copilot CLI's own variable; rename it.
 - **`node` on PATH**: every hook runs `node`, and under Copilot a PreToolUse hook that cannot start denies the tool call, so a missing `node` blocks every tool.
 
+`omg doctor conflicts --json` prints the full conflict report (every check above, plus
+`hasConflicts`) as a single JSON document on stdout instead of the coloured human
+report; the human report is unchanged when `--json` is omitted. `--json` and
+`--plugin-dir` work both on `omg doctor` (flag form, e.g. `omg doctor --team-routing
+--json`) and on `omg doctor conflicts`/`omg doctor team-routing` directly.
+
 ### Configure HUD Statusline
 
 ```bash

package/docs/TOOLS.md

@@ -2,7 +2,7 @@
 
 > OMC provides MCP tools for state management, code intelligence, and data analysis.
 
-At v5.3.0, the configured MCP server exposes exactly 55 tools.
+The configured MCP server exposes exactly 56 tools.
 
 Unlike skills that users invoke directly, tools are used internally by agents during task execution.
 
@@ -19,6 +19,7 @@ Unlike skills that users invoke directly, tools are used internally by agents du
 - [Shared Memory](#shared-memory) — Cross-agent shared memory for team coordination
 - [Skills](#skills) — Internal skill management tools
 - [Deepinit Manifest](#deepinit-manifest) — Incremental AGENTS.md regeneration manifest
+- [Host Smoke](#host-smoke) — Headless Copilot CLI smoke check of a plugin root
 
 ---
 
@@ -768,3 +769,33 @@ deepinit_manifest(action="check")
 ```
 
 Used internally by the `deepinit` skill (`/oh-my-copilot:deepinit`) to enable incremental AGENTS.md regeneration instead of full re-scans.
+
+---
+
+## Host Smoke
+
+Runs the same check as `omg smoke copilot` against a plugin root and returns the `SmokeReport` JSON. The result has `isError` set when any check fails. `OMC_DISABLE_TOOLS=smoke` hides it.
+
+### Tool
+
+#### `host_smoke`
+
+| Argument     | Type    | Meaning                                                                 |
+| ------------ | ------- | ----------------------------------------------------------------------- |
+| `tier`       | 0, 1 or 2 | `0` load check without a model call (default); `1` adds one live session, one premium request; `2` adds `@github/copilot-sdk` static checks and SDK scenarios. Tier 1 needs `OMC_SMOKE_ALLOW_LIVE=1` in the server env |
+| `scenarios`  | string[] | Tier 2 only: `smoke`, `guardrail`, `skill`, `delegate`, or `all`. Omitted runs `smoke` and `guardrail`, about two premium requests (one per scenario), and needs `OMC_SMOKE_ALLOW_LIVE=1`. `[]` runs the SDK static checks only, with no model call and no opt-in |
+| `pluginRoot` | string  | Plugin root passed to `--plugin-dir`; defaults to the package root. Any other root needs `OMC_SMOKE_ALLOW_ANY_ROOT=1` |
+| `model`      | string  | Tiers 1-2 model id; omitted means Copilot auto-selects at tier 1 and a cheap listed model, else auto, at tier 2 |
+| `maxCredits` | integer | Tiers 1-2 AI credit cap, default and minimum 30. Tier 1 passes `--max-ai-credits`; tier 2 also aborts a scenario and skips the rest once the run passes it |
+| `timeoutMs`  | integer | Per subprocess at tier 0 (default 60000), for the session at tier 1 (default 180000), or per scenario at tier 2 (default 120000); the MCP check is fixed at 10 s |
+| `keepHome`   | boolean | Keep the temp `COPILOT_HOME` and project; paths are in `artifacts`      |
+| `delegate`   | boolean | Tier 1: also exercise one delegation to `oh-my-copilot:architect`       |
+
+```
+host_smoke(tier=0)
+host_smoke(tier=2, scenarios=[])   # SDK static checks, free
+```
+
+Tier 2 needs the optional peer `@github/copilot-sdk` next to the package. Without it the `sdk.*` checks fail with an install hint and the report is marked `skipped`.
+
+See [DEVELOPERS.md](./DEVELOPERS.md#headless-smoke-against-a-local-build) for the check list and how to register a local build in Claude Code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-copilot",
-  "version": "5.6.2",
+  "version": "5.8.0",
   "description": "Multi-agent orchestration system for Copilot CLI - Inspired by oh-my-opencode",
   "type": "module",
   "main": "dist/index.js",
@@ -74,6 +74,7 @@
     "test:ui": "vitest --ui --exclude \"tests/perf/**\"",
     "test:run": "vitest run --exclude \"tests/perf/**\"",
     "test:coverage": "vitest run --coverage --exclude \"tests/perf/**\"",
+    "test:live": "vitest run --config vitest.live.config.ts",
     "prepack": "npm run build",
     "lint": "eslint src",
     "format": "prettier --write src/**/*.ts",
@@ -131,6 +132,14 @@
     "typescript-eslint": "^8.53.0",
     "vitest": "^4.1.11"
   },
+  "peerDependencies": {
+    "@github/copilot-sdk": "^1.0.16"
+  },
+  "peerDependenciesMeta": {
+    "@github/copilot-sdk": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": "20.x || 22.x || 23.x || 24.x || 25.x || 26.x"
   },
@@ -159,5 +168,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "dff284086ef69f7bd488ba13346e66a90180d671"
+  "gitHead": "a63b41dee653b2fad61a2fdd840a24dd2350ffc5"
 }

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-copilot",
-  "version": "5.6.2",
+  "version": "5.8.0",
   "description": "Multi-agent orchestration system for GitHub Copilot CLI",
   "author": {
     "name": "oh-my-copilot contributors"

package/scripts/dev/repro-state-lock.mjs

@@ -1,4 +1,4 @@
-// Repro for upstream issue #4146: mutual exclusion of the owner-file fallback in
+// Repro for issue #4146: mutual exclusion of the owner-file fallback in
 // scripts/lib/state-lock.mjs (owner releases/exits during a reclaimer's liveness
 // probe; the reclaimer must not quarantine a live replacement owner).
 //

package/scripts/lib/atomic-write.mjs

@@ -137,9 +137,11 @@ function readEmergencyJournal(path) {
   } catch { return null; }
 }
 
+// BigInt ids: NTFS file IDs exceed 2^53 once the MFT sequence number reaches
+// 32, and a Number ino rounds distinct files onto the same value.
 function fileIdentity(path) {
   try {
-    const stat = statSync(path);
+    const stat = statSync(path, { bigint: true });
     return { dev: stat.dev, ino: stat.ino };
   } catch { return null; }
 }
@@ -157,7 +159,7 @@ function sameFileIdentity(a, b) {
   // On Windows, lstat returns dev=0, so skip dev comparison when on Windows
   // unless both are non-zero (indicating a real comparison is possible)
   const isWindows = process.platform === 'win32';
-  if (isWindows && (a.dev === 0 || b.dev === 0)) {
+  if (isWindows && (a.dev === 0n || b.dev === 0n)) {
     return true; // Skip dev comparison on Windows when either is 0
   }
   

package/scripts/lib/state-lock.mjs

@@ -156,33 +156,41 @@ function sameOwner(left, right) {
   return Boolean(left && right && left.pid === right.pid && left.processStart === right.processStart && left.nonce === right.nonce);
 }
 
+// BigInt ids: NTFS file IDs exceed 2^53 once the MFT sequence number reaches
+// 32, and a Number ino rounds distinct files onto the same value.
 function ownerArtifactIdentity(path) {
   try {
-    const stats = statSync(path);
+    const stats = statSync(path, { bigint: true });
     return stats.isFile() ? { dev: stats.dev, ino: stats.ino } : null;
   } catch {
     return null;
   }
 }
 
-/** Windows reports dev=0 from some stat paths (#4156); compare ino always, dev only when both are known. */
+/** Mirrors sameFileIdentity in src/lib/atomic-write.ts: ino always, dev unless win32 reports 0 (#4156). */
 function sameArtifactIdentity(a, b) {
   if (a.ino !== b.ino) return false;
-  if (process.platform === 'win32' && (a.dev === 0 || b.dev === 0)) return true;
+  if (process.platform === 'win32' && (a.dev === 0n || b.dev === 0n)) return true;
   return a.dev === b.dev;
 }
 
 /** Remove only the exact dead publication that was inspected. */
 function reclaimDeadOwner(path, observed, identity) {
-  // Fork fix: the liveness verdict can be seconds old (win32 probe), and the owner may have
-  // exited and been replaced meanwhile. Renaming a live replacement into quarantine lets a third
-  // contender publish before the restore, leaving two holders, so re-verify the exact artifact
-  // (owner record AND dev/ino, upstream #4149 checks only the latter) immediately before the rename.
-  const current = readOwner(path);
-  const currentIdentity = ownerArtifactIdentity(path);
-  if (current === 'absent' || !current || !sameOwner(current, observed) || !currentIdentity ||
-      !sameArtifactIdentity(currentIdentity, identity)) return 'changed';
   const quarantinePath = `${path}.reclaim.${process.pid}.${randomUUID()}`;
+  // The liveness verdict can be seconds old (the win32 probe spawns PowerShell),
+  // and the identity alone cannot tell a replacement apart when its inode reuses
+  // the old one (or when the identity was captured after the probe). Renaming a
+  // live replacement into quarantine opens a window in which a third contender
+  // publishes, leaving two holders. Re-verify the exact artifact, owner record
+  // AND file identity, immediately before the rename. Bracketing the read with
+  // two stats binds the record that was read to the identity that was checked.
+  const before = ownerArtifactIdentity(path);
+  const current = readOwner(path);
+  const after = ownerArtifactIdentity(path);
+  if (current === 'absent' || !current || !sameOwner(current, observed) ||
+      !before || !after || !sameArtifactIdentity(before, identity) || !sameArtifactIdentity(after, identity)) {
+    return 'changed';
+  }
   try {
     renameSync(path, quarantinePath);
   } catch (error) {
@@ -194,7 +202,8 @@ function reclaimDeadOwner(path, observed, identity) {
   try {
     moved = readOwner(quarantinePath);
     movedIdentity = ownerArtifactIdentity(quarantinePath);
-    if (moved !== 'absent' && moved && movedIdentity && sameArtifactIdentity(movedIdentity, identity) &&
+    if (moved !== 'absent' && moved && movedIdentity &&
+        sameArtifactIdentity(movedIdentity, identity) &&
         sameOwner(moved, observed)) {
       try {
         unlinkSync(quarantinePath);