pi-session-mcp 0.8.3 → 0.12.0

package/scripts/isolation-probe.cjs

@@ -0,0 +1,213 @@
+// Provider-free probe for the ADR 0008 isolation acceptance (docs/isolation-setup.md).
+//
+// scripts/isolation-acceptance.mjs pipes this file to `<launch prefix> - <config>`, so it runs inside
+// the boundary under test as the boundary's Node.js process. It reads its configuration from argv[2]
+// (base64url JSON), attempts the escapes listed there through Node.js file writes and through
+// `bash -c`, observes credentials, environment, namespaces and network, and prints exactly one line
+// "ISOLATION_PROBE_RESULT <json>" on stdout. The harness consumes that line and never copies it into
+// its own report.
+//
+// Safety: the probe only creates NEW files (O_EXCL / noclobber) whose names carry the per-run token,
+// and appends one comment line to the config of the harness-owned disposable source repository. It
+// never reads file contents, never runs a mutating remote command and never prints a path or value.
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const cp = require("node:child_process");
+const net = require("node:net");
+
+const config = JSON.parse(Buffer.from(process.argv[2] || "", "base64url").toString("utf8"));
+const home = os.homedir();
+const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(home, ".pi", "agent");
+
+const sanitizeCode = (code) => (typeof code === "string" && /^[A-Z0-9_]{2,16}$/.test(code) ? code : "OTHER");
+
+function bashCode(stderr) {
+  const text = String(stderr || "");
+  if (/read-only file system/i.test(text)) return "EROFS";
+  if (/permission denied/i.test(text)) return "EACCES";
+  if (/no such file/i.test(text)) return "ENOENT";
+  if (/not a directory/i.test(text)) return "ENOTDIR";
+  if (/cannot overwrite|file exists/i.test(text)) return "EEXIST";
+  return "OTHER";
+}
+
+// Create attempts get a per-method suffix so the node and bash attempt never collide on one name.
+function nodeAttempt(target, kind) {
+  try {
+    if (kind === "append") fs.appendFileSync(target, `\n# ${config.prefix}-node\n`);
+    else fs.writeFileSync(`${target}-node`, "x\n", { flag: "wx" });
+    return { blocked: false, error_code: null };
+  } catch (error) {
+    return { blocked: true, error_code: sanitizeCode(error && error.code) };
+  }
+}
+
+let bashAvailable = true;
+function bashAttempt(target, kind) {
+  const script = 'set -C; if [ "$K" = append ]; then printf "\\n# %s-bash\\n" "$M" >> "$T"; else printf "x\\n" > "$T-bash"; fi';
+  const result = cp.spawnSync("bash", ["-c", script], {
+    env: { ...process.env, T: target, K: kind, M: config.prefix },
+    encoding: "utf8",
+    timeout: 10_000,
+  });
+  if (result.error && result.error.code === "ENOENT") { bashAvailable = false; return { blocked: true, error_code: "ENOENT" }; }
+  if (result.status === 0) return { blocked: false, error_code: null };
+  return { blocked: true, error_code: bashCode(result.stderr) };
+}
+
+// The harness passes host-side paths. `inner` attempts name the same location as this process sees it
+// (its own home or agent directory); they matter when the boundary maps those somewhere else.
+function resolveTarget(attempt) {
+  if (attempt.path) return attempt.path;
+  const base = { home, agent: agentDir, ext: path.join(agentDir, "npm", "node_modules") }[attempt.inner];
+  const target = path.join(base, attempt.name);
+  return target === attempt.compare ? null : target;
+}
+
+const attempts = [];
+for (const attempt of config.attempts) {
+  const target = resolveTarget(attempt);
+  if (target === null) { attempts.push({ id: attempt.id, skipped: true }); continue; }
+  const viaNode = nodeAttempt(target, attempt.kind);
+  attempts.push({ id: `${attempt.id}.node`, ...viaNode });
+  const viaBash = bashAttempt(target, attempt.kind);
+  attempts.push({ id: `${attempt.id}.bash`, ...viaBash });
+}
+
+// Git metadata: a writer's clone is untrusted; record whether a redirect file can be created there.
+let gitCommondirWritten = null;
+if (config.gitCommondir) {
+  // The exact name matters here; the value names no directory, and the harness removes the file afterwards.
+  try { fs.writeFileSync(config.gitCommondir, `${config.prefix}-commondir\n`, { flag: "wx" }); gitCommondirWritten = true; }
+  catch { gitCommondirWritten = false; }
+}
+
+// Persistence: leave a detached process behind; the harness looks for it after this process ends.
+let markerStarted = false;
+try {
+  const child = cp.spawn("bash", ["-c", 'exec -a "$M" sleep 120'], { detached: true, stdio: "ignore", env: { ...process.env, M: config.marker } });
+  child.on("error", () => {});
+  child.unref();
+  markerStarted = true;
+} catch { markerStarted = false; }
+
+function visible(candidates) {
+  let exists = false;
+  let readable = false;
+  for (const candidate of candidates) {
+    try {
+      fs.statSync(candidate);
+      exists = true;
+      try { fs.accessSync(candidate, fs.constants.R_OK); readable = true; } catch { /* not readable */ }
+    } catch { /* absent */ }
+  }
+  return { exists, readable };
+}
+
+const homes = [...new Set([config.hostHome, home])];
+const xdgConfig = process.env.XDG_CONFIG_HOME;
+const underHomes = (...segments) => homes.map((base) => path.join(base, ...segments));
+const configDirs = [...underHomes(".config"), ...(xdgConfig ? [xdgConfig] : [])];
+
+function gitCredentialConfig() {
+  const result = cp.spawnSync("git", ["config", "--show-origin", "--get-regexp", "^credential\\."], {
+    encoding: "utf8", timeout: 10_000, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+  });
+  if (result.error) return { exists: false, readable: false };
+  const count = String(result.stdout || "").split("\n").filter(Boolean).length;
+  return { exists: count > 0, readable: count > 0 };
+}
+
+const credentials = {
+  ssh_dir: visible(underHomes(".ssh")),
+  ssh_auth_sock: visible(process.env.SSH_AUTH_SOCK ? [process.env.SSH_AUTH_SOCK] : []),
+  gh_hosts_file: visible([...configDirs.map((dir) => path.join(dir, "gh", "hosts.yml")), ...(process.env.GH_CONFIG_DIR ? [path.join(process.env.GH_CONFIG_DIR, "hosts.yml")] : [])]),
+  gh_token_env: { exists: Boolean(process.env.GH_TOKEN || process.env.GITHUB_TOKEN || process.env.GH_ENTERPRISE_TOKEN), readable: Boolean(process.env.GH_TOKEN || process.env.GITHUB_TOKEN || process.env.GH_ENTERPRISE_TOKEN) },
+  git_credentials_file: visible([...underHomes(".git-credentials"), ...configDirs.map((dir) => path.join(dir, "git", "credentials"))]),
+  git_credential_config: gitCredentialConfig(),
+  claude_client_config: visible([...underHomes(".claude.json"), ...underHomes(".claude")]),
+  codex_client_config: visible([...underHomes(".codex")]),
+  // The host configuration directories only; the boundary's own configuration is reported separately below.
+  pi_session_mcp_config: visible(configDirs.map((dir) => path.join(dir, "pi-session-mcp"))),
+};
+// The boundary's own server configuration must be readable; only a digest prefix leaves the probe, so the
+// harness can tell whether it is the host's configuration file.
+function ownConfig() {
+  const file = process.env.PI_SESSION_MCP_CONFIG;
+  if (!file) return { present: false, digest: null };
+  try { return { present: true, digest: require("node:crypto").createHash("sha256").update(fs.readFileSync(file)).digest("hex").slice(0, 12) }; }
+  catch { return { present: false, digest: null }; }
+}
+// The filesystem type of the mount that holds HOME, from /proc/self/mountinfo (longest matching mount point).
+function homeMountType() {
+  try {
+    const target = fs.realpathSync(home);
+    let best = { point: "", type: null };
+    for (const line of fs.readFileSync("/proc/self/mountinfo", "utf8").split("\n")) {
+      const [left, right] = line.split(" - ");
+      if (!left || !right) continue;
+      const point = left.split(" ")[4];
+      if (point && (target === point || target.startsWith(point.endsWith("/") ? point : point + "/")) && point.length > best.point.length) best = { point, type: right.split(" ")[0] };
+    }
+    return best.type;
+  } catch { return null; }
+}
+// Informational: the boundary's own provider authentication, expected to exist for a working session.
+const piAgentAuth = visible([path.join(agentDir, "auth.json")]);
+
+let sshAuthenticated = null;
+let networkTcp = null;
+if (!config.skipRemote) {
+  const ssh = cp.spawnSync("ssh", ["-o", "BatchMode=yes", "-o", "ConnectTimeout=5", "-T", "git@github.com"], { encoding: "utf8", timeout: 20_000 });
+  // Only "authentication succeeded" is kept; GitHub answers with exit status 1 and a fixed greeting.
+  sshAuthenticated = !ssh.error && /successfully authenticated/i.test(`${ssh.stdout || ""}${ssh.stderr || ""}`);
+}
+
+function envNamesOfChild() {
+  const result = cp.spawnSync("bash", ["-c", "env -0"], { encoding: "utf8", timeout: 10_000 });
+  const raw = result.status === 0 ? String(result.stdout || "") : null;
+  const names = raw === null ? Object.keys(process.env) : raw.split("\0").map((entry) => entry.split("=")[0]).filter((name) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(name));
+  return [...new Set(names)];
+}
+const childEnvNames = envNamesOfChild();
+
+function ns(kind) {
+  try { return fs.readlinkSync(`/proc/self/ns/${kind}`); } catch { return null; }
+}
+const namespaces = { user: ns("user"), mnt: ns("mnt"), pid: ns("pid"), net: ns("net") };
+
+function tcpProbe() {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: config.networkHost, port: 443 });
+    const done = (value) => { socket.destroy(); resolve(value); };
+    socket.setTimeout(5000);
+    socket.on("connect", () => done(true));
+    socket.on("timeout", () => done(false));
+    socket.on("error", () => done(false));
+  });
+}
+
+(async () => {
+  if (!config.skipRemote) networkTcp = await tcpProbe();
+  // Give the detached marker a moment to reach its exec before this process (and a container) ends.
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  const result = {
+    attempts,
+    bash_available: bashAvailable,
+    marker_started: markerStarted,
+    git_commondir_written: gitCommondirWritten,
+    credentials,
+    pi_agent_auth: piAgentAuth,
+    own_config: ownConfig(),
+    home_mount_type: homeMountType(),
+    ssh_authenticated: sshAuthenticated,
+    network_tcp_443: networkTcp,
+    child_env_names: childEnvNames,
+    namespaces,
+    uid: typeof process.getuid === "function" ? process.getuid() : null,
+  };
+  process.stdout.write(`ISOLATION_PROBE_RESULT ${JSON.stringify(result)}\n`);
+})();

