[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7E9ZPQZ2VT1SQ2PG8QF37Z8":3,"skill-same:01M7E9ZPQZ2VT1SQ2PG8QF37Z8":54},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7E9ZPQZ2VT1SQ2PG8QF37Z8","pi-session-orchestration",null,"Use when you, as the controlling agent (Claude Code or Codex), delegate work to Pi worker sessions through the pi-session-mcp MCP tools (pi_capabilities_get, pi_session_start, pi_session_prompt, pi_turn_get, pi_session_abort, pi_session_close). Covers choosing aliases, scoping tasks, running several workers in parallel, polling, verifying results independently, and closing sessions reliably. Do not use inside a Pi worker session.","plagor44-ux\u002Fpi-session-mcp","plagor44-ux","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F247000753?v=4","01M7E9ZG2XRJ8MP7GA9MV9H59S","01M7E9ZG3XW2RG6PG0W49DPQB6",1,"MIT","https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp\u002Fblob\u002Fmain\u002Fskills\u002Fpi-session-orchestration\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: pi-session-orchestration\ndescription: Use when you, as the controlling agent (Claude Code or Codex), delegate work to Pi worker sessions through the pi-session-mcp MCP tools (pi_capabilities_get, pi_session_start, pi_session_prompt, pi_turn_get, pi_session_abort, pi_session_close). Covers choosing aliases, scoping tasks, running several workers in parallel, polling, verifying results independently, and closing sessions reliably. Do not use inside a Pi worker session.\n---\n\n# Orchestrating Pi worker sessions\n\nYou control Pi worker sessions through the pi-session-mcp tools. You choose only configured workspace and profile aliases. Workers do the work; you scope, monitor, verify and close.\n\n## 1. Discover first\n\n- Call `pi_capabilities_get` before anything else in a run. Use only the workspace and profile aliases it lists. Never invent an alias or pass a path.\n- Each profile lists `permissionProfile` (`read-only` or `coding`), `extensions`, `grantedExtensionTools`, `shell` (`sandboxed` gives a read-only profile a network-free sandbox shell, `none` no shell) and `skills`. These are configuration intent only: grants name configured extension tools, not proven availability; `skills` names configured skill aliases, not proof that a session loaded the skill or that the model will read it.\n- Capabilities do not prove that a provider or model is reachable. A successful `pi_session_start` shows that the session was created with the selected provider, model and thinking level, and that local authentication, the extensions, external MCP servers and selected skills passed their start checks. It does not prove that the provider accepts requests: credentials, quota and network show only when a turn runs.\n\n## 2. Scope each task\n\nWrite down before you start a worker:\n\n- goal and the single bounded problem,\n- issue or reference, if any,\n- base commit or branch the worker starts from,\n- dependencies on other tasks,\n- workspace alias,\n- the change area (files or directories) the worker may touch,\n- the checks you expect it to run,\n- the report you expect back (see section 5).\n\nSplit work so tasks do not overlap. If two tasks need the same files, run them one after the other.\n\n## 3. Pick workspace and profile\n\n- Read each workspace's `mode` from `pi_capabilities_get`. For `container` workspaces, use `pi-session-mcp` with an explicit coding profile. The host leases a full-clone writer per session; there are no per-writer tool sets or prefixes to choose.\n- If a coding start is refused because of the workspace's execution mode, do not retry or switch profiles on that server. The code is listed in [references\u002Fstart-errors.md](references\u002Fstart-errors.md).\n- Use a `read-only` profile for review, analysis and questions. Use a `coding` profile only when files must change. A `read-only` profile with granted extension tools may change files through those third-party tools in every workspace mode; never treat it as unable to write.\n- Pick a profile whose listed `skills`, `extensions` and model fit the task, for example a profile that lists `pi-session-implementation` for implementation work or `pi-session-review` for review work.\n- A listed skill is something the worker can use, not a task. Do not tell a worker to follow a skill, and never widen a task, just because its profile lists that skill. Name a skill in the prompt only when the task itself needs it.\n- On container workspaces, the pool gives concurrent coding sessions separate full clones. Capabilities list configured `writers` and `defaultBase`, not free capacity. On host workspaces, prepare a separate full-clone alias for each concurrent writer. Read-only workers without extension tool grants may share one.\n- Omit `base` for ordinary container coding starts to use the workspace default. Pass `base` only for fix rounds prepared as in section 11; it is not applicable to read-only profiles or non-container workspaces. Read `writer` and `base` from the start result and record them in the ledger; collect the returned writer, never guess a name.\n- A start that omits `base` reports `base.freshness`. With `current`, go on. With `behind`, the writer holds older code than the workspace default base: accept that knowingly when the task allows it, or close the session, run `pi-session-mcp-setup --writer \u003Cname> --finish --apply` and start again; the next start may lease another writer, so read `freshness` again. With `unknown`, compare `base.commit` with the default branch yourself before relying on it. Parallel sessions can start from different commits, so compare `base.commit` before you integrate their work.\n- A session's workspace and profile are fixed at start. Never try to switch them; start a new session instead.\n- The profile's tools set the limit. A skill grants no rights. If no listed profile can do the task, stop and report that instead of picking a more powerful one than needed.\n- Route by task type. As a default with small evidence (a few runs per profile on synthetic and maintenance tasks): give a fully specified, mechanical task to the cheapest coding profile that passed comparable tasks, a task that needs judgement or design to a stronger coding profile, and a review to a read-only profile of a different model family than the author's. Change the default when your own results disagree.\n\nWhen capabilities report routing on, use `role: code`, `review`, or `explore` instead of an explicit profile to let the server select. Omit `tier` for the server floor; set it only to raise the tier. Declare `risk: high` for security, isolation, boundaries, migrations, or irreversible changes. For a routed review, pass `authorFamily` from capabilities' `routing.families` for the profile that authored the work; for your own work use your model's corresponding configured family label. If that label is uncertain, ask rather than inventing it. Use `allowSameFamily: true` only as a conscious override when independent-family review is unavailable. Read and record the returned routing profile and reason. Explicit profiles remain available, but do not combine one with `tier`.\n\nEvery finished session needs a verdict: accepted when used without correction, reworked when corrected, rejected when not used. When history is enabled, record it with `pi-session-mcp-history verdict`; do not confuse a completed turn with accepted work.\n\n## 4. Keep a ledger\n\nKeep an internal ledger with one row per task: task, workspace alias, profile alias, `sessionId`, `turnId`, start time and time budget, status, and once the turn is terminal its `state`, `assistantText`, `truncated` and `completion`. Update it after every tool call. Decide the time budget per task and one fixed cleanup and observation budget (see section 9) when you start the run. A cap on concurrent sessions and per-task budgets are your own policy for this run. Two concurrent workers is the first tested scope, not a limit of the server; choose a cap you can supervise.\n\nRead each profile's `maxTurnSeconds` from capabilities (`null` means no server limit). Keep your per-task budgets: the server limit is a backstop for an unsupervised turn, not a replacement for supervision. Treat `abortReason: \"deadline\"` like any other aborted turn and inspect the work before reuse. If a session answers `turn_deadline_uncertain`, close it; the deadline abort was not confirmed and the session is not reusable.\n\n## 5. Start in parallel, wait on the first\n\n- Start all independent tasks (`pi_session_start`, then `pi_session_prompt`) before you wait on any of them.\n- When `pi_capabilities_get` reports `history.enabled: true`, pass a short `task` label to `pi_session_start`, such as the issue or plan id (`#215`), so the session can be found later.\n- A prompt call returns a running turn at once. Do not block on one task while others sit unstarted.\n- A session accepts one running turn. A second prompt on a running session fails with `session_running`.\n- Put the full task in the prompt: goal, base commit, change area, checks, expected report. Add nothing the task does not ask for. The worker cannot see your conversation.\n- Ask for a report whose first line is `STATUS:` with exactly one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT` or `BLOCKED`, followed by the fields you need, for code at least branch, commits, changed files, each check with its exit code, and concerns. Ask for the commit as `Commit:` followed by the bare full commit hash, with no backticks or other formatting, so you can read it directly. The fields of an implementation report and of a review report are in [references\u002Fhandoff-reports.md](references\u002Fhandoff-reports.md).\n- Tell the worker to stop with `BLOCKED` when its workspace is not at the base, and not to fetch or change the base itself.\n\n## 6. Wait for results\n\n### Event delivery\n\n`pi_capabilities_get` reports `events.delivery`. Use the wake only when it is `spool` **and** you are Claude Code in an interactive or stream-json session with the `pi-session-mcp-wake` hook installed by setup. Otherwise poll as described below. Codex and one-shot `claude -p` runs always poll.\n\n- After `pi_session_prompt` returns a running turn, do not poll it and do not sleep. Start other tasks or end your turn.\n- A system reminder `pi-session-mcp: turn \u003CturnId> of session \u003CsessionId> is \u003Cstate>.` means that turn should be terminal. Read it once with `pi_turn_get` and continue as in section 7. If that read still shows `running`, the read itself re-arms the wake; wait again. With several running turns, each wake names one turn; read only that one.\n- A reminder `pi-session-mcp: no event for turn \u003CturnId> within the wait budget` means no event arrived in time. Read that turn once. If it is still running, that read re-arms the wake; apply your time budget as usual.\n- A wake is only a trigger. The state you act on is always the one `pi_turn_get` returns.\n\n### Polling\n\n- Poll `pi_turn_get` with `sessionId` and `turnId`. There is no wait tool.\n- Cadence: first poll about 10 s after the prompt, then every 15 to 30 s, matched to the task budget: the short end for short budgets, the long end for long ones. Do not poll faster.\n- Poll only tasks that are still running in the ledger. Cycle over them and handle whichever finishes first, then continue.\n- Stop waiting on a task when its time budget is spent. Then abort it (see section 9).\n- Cost observation, specific to one client and route: in the measured Codex route (M1 pilot, 2026-10-18) every controller tool call was a new model request that re-sent the accumulated controller context, so fewer calls is the main lever there. This is not a universal billing promise for other clients or routes.\n\n## 7. Interpret progress and results\n\n- `updatedAt` on a running turn is the time of the last observed public SDK activity: assistant message start, streaming updates and end, and tool execution start, update and end. Streaming is activity, not evidence of finished or useful work. Work without a public event stays invisible, for example inside an extension's own agent loop or in a long tool call without updates. A stamp that has not moved is therefore no proof of a hang. Judge by your time budget and by the workspace.\n- `completed`, `failed` and `aborted` are terminal and immutable. On the first terminal read, record `state`, `assistantText`, `truncated` and `completion` in the ledger. In normal operation do not fetch that turn again. A deliberate re-fetch for a contract or invariance check is a separate exception; label it as such.\n- `completed` is a technical state: the turn ended and returned text. It does not mean the task succeeded. Read `assistantText` and check `truncated` and `completion`.\n- A completed turn with `completion: \"output_limit\"` or `truncated: true` is an incomplete report, input to verification, never success. Send at most one follow-up in the same session asking only for a shorter report in the agreed format; if that is also cut off, take over verification from the workspace\u002Fcollected commit. A cut-off review report is no review: do not use its verdict.\n- Check the report before you verify anything. A report without a valid `STATUS` line or without the fields you asked for is a format failure: send one follow-up in the same session that asks only for the report in the agreed format.\n- Act on the status. `NEEDS_CONTEXT`: answer only the question in the latest terminal report of that session, once, in a follow-up in the same session, and record the question and your answer in the ledger. Never answer after a later terminal turn of that session replaced the question, or after the turn was aborted or the session closed; a question that is no longer open is not answered. Allow at most two `NEEDS_CONTEXT` rounds per task; after that, decide yourself, take the task over, or stop it as in section 9. `BLOCKED`: resolve the blocker or report it; do not send the same prompt again. `DONE_WITH_CONCERNS`: read the concerns before you verify. `DONE`: verify as in section 8. A status is a claim, never evidence.\n- On an implementation task, treat a quick finish without work as an early stop, not as a result: a `completed` turn that ended soon after its prompt (for example within a minute), whose report is missing, has no valid status or claims `DONE`, and that names no commit or changed file. Judge a container writer by its report; you collect only after closing the session. Send exactly one follow-up in the same session that restates the goal and asks the worker to do the work and report. If that turn also ends without a change, count the task as failed and continue as in section 9. A valid `BLOCKED` or `NEEDS_CONTEXT` is never an early stop, and a quick review is not one either.\n- Never accept a worker report as proof. A worker saying the tests pass is a claim, not evidence.\n\n## 8. Take over and verify\n\nBefore you close a task or integrate anything:\n\n- inspect the actual files and diff in the worker's workspace, and stay within the paths you were given: do not search the machine for other files to confirm a result,\n- run the relevant tests and checks yourself,\n- compare the result with the scope you wrote down,\n- reject or send back work that is outside the change area or unverified.\n- When `history.enabled` is true, record your verdict after your own verification: `pi-session-mcp-history verdict \u003Csession> accepted|rejected|reworked --reason \"\u003Cone sentence>\"`.\n- Never pass history content (`show`, `export` or `query` output) to Pi workers, agy or other models. It is redacted, not clean.\n\nReview every code task before you integrate it:\n\n- Use a read-only profile of another model family than the author's, on the collected commit. If `pi_capabilities_get` lists a `snapshot` workspace that the operator prepared for that commit, start the reviewer there and check before the first prompt that `session.snapshot.head` equals the collected commit; a mismatch means the slot holds another commit, so close the session and report it. A snapshot session's turn can end `failed` when the tree changed during it; the session then refuses further prompts.\n- Give the reviewer the full hash of the commit under review. Ask for a report whose first line is `STATUS:`, followed by `Target:` with that bare full hash, `Verdict:` with exactly one of `BLOCKING_FINDINGS`, `NON_BLOCKING_ONLY` or `NO_FINDINGS`, and `Findings:` with one line per finding that gives severity, `path:line` and the concrete failure scenario. The fields are in [references\u002Fhandoff-reports.md](references\u002Fhandoff-reports.md).\n- Bind the report to the commit before you read anything else in it. `Target` must hold the full hash of the commit you asked about and nothing else. A report that names another commit, an abbreviated hash or none says nothing about your candidate, whatever its verdict: do not use it. For another commit, alone or beside yours, close the session and start a fresh review of the right one; do not ask the same session to correct the line. This comes first: it holds for a cut-off report and for one in the wrong form too. `Target` is a claim like the rest of the report: what the reviewer could read is fixed only by the workspace you gave it, such as a snapshot whose head you checked.\n- Only `STATUS: DONE` with a verdict is a complete review; `NO_FINDINGS` then says that the whole target was read and nothing was found. `DONE_WITH_CONCERNS` is an incomplete review: its verdict covers only what was reviewed, so have the parts under `Not reviewed` reviewed, or decide knowingly and record it. `NEEDS_CONTEXT` and `BLOCKED` carry no verdict; no review took place. A report cut off by `truncated` or `completion: \"output_limit\"` is none of these: unless it names another commit, ask once for a complete report as in section 7.\n- A finding is a claim. Check each one against the code before you act on it.\n- Fix rounds: at most three, as follow-ups in the author's session, or in a fresh session on the collected commit once that session is closed. After the third round, decide yourself: take the fix over, or reject the task.\n- Evidence for this stage is small: of four cross-family reviews in Sprint 11, one found a defect that the passing tests and the author had missed, one found that a probe could record a false negative, and every one found low-severity latent defects.\n\nYou integrate. Workers never integrate each other's changes. Resolve conflicts between workers yourself.\n\n## 9. Follow-ups, failures and aborts\n\n- Send a follow-up prompt in the same session only when the existing context fits the next step: same task, same workspace, same base. For an unrelated task, start a fresh session.\n- `failed` means `turn_failed`. The error carries no cause. Check the result in the workspace, then retry once in a fresh session with a narrower prompt, or take the task over yourself.\n- `aborted` means the turn stopped. Look at what the workspace contains before reusing it.\n- `pi_session_abort` returns `abort_failed` if the abort was rejected. The turn may still be running. Poll it.\n- `abort_timeout` is not a successful abort. The turn may still be running or may finish normally. Decide an observation and cleanup budget before you abort, for example a fixed number of polling rounds within a few minutes. Poll `pi_turn_get` until the turn is terminal or the budget is spent, then close the session with `pi_session_close`. If the close fails or does not finish, stop using that workspace, treat it as unverified and report it. Never wait without a bound.\n- If `pi_session_start` fails, classify the error by its `code` alone. Never decide by the message, provider text or any other free text, and never infer a cause. Read [references\u002Fstart-errors.md](references\u002Fstart-errors.md) only now; it lists each known code in exactly one class. Any code not listed there is Unknown. Until the code is classified, do not retry and do not switch profiles. If the reference cannot be read, do not retry at all: report the code and stop that task. Always report the code.\n- `writer_unavailable` is a capacity\u002Fstate signal, not a reason to switch profiles. Wait for sessions\u002Fcleanup or collect and finish writers; use its structured reason and counts as described in the error reference. A lost writer session must be closed and its work inspected before a fresh start.\n- If the pi-session-mcp tools are missing entirely, the server did not start. Its stderr names a `startup_failed` diagnostic (`config_path_required`, `invalid_execution_profile_config`, `invalid_thinking_level`, `invalid_execution_modes`, `invalid_event_delivery`, `invalid_history` or `event_spool_unavailable`). No MCP server is available; the operator must fix the configuration.\n\n## 10. Close every session\n\n- Call `pi_session_close` for every session you started, when its task is done, aborted, failed or abandoned. Closing is idempotent.\n- Close on every error path, too. Before you end the run, check the ledger: no session may remain open.\n- A session that is idle is still open. Closing releases its resources.\n\n## 11. Finish a task on a writer\n\nAfter taking over the result and closing its coding session, before the next task:\n\n1. Run `pi-session-mcp-setup --writer \u003Cname> --collect --apply` from the operator environment. Review the collected refs in the operator's checkout: `refs\u002Fremotes\u002Fwriter-\u003Cname>\u002F\u003Cbranch>`, with uncommitted work as `\u003Cbranch>-wip`, staged work that differs from both HEAD and the worktree as `\u003Cbranch>-index`, a clean detached HEAD as `\u003Cbase>-detached`, and each stash entry as `\u003Cbase>-stash-\u003Cn>`. They are untrusted until reviewed. Integrate only verified work yourself.\n2. Run `pi-session-mcp-setup --writer \u003Cname> --finish --apply`. It collects again, then resets a persistent writer or recreates an ephemeral writer. Do not reuse it until this succeeds. A refused branch name makes collection incomplete and finish stops: ask the operator to resolve it by renaming inside the boundary or explicitly discarding with `--reset --discard --apply`. Finish returns it to the workspace default base. No reconnect is needed after reset, finish or recreate. A setup operation on a writer held by a session fails with `writer_busy` after a short wait; close the session and allow launcher cleanup to finish.\n3. A coding start needs the writer's clone at its baseline, even after a complete collection; otherwise it fails with the controller-action code for uncollected work in [references\u002Fstart-errors.md](references\u002Fstart-errors.md). To let a fresh session continue from collected work, for example after a failed turn or for a review fix round, create a local branch at the collected ref and run `pi-session-mcp-setup --writer \u003Cname> --reset --base \u003Cbranch> --apply`, then call `pi_session_start` on `pi-session-mcp` with the coding profile and `base: \"\u003Cbranch>\"`. Read `writer` from that result for collection. Default starts cannot use a writer moved to the fix branch.\n4. Never run Git inside the writer's clone as the host user, including direct fetch from that clone. Use setup's bundle collection and inspect the imported refs in your own checkout. Never discard unreviewed work just to admit the next task.\n\nIf collect is refused because of an unmerged index, the operator can export it\nwith `pi-session-mcp-setup --writer \u003Cname> --recover --apply` and review\n`refs\u002Frecovery\u002Fwriter-\u003Cname>\u002F\u003Cslot>\u002F…` in their own checkout before any `--discard`.\nRecovery does not authorize cleanup or export all local state; decide whether\nanything outside its preserved set matters before discarding.\n\n## Limits to remember\n\n- Each client process has its own server process and its own in-memory sessions. Separate Claude Code and Codex processes do not share sessions.\n- Sessions disappear when the server process ends. Do not rely on them across restarts.\n- A `coding` profile limits Pi's tools. It is not an operating-system sandbox.\n","# Orchestrating Pi worker sessions\n\nYou control Pi worker sessions through the pi-session-mcp tools. You choose only configured workspace and profile aliases. Workers do the work; you scope, monitor, verify and close.\n\n## 1. Discover first\n\n- Call `pi_capabilities_get` before anything else in a run. Use only the workspace and profile aliases it lists. Never invent an alias or pass a path.\n- Each profile lists `permissionProfile` (`read-only` or `coding`), `extensions`, `grantedExtensionTools`, `shell` (`sandboxed` gives a read-only profile a network-free sandbox shell, `none` no shell) and `skills`. These are configuration intent only: grants name configured extension tools, not proven availability; `skills` names configured skill aliases, not proof that a session loaded the skill or that the model will read it.\n- Capabilities do not prove that a provider or model is reachable. A successful `pi_session_start` shows that the session was created with the selected provider, model and thinking level, and that local authentication, the extensions, external MCP servers and selected skills passed their start checks. It does not prove that the provider accepts requests: credentials, quota and network show only when a turn runs.\n\n## 2. Scope each task\n\nWrite down before you start a worker:\n\n- goal and the single bounded problem,\n- issue or reference, if any,\n- base commit or branch the worker starts from,\n- dependencies on other tasks,\n- workspace alias,\n- the change area (files or directories) the worker may touch,\n- the checks you expect it to run,\n- the report you expect back (see section 5).\n\nSplit work so tasks do not overlap. If two tasks need the same files, run them one after the other.\n\n## 3. Pick workspace and profile\n\n- Read each workspace's `mode` from `pi_capabilities_get`. For `container` workspaces, use `pi-session-mcp` with an explicit coding profile. The host leases a full-clone writer per session; there are no per-writer tool sets or prefixes to choose.\n- If a coding start is refused because of the workspace's execution mode, do not retry or switch profiles on that server. The code is listed in [references\u002Fstart-errors.md](references\u002Fstart-errors.md).\n- Use a `read-only` profile for review, analysis and questions. Use a `coding` profile only when files must change. A `read-only` profile with granted extension tools may change files through those third-party tools in every workspace mode; never treat it as unable to write.\n- Pick a profile whose listed `skills`, `extensions` and model fit the task, for example a profile that lists `pi-session-implementation` for implementation work or `pi-session-review` for review work.\n- A listed skill is something the worker can use, not a task. Do not tell a worker to follow a skill, and never widen a task, just because its profile lists that skill. Name a skill in the prompt only when the task itself needs it.\n- On container workspaces, the pool gives concurrent coding sessions separate full clones. Capabilities list configured `writers` and `defaultBase`, not free capacity. On host workspaces, prepare a separate full-clone alias for each concurrent writer. Read-only workers without extension tool grants may share one.\n- Omit `base` for ordinary container coding starts to use the workspace default. Pass `base` only for fix rounds prepared as in section 11; it is not applicable to read-only profiles or non-container workspaces. Read `writer` and `base` from the start result and record them in the ledger; collect the returned writer, never guess a name.\n- A start that omits `base` reports `base.freshness`. With `current`, go on. With `behind`, the writer holds older code than the workspace default base: accept that knowingly when the task allows it, or close the session, run `pi-session-mcp-setup --writer \u003Cname> --finish --apply` and start again; the next start may lease another writer, so read `freshness` again. With `unknown`, compare `base.commit` with the default branch yourself before relying on it. Parallel sessions can start from different commits, so compare `base.commit` before you integrate their work.\n- A session's workspace and profile are fixed at start. Never try to switch them; start a new session instead.\n- The profile's tools set the limit. A skill grants no rights. If no listed profile can do the task, stop and report that instead of picking a more powerful one than needed.\n- Route by task type. As a default with small evidence (a few runs per profile on synthetic and maintenance tasks): give a fully specified, mechanical task to the cheapest coding profile that passed comparable tasks, a task that needs judgement or design to a stronger coding profile, and a review to a read-only profile of a different model family than the author's. Change the default when your own results disagree.\n\nWhen capabilities report routing on, use `role: code`, `review`, or `explore` instead of an explicit profile to let the server select. Omit `tier` for the server floor; set it only to raise the tier. Declare `risk: high` for security, isolation, boundaries, migrations, or irreversible changes. For a routed review, pass `authorFamily` from capabilities' `routing.families` for the profile that authored the work; for your own work use your model's corresponding configured family label. If that label is uncertain, ask rather than inventing it. Use `allowSameFamily: true` only as a conscious override when independent-family review is unavailable. Read and record the returned routing profile and reason. Explicit profiles remain available, but do not combine one with `tier`.\n\nEvery finished session needs a verdict: accepted when used without correction, reworked when corrected, rejected when not used. When history is enabled, record it with `pi-session-mcp-history verdict`; do not confuse a completed turn with accepted work.\n\n## 4. Keep a ledger\n\nKeep an internal ledger with one row per task: task, workspace alias, profile alias, `sessionId`, `turnId`, start time and time budget, status, and once the turn is terminal its `state`, `assistantText`, `truncated` and `completion`. Update it after every tool call. Decide the time budget per task and one fixed cleanup and observation budget (see section 9) when you start the run. A cap on concurrent sessions and per-task budgets are your own policy for this run. Two concurrent workers is the first tested scope, not a limit of the server; choose a cap you can supervise.\n\nRead each profile's `maxTurnSeconds` from capabilities (`null` means no server limit). Keep your per-task budgets: the server limit is a backstop for an unsupervised turn, not a replacement for supervision. Treat `abortReason: \"deadline\"` like any other aborted turn and inspect the work before reuse. If a session answers `turn_deadline_uncertain`, close it; the deadline abort was not confirmed and the session is not reusable.\n\n## 5. Start in parallel, wait on the first\n\n- Start all independent tasks (`pi_session_start`, then `pi_session_prompt`) before you wait on any of them.\n- When `pi_capabilities_get` reports `history.enabled: true`, pass a short `task` label to `pi_session_start`, such as the issue or plan id (`#215`), so the session can be found later.\n- A prompt call returns a running turn at once. Do not block on one task while others sit unstarted.\n- A session accepts one running turn. A second prompt on a running session fails with `session_running`.\n- Put the full task in the prompt: goal, base commit, change area, checks, expected report. Add nothing the task does not ask for. The worker cannot see your conversation.\n- Ask for a report whose first line is `STATUS:` with exactly one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT` or `BLOCKED`, followed by the fields you need, for code at least branch, commits, changed files, each check with its exit code, and concerns. Ask for the commit as `Commit:` followed by the bare full commit hash, with no backticks or other formatting, so you can read it directly. The fields of an implementation report and of a review report are in [references\u002Fhandoff-reports.md](references\u002Fhandoff-reports.md).\n- Tell the worker to stop with `BLOCKED` when its workspace is not at the base, and not to fetch or change the base itself.\n\n## 6. Wait for results\n\n### Event delivery\n\n`pi_capabilities_get` reports `events.delivery`. Use the wake only when it is `spool` **and** you are Claude Code in an interactive or stream-json session with the `pi-session-mcp-wake` hook installed by setup. Otherwise poll as described below. Codex and one-shot `claude -p` runs always poll.\n\n- After `pi_session_prompt` returns a running turn, do not poll it and do not sleep. Start other tasks or end your turn.\n- A system reminder `pi-session-mcp: turn \u003CturnId> of session \u003CsessionId> is \u003Cstate>.` means that turn should be terminal. Read it once with `pi_turn_get` and continue as in section 7. If that read still shows `running`, the read itself re-arms the wake; wait again. With several running turns, each wake names one turn; read only that one.\n- A reminder `pi-session-mcp: no event for turn \u003CturnId> within the wait budget` means no event arrived in time. Read that turn once. If it is still running, that read re-arms the wake; apply your time budget as usual.\n- A wake is only a trigger. The state you act on is always the one `pi_turn_get` returns.\n\n### Polling\n\n- Poll `pi_turn_get` with `sessionId` and `turnId`. There is no wait tool.\n- Cadence: first poll about 10 s after the prompt, then every 15 to 30 s, matched to the task budget: the short end for short budgets, the long end for long ones. Do not poll faster.\n- Poll only tasks that are still running in the ledger. Cycle over them and handle whichever finishes first, then continue.\n- Stop waiting on a task when its time budget is spent. Then abort it (see section 9).\n- Cost observation, specific to one client and route: in the measured Codex route (M1 pilot, 2026-10-18) every controller tool call was a new model request that re-sent the accumulated controller context, so fewer calls is the main lever there. This is not a universal billing promise for other clients or routes.\n\n## 7. Interpret progress and results\n\n- `updatedAt` on a running turn is the time of the last observed public SDK activity: assistant message start, streaming updates and end, and tool execution start, update and end. Streaming is activity, not evidence of finished or useful work. Work without a public event stays invisible, for example inside an extension's own agent loop or in a long tool call without updates. A stamp that has not moved is therefore no proof of a hang. Judge by your time budget and by the workspace.\n- `completed`, `failed` and `aborted` are terminal and immutable. On the first terminal read, record `state`, `assistantText`, `truncated` and `completion` in the ledger. In normal operation do not fetch that turn again. A deliberate re-fetch for a contract or invariance check is a separate exception; label it as such.\n- `completed` is a technical state: the turn ended and returned text. It does not mean the task succeeded. Read `assistantText` and check `truncated` and `completion`.\n- A completed turn with `completion: \"output_limit\"` or `truncated: true` is an incomplete report, input to verification, never success. Send at most one follow-up in the same session asking only for a shorter report in the agreed format; if that is also cut off, take over verification from the workspace\u002Fcollected commit. A cut-off review report is no review: do not use its verdict.\n- Check the report before you verify anything. A report without a valid `STATUS` line or without the fields you asked for is a format failure: send one follow-up in the same session that asks only for the report in the agreed format.\n- Act on the status. `NEEDS_CONTEXT`: answer only the question in the latest terminal report of that session, once, in a follow-up in the same session, and record the question and your answer in the ledger. Never answer after a later terminal turn of that session replaced the question, or after the turn was aborted or the session closed; a question that is no longer open is not answered. Allow at most two `NEEDS_CONTEXT` rounds per task; after that, decide yourself, take the task over, or stop it as in section 9. `BLOCKED`: resolve the blocker or report it; do not send the same prompt again. `DONE_WITH_CONCERNS`: read the concerns before you verify. `DONE`: verify as in section 8. A status is a claim, never evidence.\n- On an implementation task, treat a quick finish without work as an early stop, not as a result: a `completed` turn that ended soon after its prompt (for example within a minute), whose report is missing, has no valid status or claims `DONE`, and that names no commit or changed file. Judge a container writer by its report; you collect only after closing the session. Send exactly one follow-up in the same session that restates the goal and asks the worker to do the work and report. If that turn also ends without a change, count the task as failed and continue as in section 9. A valid `BLOCKED` or `NEEDS_CONTEXT` is never an early stop, and a quick review is not one either.\n- Never accept a worker report as proof. A worker saying the tests pass is a claim, not evidence.\n\n## 8. Take over and verify\n\nBefore you close a task or integrate anything:\n\n- inspect the actual files and diff in the worker's workspace, and stay within the paths you were given: do not search the machine for other files to confirm a result,\n- run the relevant tests and checks yourself,\n- compare the result with the scope you wrote down,\n- reject or send back work that is outside the change area or unverified.\n- When `history.enabled` is true, record your verdict after your own verification: `pi-session-mcp-history verdict \u003Csession> accepted|rejected|reworked --reason \"\u003Cone sentence>\"`.\n- Never pass history content (`show`, `export` or `query` output) to Pi workers, agy or other models. It is redacted, not clean.\n\nReview every code task before you integrate it:\n\n- Use a read-only profile of another model family than the author's, on the collected commit. If `pi_capabilities_get` lists a `snapshot` workspace that the operator prepared for that commit, start the reviewer there and check before the first prompt that `session.snapshot.head` equals the collected commit; a mismatch means the slot holds another commit, so close the session and report it. A snapshot session's turn can end `failed` when the tree changed during it; the session then refuses further prompts.\n- Give the reviewer the full hash of the commit under review. Ask for a report whose first line is `STATUS:`, followed by `Target:` with that bare full hash, `Verdict:` with exactly one of `BLOCKING_FINDINGS`, `NON_BLOCKING_ONLY` or `NO_FINDINGS`, and `Findings:` with one line per finding that gives severity, `path:line` and the concrete failure scenario. The fields are in [references\u002Fhandoff-reports.md](references\u002Fhandoff-reports.md).\n- Bind the report to the commit before you read anything else in it. `Target` must hold the full hash of the commit you asked about and nothing else. A report that names another commit, an abbreviated hash or none says nothing about your candidate, whatever its verdict: do not use it. For another commit, alone or beside yours, close the session and start a fresh review of the right one; do not ask the same session to correct the line. This comes first: it holds for a cut-off report and for one in the wrong form too. `Target` is a claim like the rest of the report: what the reviewer could read is fixed only by the workspace you gave it, such as a snapshot whose head you checked.\n- Only `STATUS: DONE` with a verdict is a complete review; `NO_FINDINGS` then says that the whole target was read and nothing was found. `DONE_WITH_CONCERNS` is an incomplete review: its verdict covers only what was reviewed, so have the parts under `Not reviewed` reviewed, or decide knowingly and record it. `NEEDS_CONTEXT` and `BLOCKED` carry no verdict; no review took place. A report cut off by `truncated` or `completion: \"output_limit\"` is none of these: unless it names another commit, ask once for a complete report as in section 7.\n- A finding is a claim. Check each one against the code before you act on it.\n- Fix rounds: at most three, as follow-ups in the author's session, or in a fresh session on the collected commit once that session is closed. After the third round, decide yourself: take the fix over, or reject the task.\n- Evidence for this stage is small: of four cross-family reviews in Sprint 11, one found a defect that the passing tests and the author had missed, one found that a probe could record a false negative, and every one found low-severity latent defects.\n\nYou integrate. Workers never integrate each other's changes. Resolve conflicts between workers yourself.\n\n## 9. Follow-ups, failures and aborts\n\n- Send a follow-up prompt in the same session only when the existing context fits the next step: same task, same workspace, same base. For an unrelated task, start a fresh session.\n- `failed` means `turn_failed`. The error carries no cause. Check the result in the workspace, then retry once in a fresh session with a narrower prompt, or take the task over yourself.\n- `aborted` means the turn stopped. Look at what the workspace contains before reusing it.\n- `pi_session_abort` returns `abort_failed` if the abort was rejected. The turn may still be running. Poll it.\n- `abort_timeout` is not a successful abort. The turn may still be running or may finish normally. Decide an observation and cleanup budget before you abort, for example a fixed number of polling rounds within a few minutes. Poll `pi_turn_get` until the turn is terminal or the budget is spent, then close the session with `pi_session_close`. If the close fails or does not finish, stop using that workspace, treat it as unverified and report it. Never wait without a bound.\n- If `pi_session_start` fails, classify the error by its `code` alone. Never decide by the message, provider text or any other free text, and never infer a cause. Read [references\u002Fstart-errors.md](references\u002Fstart-errors.md) only now; it lists each known code in exactly one class. Any code not listed there is Unknown. Until the code is classified, do not retry and do not switch profiles. If the reference cannot be read, do not retry at all: report the code and stop that task. Always report the code.\n- `writer_unavailable` is a capacity\u002Fstate signal, not a reason to switch profiles. Wait for sessions\u002Fcleanup or collect and finish writers; use its structured reason and counts as described in the error reference. A lost writer session must be closed and its work inspected before a fresh start.\n- If the pi-session-mcp tools are missing entirely, the server did not start. Its stderr names a `startup_failed` diagnostic (`config_path_required`, `invalid_execution_profile_config`, `invalid_thinking_level`, `invalid_execution_modes`, `invalid_event_delivery`, `invalid_history` or `event_spool_unavailable`). No MCP server is available; the operator must fix the configuration.\n\n## 10. Close every session\n\n- Call `pi_session_close` for every session you started, when its task is done, aborted, failed or abandoned. Closing is idempotent.\n- Close on every error path, too. Before you end the run, check the ledger: no session may remain open.\n- A session that is idle is still open. Closing releases its resources.\n\n## 11. Finish a task on a writer\n\nAfter taking over the result and closing its coding session, before the next task:\n\n1. Run `pi-session-mcp-setup --writer \u003Cname> --collect --apply` from the operator environment. Review the collected refs in the operator's checkout: `refs\u002Fremotes\u002Fwriter-\u003Cname>\u002F\u003Cbranch>`, with uncommitted work as `\u003Cbranch>-wip`, staged work that differs from both HEAD and the worktree as `\u003Cbranch>-index`, a clean detached HEAD as `\u003Cbase>-detached`, and each stash entry as `\u003Cbase>-stash-\u003Cn>`. They are untrusted until reviewed. Integrate only verified work yourself.\n2. Run `pi-session-mcp-setup --writer \u003Cname> --finish --apply`. It collects again, then resets a persistent writer or recreates an ephemeral writer. Do not reuse it until this succeeds. A refused branch name makes collection incomplete and finish stops: ask the operator to resolve it by renaming inside the boundary or explicitly discarding with `--reset --discard --apply`. Finish returns it to the workspace default base. No reconnect is needed after reset, finish or recreate. A setup operation on a writer held by a session fails with `writer_busy` after a short wait; close the session and allow launcher cleanup to finish.\n3. A coding start needs the writer's clone at its baseline, even after a complete collection; otherwise it fails with the controller-action code for uncollected work in [references\u002Fstart-errors.md](references\u002Fstart-errors.md). To let a fresh session continue from collected work, for example after a failed turn or for a review fix round, create a local branch at the collected ref and run `pi-session-mcp-setup --writer \u003Cname> --reset --base \u003Cbranch> --apply`, then call `pi_session_start` on `pi-session-mcp` with the coding profile and `base: \"\u003Cbranch>\"`. Read `writer` from that result for collection. Default starts cannot use a writer moved to the fix branch.\n4. Never run Git inside the writer's clone as the host user, including direct fetch from that clone. Use setup's bundle collection and inspect the imported refs in your own checkout. Never discard unreviewed work just to admit the next task.\n\nIf collect is refused because of an unmerged index, the operator can export it\nwith `pi-session-mcp-setup --writer \u003Cname> --recover --apply` and review\n`refs\u002Frecovery\u002Fwriter-\u003Cname>\u002F\u003Cslot>\u002F…` in their own checkout before any `--discard`.\nRecovery does not authorize cleanup or export all local state; decide whether\nanything outside its preserved set matters before discarding.\n\n## Limits to remember\n\n- Each client process has its own server process and its own in-memory sessions. Separate Claude Code and Codex processes do not share sessions.\n- Sessions disappear when the server process ends. Do not rely on them across restarts.\n- A `coding` profile limits Pi's tools. It is not an operating-system sandbox.\n",{"name":5,"description":7},"main","51b3c1a1ed3f78e5e2e67f46e70e5dedd2b4398b","skills\u002Fpi-session-orchestration",0,"https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp","https:\u002F\u002Fgithub.com\u002Fplagor44-ux","2026-11-15 05:37:33",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add plagor44-ux\u002Fpi-session-mcp --skill pi-session-orchestration",{"tool":36,"command":37},"bunx","bunx skills add plagor44-ux\u002Fpi-session-mcp --skill pi-session-orchestration",{"tool":39,"command":40},"pnpm","pnpm dlx skills add plagor44-ux\u002Fpi-session-mcp --skill pi-session-orchestration","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp\u002Fblob\u002Fmain\u002Fskills\u002Fpi-session-orchestration\u002FSKILL.md",true,[44,50],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"references\u002Fhandoff-reports.md","REFERENCE","参考文档",9499,"https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp\u002Fblob\u002Fmain\u002Fskills\u002Fpi-session-orchestration\u002Freferences\u002Fhandoff-reports.md",{"path":51,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":52,"sourceHtmlUrl":53},"references\u002Fstart-errors.md",4896,"https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp\u002Fblob\u002Fmain\u002Fskills\u002Fpi-session-orchestration\u002Freferences\u002Fstart-errors.md",[55,62,69,76,82,89],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":18},"01M7EA0VRZXAWYP21T2PDENDWS","fixture-bundled","BUNDLED_DESCRIPTION_SENTINEL","https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fpi-skill-fixtures\u002Fpackage\u002Fskills\u002Ffixture-bundled\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":18},"01M7EA0RN37ZRF5FE1QYD0822N","fixture-alpha","BUNDLED_ALPHA_DESCRIPTION_SENTINEL","https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fpi-skill-fixtures\u002Fpackage\u002Fskills\u002Ffixture-alpha\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":18},"01M7EA0NG5GQWTZNXTX3005Z7R","fixture-late","LATE_DESCRIPTION_SENTINEL","https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fpi-skill-fixtures\u002Fpackage\u002Flate\u002Ffixture-late\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":18},"01M7EA0JPCN31Q313DMJ8GV1WH","fixture-invalid","https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fpi-skill-fixtures\u002Ffixture-invalid\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":18},"01M7EA0H530SYTSZGEDKBCGB4A","fixture-explicit","EXPLICIT_DESCRIPTION_SENTINEL","https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fpi-skill-fixtures\u002Ffixture-explicit\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":18},"01M7EA0FW23PCGHYA6JP588NWW","fixture-beta","SELECTED_BETA_DESCRIPTION_SENTINEL","https:\u002F\u002Fgithub.com\u002Fplagor44-ux\u002Fpi-session-mcp\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fpi-skill-fixtures\u002Ffixture-beta\u002FSKILL.md",[],[]]