feat: add strict Conductor orchestration to Poteto Mode

.agents/plugins/marketplace.json

@@ -6,6 +6,7 @@
   "plugins": [
     {
       "name": "pstack",
+      "version": "1.4.0",
       "source": {
         "source": "local",
         "path": "./plugins/pstack"

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "pstack",
       "source": "./plugins/pstack",
       "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "author": {
         "name": "Lauren Tan (original)"
       },

CHANGES.md

@@ -2,6 +2,37 @@
 
 This port applies the Cursor → Claude Code substitutions in skill bodies. Earlier drafts left them flagged; this revision resolves them. A later pass added a Codex build that shares the same skills; see [Codex port](#codex-port) below.
 
+## 1.4.0 adds opt-in Conductor orchestration
+
+**Opt-in Conductor orchestration.** A repository can now select a strict
+Conductor route with `.conductor/poteto-mode.json`. The Claude or Codex session
+that invokes Poteto Mode remains the fixed coordinator. Every delegated Claude,
+Codex, or Cursor worker receives an isolated Conductor workspace and branch.
+Cursor provides the Grok lane through its exact Conductor agent and model pair.
+
+The new local helper validates the project policy and live model catalog,
+persists fixed run budgets and retry-safe message IDs, parses untrusted MCP
+responses, verifies post-create and post-run session receipts, accepts one
+attempt-matched assistant result, and emits run-scoped cleanup targets. It does
+not make network calls or read credentials. Missing identity, catalog entries,
+response fields, or receipts fail the lane without a native, portable-runner,
+effort, agent, or model fallback.
+
+Setup detects Conductor projects before portable model-sheet configuration.
+It validates `whoami`, the coordinator session status, and `list_models`, then
+runs one isolated marker smoke while leaving both user model sheets untouched.
+Poteto workers refuse recursive invocation before loading the skill. Arena,
+Architect, How, Interrogate, Reflect, and Swarm follow the dispatch route chosen
+by the parent instead of bypassing it.
+
+The Conductor unit, strict type, and static contract suites cover policy,
+state transitions, uncertain create reconciliation, exact receipts, transcript
+trust, CLI lifecycle, cleanup safety, and worker refusal. Published-contract
+fixtures are deliberately labeled as non-live. Release is gated on running the
+exact candidate from real Claude and Codex Conductor coordinator sessions.
+
+**Claude poteto-agent preload.** The Claude Code agent definition preloads `pstack:poteto-mode` through its `skills` frontmatter. Claude subagents start with isolated context, so the upstream prompt alone exposed the skill name but not its body. The shared skill tree and the Codex path are unchanged. The static invariants preserve the binding, and the behavioral check proves that the packaged agent can read a named principle without invoking `Skill` or reading a file.
+
 ## 1.3.0 syncs to Cursor pstack 0.14.7
 
 Open Pstack now tracks Cursor pstack 0.14.7 at `efa2a531985e0a8084d36ff3cf87233be8a9f34b`.
@@ -197,7 +228,7 @@ pstack diverges from superpowers in one respect, and it is deliberate. superpowe
 
 **Verified.** Codex discovers the skills and namespaces them under `pstack` (`pstack:poteto-mode` and so on) in a live session. Mapping resolution mid-task and `spawn_agent` fan-out follow the `superpowers` pattern and are worth confirming per session.
 
-**Maintenance.** The open-pstack version string lives in `plugins/pstack/.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `plugins/pstack/.codex-plugin/plugin.json`, and the current-version row in `UPSTREAM.md`. A version bump must update all four. `tests/skill-collision-repro.sh` checks that they match. `.agents/plugins/marketplace.json` carries no version field. The canonical default panel quad is the model matrix in `provider-dispatch.md` (`provider:model@default` in family-row order). It is copied into the four panel skills (`arena`, `architect`, `how`, `interrogate`) and the `setup-pstack` first-run sheet. Keep those copies grep-identical when models change. The static test derives the quad from the matrix. After a sync that touches `skills/poteto-mode/scripts/`, run `bun install --frozen-lockfile`, `bun run test`, and `bun run typecheck` from that directory. `hooks/session-start-context.md` restates skill one-liners. Re-verify it whenever skill names or descriptions change. The package must not contain a `commands/` layer. Claude Code and Codex load the native `skills/` tree directly, and a command layer duplicates that inventory. The 21 `principle-*` leaves carry `user-invocable: false` to request exclusion from the user picker while `poteto-mode` reads them by path. Claude honors the metadata; Codex 0.149.0 currently does not ([#8](https://github.com/ericlitman/open-pstack/issues/8)). They must not carry `disable-model-invocation`, which would make them unreachable to the model. Re-run the behavioral mode of `tests/skill-collision-repro.sh` after Claude Code upgrades to check both model-initiated and user-initiated native skill invocation.
+**Maintenance.** The open-pstack version string lives in `plugins/pstack/.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.agents/plugins/marketplace.json`, `plugins/pstack/.codex-plugin/plugin.json`, and the current-version row in `UPSTREAM.md`. A version bump must update all five. `tests/skill-collision-repro.sh` checks that they match. The canonical default panel quad is the model matrix in `provider-dispatch.md` (`provider:model@default` in family-row order). It is copied into the four panel skills (`arena`, `architect`, `how`, `interrogate`) and the `setup-pstack` first-run sheet. Keep those copies grep-identical when models change. The static test derives the quad from the matrix. After a sync that touches `skills/poteto-mode/scripts/`, run `bun install --frozen-lockfile`, `bun run test`, and `bun run typecheck` from that directory. `hooks/session-start-context.md` restates skill one-liners. Re-verify it whenever skill names or descriptions change. The package must not contain a `commands/` layer. Claude Code and Codex load the native `skills/` tree directly, and a command layer duplicates that inventory. The 21 `principle-*` leaves carry `user-invocable: false` to request exclusion from the user picker while `poteto-mode` reads them by path. Claude honors the metadata; Codex 0.149.0 currently does not ([#8](https://github.com/ericlitman/open-pstack/issues/8)). They must not carry `disable-model-invocation`, which would make them unreachable to the model. Re-run the behavioral mode of `tests/skill-collision-repro.sh` after Claude Code upgrades to check both model-initiated and user-initiated native skill invocation.
 
 ## 0.9.2 sync (against upstream `e46364b`)
 

NOTICE.md

@@ -32,6 +32,7 @@ Summary of structural changes:
 - `plugins/pstack/skills/babysit/` is independently authored as the Claude Code analog of Cursor's `/babysit` built-in. It has no upstream pstack equivalent; its workflow is informed by Cursor's public `/babysit` behavior. No code or prose was copied from any source.
 - `plugins/pstack/skills/poteto-mode/scripts/` is vendored from upstream (`watch-pr`, `orch`, `bootstrap.ts`, `worktree-audit.sh`, `package.json`, `bun.lock`) with these port edits: `worktree-audit.sh` reads `~/.claude/projects/` instead of Cursor's transcript directory and warns when `jq` or `rg` is missing (their absence silently blanks the columns the prune decision reads), the private workspace package is named `@open-pstack/poteto-mode-tools`, `bootstrap.ts` rejects Node before it reads Bun-only APIs, and `package.json` includes the port-authored tests in `bun run test`. `check-plan.mjs` is the Cursor 0.14.3 checker adapted for the shared Claude Code and Codex skeleton. `bootstrap.test.ts` and `check-plan.test.ts` are authored for this port.
 - `plugins/pstack/agents/comment-sicko.md` is upstream's `Comment Sicko` agent, renamed to `comment-sicko` so the name works as a Claude Code `subagent_type`. The body is verbatim.
+- `plugins/pstack/agents/poteto-agent.md` keeps the upstream prompt and adds Claude Code `skills` frontmatter so the isolated subagent preloads `pstack:poteto-mode`.
 - Claude-native Fable and Opus lanes are port-authored agent definitions. They select the rolling family alias plus requested effort for every selectable Claude-native pair in the provider-dispatch model matrix.
 - A Codex build shares the same `skills/` tree. It adds `plugins/pstack/.codex-plugin/plugin.json`, a root `.agents/plugins/marketplace.json`, and `plugins/pstack/skills/poteto-mode/references/codex-tools.md` (the Claude-to-Codex tool, model, and built-in map), plus a one-line Platform note in the skills that name a Claude primitive. The skill content itself is unchanged. See [CHANGES.md](CHANGES.md#codex-port).
 

UPSTREAM.md

@@ -10,9 +10,9 @@ open-pstack tracks [Cursor's pstack](https://github.com/cursor/plugins/tree/main
 | Path | `pstack/` |
 | Commit | `efa2a531985e0a8084d36ff3cf87233be8a9f34b` |
 | Upstream version | `0.14.7` |
-| open-pstack version | `1.3.0` |
+| open-pstack version | `1.4.0` |
 
-The table above is the current Cursor sync point. Open Pstack 1.3.0 keeps this 0.14.7 sync. `README-UPSTREAM.md` preserves its pstack README verbatim. `CHANGES.md` and `NOTICE.md` describe the adaptations and provenance.
+The table above is the current Cursor sync point. Open Pstack 1.4.0 keeps this 0.14.7 sync. `README-UPSTREAM.md` preserves its pstack README verbatim. `CHANGES.md` and `NOTICE.md` describe the adaptations and provenance.
 
 ## Upstream-only exclusions
 

docs/reference.md

@@ -60,8 +60,8 @@ The marketplace install is the normal user path. Direct links are only for testi
 │   ├── .claude-plugin/plugin.json    # Claude Code manifest
 │   ├── .codex-plugin/plugin.json     # Codex manifest (skills: ./skills/)
 │   ├── skills/                       # 52 skills shared by Claude Code and Codex
-│   │   ├── poteto-mode/references/{codex-tools,provider-dispatch}.md  # tool + provider routing
-│   │   └── poteto-mode/scripts/      # bun/bash/node tooling: watch-pr, orch, runner, check-plan.mjs, worktree-audit.sh
+│   │   ├── poteto-mode/references/{codex-tools,provider-dispatch,conductor-dispatch}.md
+│   │   └── poteto-mode/scripts/      # bun/bash/node tooling, including the Conductor boundary helper
 │   ├── hooks/                        # SessionStart auto-fire: injects the poteto-mode mandate (Claude Code only)
 │   └── agents/                       # Claude subagents, including native Fable and Opus lanes at each selectable effort
 ├── tests/skill-collision-repro.sh    # native-skill package invariants and Claude invocation checks
@@ -79,7 +79,7 @@ Plugin-internal `skills/<name>/` path references in the docs below are relative
 
 ## Running on Codex
 
-The Codex build shares one `skills/` tree with the Claude Code build. Nothing is forked or generated. Two narrow references keep runtime translation separate: `codex-tools.md` maps harness primitives and `provider-dispatch.md` maps model providers. pstack otherwise keeps the upstream Claude-native prose and adds a one-line Platform note to each skill that names a Claude primitive, so the port stays in lockstep with upstream sync.
+The Codex build shares one `skills/` tree with the Claude Code build. Nothing is forked or generated. `codex-tools.md` maps harness primitives. Projects without Conductor mode use `provider-dispatch.md` for model-provider routing. Conductor projects use `conductor-dispatch.md` instead. pstack otherwise keeps the upstream Claude-native prose and adds a one-line Platform note to each skill that names a Claude primitive, so the port stays in lockstep with upstream sync.
 
 - **Skill invocation.** Codex loads `SKILL.md` natively. There is no `Skill` tool. You invoke a skill by name (ask for it, or pick `pstack:poteto-mode` from the list).
 - **Package surface.** The native `skills/` tree is the only workflow source. The plugin ships no `commands/` layer and does not link prompts into `~/.codex/prompts/`. Codex would migrate such files into duplicate source-command skills while loading the native skill tree. The 21 `principle-*` leaves declare `user-invocable: false`. Claude keeps them out of its user picker; Codex 0.149.0 currently shows them despite that metadata ([#8](https://github.com/ericlitman/open-pstack/issues/8)).
@@ -90,6 +90,46 @@ The Codex build shares one `skills/` tree with the Claude Code build. Nothing is
 
 Verified in fresh installed Claude Code and Codex sessions: the user-facing skills are discovered and namespaced under `pstack`; both parents fan out the frontier quad through the documented native/external route table, retain long-running handles without a default timeout, and cross-judge only after every candidate is terminal. The `principle-*` leaves remain available for `poteto-mode` to read by path. Claude honors their `user-invocable: false` metadata; Codex 0.149.0 does not ([#8](https://github.com/ericlitman/open-pstack/issues/8)).
 
+## Conductor project mode
+
+Conductor mode is opt-in per repository. It activates only when the nearest
+`.conductor/poteto-mode.json` passes the strict version-one parser and declares
+`"mode": "conductor"`. Projects without that policy keep the portable routing
+described above.
+
+The invoking Claude or Codex session remains the coordinator. It binds the
+run to `CONDUCTOR_SESSION_ID`, validates the authenticated workspace through
+`whoami` and `get_session_status`, and resolves every role from committed
+project policy. It does not elect another coordinator or use a personal model
+sheet.
+
+Every delegated worker gets a separate Conductor workspace and branch. This
+includes read-only exploration and review. Claude, Codex, and Cursor are agent
+choices at the Conductor boundary, so a project can route Grok through Cursor
+without installing a local Grok launcher. Each worker receives a complete
+prompt plus `PSTACK_WORKER=1`, which prevents recursive Poteto dispatch.
+
+The `scripts/conductor/pstack-conductor` executable is a local policy and state
+boundary. It parses saved MCP responses, fixes run ceilings, records stable
+message IDs, validates post-create and post-run model receipts, accepts one
+attempt-matched assistant result, and emits cleanup targets. It does not call
+Conductor over HTTP or read authentication data. The coordinator performs the
+MCP calls documented in
+[`conductor-dispatch.md`](../plugins/pstack/skills/poteto-mode/references/conductor-dispatch.md).
+
+Setup calls the hosted [Conductor MCP
+server](https://www.conductor.build/docs/api/mcp), checks the live catalog, and
+runs one isolated marker smoke. It leaves `~/.claude/pstack-models.md` and
+`~/.codex/pstack-models.md` unchanged. Missing authentication, unavailable
+models, receipt mismatches, unknown workspace creation, or malformed results
+fail closed. There is no native-agent, portable-runner, lower-effort, or model
+fallback.
+
+The implementation ships contract fixtures derived from Conductor's published
+API shapes. They are not live evidence. A release remains blocked until the
+exact candidate completes the acceptance matrix from real Claude and Codex
+Conductor coordinator sessions.
+
 ## Dependencies
 
 Nothing is declared in `plugin.json`. Install the one companion plugin yourself:
@@ -110,6 +150,7 @@ Not declared as deps, but referenced in skill bodies:
 - **`bun`** — runs the vendored `skills/poteto-mode/scripts/` tooling (`watch-pr`, `orch`, `runner`). Install via [`brew install oven-sh/bun/bun`](https://bun.sh). `bootstrap.ts` installs dependencies for `watch-pr` and `orch`; the runner uses only Bun and Node built-ins, so it launches directly without an install/re-exec layer.
 - **`node`** — runs `skills/poteto-mode/scripts/check-plan.mjs`. The checker uses only Node built-ins and does not need Bun.
 - **Claude Code, Codex, and Grok Build CLIs** — the external runner uses the assigned subscribed CLI directly. Install and authenticate only the providers present in your model sheet. Same-provider work stays native; the runner refuses it.
+- **Conductor MCP server.** Required only for repositories that enable Conductor mode. Connect `https://api.conductor.build/mcp` through OAuth or the harness's supported bearer-token environment. The local helper never receives that credential.
 - **`jq` and `rg` (ripgrep)** — only for `scripts/worktree-audit.sh` (the Worktree cleanup playbook). Without them the audit still runs but blanks its PR and LAST_CHAT columns, so it warns on stderr rather than returning a table that looks complete.
 
 No third-party plugins. The harsher-critique escape hatch lives in the bundled `thermo-nuclear-code-quality-review` skill (imported from cursor-team-kit), not in an external plugin.
@@ -154,7 +195,7 @@ The table uses the short upstream names. Claude Code exposes each native skill w
 
 ## Subagents
 
-`poteto-agent` ships unchanged. Spawn from a parent with `subagent_type: "poteto-agent"`.
+`poteto-agent` keeps the upstream prompt and adds Claude Code `skills` frontmatter. The field preloads `pstack:poteto-mode` because Claude subagents do not inherit the parent's loaded skills. Spawn the agent from a parent with `subagent_type: "poteto-agent"`.
 
 `comment-sicko` is the read-only comment reviewer the `no-comments` skill spawns. Upstream names it `Comment Sicko`; the port renames it to `comment-sicko` so the name is a valid `subagent_type`. Invoke it through `/no-comments`, not directly.
 

plugins/pstack/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pstack",
   "displayName": "pstack",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence. Ported from cursor/plugins/pstack for Claude Code and Codex.",
   "author": {
     "name": "Lauren Tan"

plugins/pstack/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pstack",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence. Codex port of the Claude Code plugin; skills are shared, tool names resolve via skills/poteto-mode/references/codex-tools.md.",
   "author": {
     "name": "Lauren Tan"

plugins/pstack/agents/poteto-agent.md

@@ -1,8 +1,12 @@
 ---
 name: poteto-agent
 description: Routing target for `/poteto-mode` and any request for poteto's style. Resume an existing `poteto-agent` for the conversation rather than spawning a sibling. Reads the `poteto-mode` skill's `SKILL.md` in full before any work, including its inline Principles index. Substituting `general-purpose` skips that read and drifts.
+skills:
+  - pstack:poteto-mode
 ---
 
 # Poteto subagent
 
+If `PSTACK_WORKER=1`, stop before reading the skill or doing any work. A Conductor Poteto worker cannot invoke Poteto Mode or dispatch another worker.
+
 You are operating as poteto-mode's full agent style. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. Navigate to a leaf `principle-*` skill whenever you apply that principle.