package/skills/pi-session-implementation/SKILL.md

@@ -10,13 +10,14 @@ You are a worker. A controlling agent gave you one task. Do that task and report
 ## Before you change anything
 
 - Identify the one problem you must solve. If the task bundles several problems, do the first and name the rest in your report. If the task is unclear, say what is unclear in your report instead of guessing.
-- Confirm your starting point: the base commit or branch you were given. Check that the workspace matches it. If it does not, stop and report the mismatch.
+- Confirm your starting point: the base commit or branch you were given. Check that the workspace matches it. If it does not, stop and report `BLOCKED` with the mismatch. Do not fetch, pull or change the base yourself.
 - Confirm the agreed change area (files or directories). Stay inside it. If the task needs a change outside it, report that as an open point; do not make the change.
 - Read the code around the change and follow its style, naming and comment density.
 
 ## While you work
 
 - Make small changes that can be traced to the task. No unrelated cleanups, renames or formatting sweeps.
+- Do not end your turn after only reading code or announcing a plan. Either make the change and report, or end with `NEEDS_CONTEXT` or `BLOCKED` and the reason.
 - Do not add dependencies unless the task says so.
 - Write or update tests for the behavior you change. Run the targeted tests for that area, not the whole suite unless the task asks for it.
 - Never integrate, merge or copy in other workers' changes. Other workers may be changing other parts of the project at the same time. Work only from your starting point.
@@ -26,17 +27,26 @@ You are a worker. A controlling agent gave you one task. Do that task and report
 ## Commit
 
 - If your profile can commit and the task asks for it, commit your change with a clear message that refers to the task or issue. Make one commit per issue.
+- If `git commit` fails because no identity is configured, stop and report `BLOCKED`; never invent or pass an identity unless the controller's prompt supplies one.
 - If you cannot commit, leave the changes in the workspace and say so.
 - Do not push, open pull requests or change branches unless the task says so.
 
 ## Final report
 
-End with a report that has these parts:
+End with a report that has these parts. If the controlling agent asked for a specific report format, use that format and keep the status line.
 
-1. Result: done, partly done or blocked, in one sentence.
+1. Status: the first line is `STATUS:` with exactly one of `DONE` (task done, checks run), `DONE_WITH_CONCERNS` (done, with risks or unverified parts named under open points), `NEEDS_CONTEXT` (you need an answer to continue; state the question) or `BLOCKED` (you cannot continue; name the blocker). Then the result in one sentence.
 2. Commit: the hash and branch, or "not committed" and why.
 3. Changed files: repository-relative paths, one line each on what changed.
 4. Checks run: each command and its result (pass, fail, number of tests). Say which checks you did not run and why.
 5. Open points: blockers, assumptions, work outside your change area, anything the controlling agent must verify.
 
 Report facts you observed. Do not claim a check passed unless you ran it and saw it pass.
+
+Keep the report concise:
+
+- Give the status, the actual changed paths, each check with its exit code, failures, blockers, risks, and relative evidence references (repository-relative paths and commands).
+- Do not paste full diffs, whole files or full logs by default. The controlling agent fetches them when needed.
+- For a failed check, quote only the failing lines.
+- Never drop a failed check, blocker or risk to save space. If required evidence does not fit, say so explicitly.
+- `truncated: true` means the report the controlling agent receives is incomplete. `truncated: false` does not prove the report is complete or correct, and does not prove that no SDK-side output limit applied.

package/skills/pi-session-orchestration/SKILL.md

@@ -10,7 +10,7 @@ You control Pi worker sessions through the pi-session-mcp tools. You choose only
 ## 1. Discover first
 
 - 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.
-- Each profile lists `permissionProfile` (`read-only` or `coding`), `extensions` and `skills`. `skills` names the configured skill aliases. That is configuration intent only. It does not prove that a session loaded the skill or that the model will read it.
+- Each profile lists `permissionProfile` (`read-only` or `coding`), `extensions`, `grantedExtensionTools` 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.
 - 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.
 
 ## 2. Scope each task
@@ -23,22 +23,27 @@ Write down before you start a worker:
 - dependencies on other tasks,
 - workspace alias,
 - the change area (files or directories) the worker may touch,
-- the checks you expect it to run.
+- the checks you expect it to run,
+- the report you expect back (see section 5).
 
 Split work so tasks do not overlap. If two tasks need the same files, run them one after the other.
 
 ## 3. Pick workspace and profile
 
-- Use a `read-only` profile for review, analysis and questions. Use a `coding` profile only when files must change.
+- 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.
+- 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/start-errors.md](references/start-errors.md).
+- 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.
 - 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.
 - 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.
-- Every concurrently writing worker needs its own prepared worktree workspace alias on the base commit you specified. Never let two writers share an alias. Read-only workers may share one.
+- 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.
+- 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.
 - A session's workspace and profile are fixed at start. Never try to switch them; start a new session instead.
 - 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.
+- 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.
 
 ## 4. Keep a ledger
 
-Keep an internal ledger with one row per task: task, workspace alias, profile alias, `sessionId`, `turnId`, start time and time budget, status. Update it after every tool call. Decide the time budget per task when you start it. A cap on concurrent sessions and per-task budgets are your own policy for this run; the server enforces neither. Two concurrent workers is the first tested scope, not a limit of the server; choose a cap you can supervise.
+Keep 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 `assistantText` and `truncated`. 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; the server enforces neither. Two concurrent workers is the first tested scope, not a limit of the server; choose a cap you can supervise.
 
 ## 5. Start in parallel, wait on the first
 
@@ -46,18 +51,36 @@ Keep an internal ledger with one row per task: task, workspace alias, profile al
 - A prompt call returns a running turn at once. Do not block on one task while others sit unstarted.
 - A session accepts one running turn. A second prompt on a running session fails with `session_running`.
 - 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.
+- 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.
+- Tell the worker to stop with `BLOCKED` when its workspace is not at the base, and not to fetch or change the base itself.
 
-## 6. Poll with pauses
+## 6. Wait for results
+
+### Event delivery
+
+`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.
+
+- After `pi_session_prompt` returns a running turn, do not poll it and do not sleep. Start other tasks or end your turn.
+- A system reminder `pi-session-mcp: turn <turnId> of session <sessionId> is <state>.` 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.
+- A reminder `pi-session-mcp: no event for turn <turnId> 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.
+- A wake is only a trigger. The state you act on is always the one `pi_turn_get` returns.
+
+### Polling
 
 - Poll `pi_turn_get` with `sessionId` and `turnId`. There is no wait tool.
-- Pause between polls (several seconds, longer for long tasks). Do not hammer.
-- Cycle over all running tasks in the ledger. Handle whichever finishes first, then continue.
+- 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.
+- Poll only tasks that are still running in the ledger. Cycle over them and handle whichever finishes first, then continue.
 - Stop waiting on a task when its time budget is spent. Then abort it (see section 9).
+- 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.
 
 ## 7. Interpret progress and results
 
 - `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.
+- `completed`, `failed` and `aborted` are terminal and immutable. On the first terminal read, record `state`, `assistantText` and `truncated` 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.
 - `completed` is a technical state: the turn ended and returned text. It does not mean the task succeeded. Read `assistantText` and check `truncated`.
+- 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.
+- Act on the status. `NEEDS_CONTEXT`: answer the question in a follow-up in the same session. `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.
+- 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.
 - Never accept a worker report as proof. A worker saying the tests pass is a claim, not evidence.
 
 ## 8. Take over and verify
@@ -69,6 +92,13 @@ Before you close a task or integrate anything:
 - compare the result with the scope you wrote down,
 - reject or send back work that is outside the change area or unverified.
 
+Review every code task before you integrate it:
+
+- Use a read-only profile of another model family than the author's, on the collected commit. Ask for a first line `VERDICT:` with exactly one of `BLOCKING`, `NON_BLOCKING_ONLY` or `CLEAN`, then findings with severity, file and line, and the concrete failure scenario.
+- A finding is a claim. Check each one against the code before you act on it.
+- 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.
+- 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.
+
 You integrate. Workers never integrate each other's changes. Resolve conflicts between workers yourself.
 
 ## 9. Follow-ups, failures and aborts
@@ -78,11 +108,9 @@ You integrate. Workers never integrate each other's changes. Resolve conflicts b
 - `aborted` means the turn stopped. Look at what the workspace contains before reusing it.
 - `pi_session_abort` returns `abort_failed` if the abort was rejected. The turn may still be running. Poll it.
 - `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.
-- Classify every `pi_session_start` error by its `code` alone. Never decide by the message, provider text or any other free text, and never infer a cause. Each code below is in exactly one class:
-  - Operator needed (do not retry and do not switch to another profile; report the code and stop that task): `unknown_execution_profile`, `unknown_workspace`, `unknown_provider`, `unknown_model`, `model_unavailable`, `thinking_level_unavailable`, `local_authentication_missing`, `execution_selection_mismatch`, `skill_load_failed`, `extension_not_installed`, `extension_version_mismatch`, `extension_tool_conflict`, `external_mcp_no_tools`, `external_mcp_grant_tool_missing`, `external_mcp_activation_mismatch`, `server_stopping`. The last code means the server is shutting down: a new server process is needed, not a retry.
-  - Transient (retry at most once after a pause, then report): `external_mcp_unavailable` (an external MCP server that cannot connect, times out or breaks the protocol), `extension_load_failed` (an invalid package, but also a start timeout), `local_authentication_unavailable` (local authentication could not be resolved within its deadline).
-  - Unknown (report the code; at most one retry in a fresh session): `pi_session_creation_failed`. Any code not listed above is also unknown.
-- If the pi-session-mcp tools are missing entirely, the server did not start. Its stderr names a `startup_failed` diagnostic (`invalid_execution_profile_config` or `invalid_thinking_level`). No MCP server is available; the operator must fix the configuration.
+- 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/start-errors.md](references/start-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.
+- `writer_unavailable` is a capacity/state signal, not a reason to switch profiles. Wait for sessions/cleanup 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.
+- If the pi-session-mcp tools are missing entirely, the server did not start. Its stderr names a `startup_failed` diagnostic (`invalid_execution_profile_config`, `invalid_thinking_level`, `invalid_execution_modes`, `invalid_event_delivery` or `event_spool_unavailable`). No MCP server is available; the operator must fix the configuration.
 
 ## 10. Close every session
 
@@ -90,6 +118,15 @@ You integrate. Workers never integrate each other's changes. Resolve conflicts b
 - Close on every error path, too. Before you end the run, check the ledger: no session may remain open.
 - A session that is idle is still open. Closing releases its resources.
 
+## 11. Finish a task on a writer
+
+After taking over the result and closing its coding session, before the next task:
+
+1. Run `pi-session-mcp-setup --writer <name> --collect --apply` from the operator environment. Review the collected refs in the operator's checkout: `refs/remotes/writer-<name>/<branch>`, with uncommitted work as `<branch>-wip`. They are untrusted until reviewed. Integrate only verified work yourself.
+2. Run `pi-session-mcp-setup --writer <name> --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.
+3. 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/start-errors.md](references/start-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 <name> --reset --base <branch> --apply`, then call `pi_session_start` on `pi-session-mcp` with the coding profile and `base: "<branch>"`. Read `writer` from that result for collection. Default starts cannot use a writer moved to the fix branch.
+4. 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.
+
 ## Limits to remember
 
 - Each client process has its own server process and its own in-memory sessions. Separate Claude Code and Codex processes do not share sessions.

package/skills/pi-session-orchestration/references/start-errors.md

@@ -0,0 +1,12 @@
+# Start errors of `pi_session_start`
+
+Load this file only after a `pi_session_start` call has failed. Classify the error by its `code` alone. Never decide by the message, provider text or any other free text, and never infer a cause. Each code below is in exactly one class.
+
+- Operator needed (do not retry and do not switch to another profile; report the code and stop that task): `unknown_execution_profile`, `unknown_workspace`, `workspace_mode_forbids_coding`, `unknown_provider`, `unknown_model`, `model_unavailable`, `thinking_level_unavailable`, `local_authentication_missing`, `execution_selection_mismatch`, `skill_load_failed`, `extension_not_installed`, `extension_version_mismatch`, `extension_tool_conflict`, `extension_tool_missing`, `external_mcp_no_tools`, `external_mcp_grant_tool_missing`, `external_mcp_activation_mismatch`, `writer_not_ready`, `container_runtime_unavailable`, `server_stopping`. Writer readiness needs repository setup and acceptance; runtime unavailability needs usable rootless Podman. The last code means the server is shutting down: a new server process is needed, not a retry.
+- Controller action (do not blindly retry or switch profiles; collect and reset the writer for uncollected work, or wait for or close the open coding session for a busy writer; resolve pool state, lost sessions or inapplicable base before a fresh start): `writer_uncollected`, `writer_busy`, `writer_unavailable`, `writer_session_lost`, `base_not_applicable`.
+- Transient (retry at most once after a pause, then report): `external_mcp_unavailable` (an external MCP server that cannot connect, times out or breaks the protocol), `extension_load_failed` (an invalid package, but also a start timeout), `local_authentication_unavailable` (local authentication could not be resolved within its deadline).
+- Unknown (report the code; at most one retry in a fresh session): `pi_session_creation_failed`. Any code not listed above is also unknown.
+
+Pool unavailability is a capacity/state signal: reason `none_ready` means no ready writer with current acceptance, `none_at_base` means none of the ready writers matches the requested/default base, and `none_admitted` means candidates refused, with content-free counts `busy`, `notAtBaseline`, `settingsChanged`. Wait for capacity or collect/finish writers; readiness or settings drift may need operator reconciliation, never a profile switch. Setup on a held writer fails after a short lease wait.
+
+Session loss also applies to further prompts after idle or running transport loss: get and close still work; close and inspect/collect work before a fresh session, not a blind repeat of a prompt. An inapplicable base means no session was created: omit `base` unless using a coding profile on a container workspace. For fix rounds create a local branch at the collected ref, reset with `--writer <name> --reset --base <branch> --apply`, then start with `base: "<branch>"` and collect the `writer` returned. No reconnect is needed.

package/skills/pi-session-review/SKILL.md

@@ -51,8 +51,16 @@ Order findings by severity. If you find nothing, say what you checked and what y
 
 ## Final report
 
-1. Target reviewed.
-2. Verdict: blocking findings exist, only non-blocking findings, or no findings. Base it on your evidence.
-3. Verified findings.
-4. Risks and hypotheses.
-5. Checks run and checks not run.
+1. Status: the first line is `STATUS:` with `DONE` when you reviewed the whole target, `DONE_WITH_CONCERNS` when you reviewed only part of it (name what you left out and why), `NEEDS_CONTEXT` when the target is missing or ambiguous (state the question), or `BLOCKED` when you could not review it (name the blocker).
+2. Target reviewed.
+3. Verdict: exactly one of `BLOCKING_FINDINGS`, `NON_BLOCKING_ONLY` or `NO_FINDINGS`. Base it on your evidence.
+4. Verified findings.
+5. Risks and hypotheses.
+6. Checks run and checks not run.
+
+Keep the report concise:
+
+- Cite evidence by relative reference (repository-relative paths, line numbers, commands). Do not paste full diffs, whole files or full logs by default. The controlling agent fetches them when needed.
+- For a failed check, quote only the failing lines, and give each check with its exit code.
+- Never drop a failed check, blocker or risk to save space. If required evidence does not fit, say so explicitly.
+- `truncated: true` means the report the controlling agent receives is incomplete. `truncated: false` does not prove the report is complete or correct, and does not prove that no SDK-side output limit applied.