backpass 0.1.7 → 0.1.8

package/src/harness-invoke.js

@@ -0,0 +1,277 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { UserError } from "./logger.js";
+
+/**
+ * Invocation-scoped model and effort overlays (`src/acpx.js` is the caller).
+ *
+ * A one-off model or reasoning level must ride on this spawn only. Isolated Pi
+ * reproduction (throwaway `PI_CODING_AGENT_DIR`): RPC `set_model` /
+ * `set_thinking_level` rewrite `settings.json`; `pi --model` / `--thinking` at
+ * process start select the values for that process and leave defaults untouched.
+ * acpx `--model` after `session/new` is ACP `setSessionModel`, which is that
+ * persist path for Pi, so Pi never gets `--model` on acpx or a later `set`.
+ *
+ * How each invoked harness applies a requested overlay for this spawn:
+ *   pi        process argv via `PI_ACP_PI_COMMAND` wrapper: `--model`, `--thinking`
+ *   grok      process argv via acpx `--agent` wrapper: `-m`, `--reasoning-effort`
+ *   claude    acpx `--model` at `sessions new` (session/new `_meta`); ACP `set effort`
+ *   codex     acpx `--model` at `sessions new`; ACP `set reasoning_effort`
+ *   opencode  acpx `--model` at `sessions new`; no effort overlay (report, never pretend)
+ *
+ * No overlay requested means no wrapper, no `--model`, no `set` - same spawn as before.
+ * A requested overlay with no proven invocation-scoped mechanism throws rather than
+ * writing persistent defaults or silently ignoring the request. OpenCode effort is the
+ * sole explicit exception: it is skipped with a report note.
+ */
+
+/** ACP session-config ids used only when that `set` is session-local, not a persist path. */
+const SESSION_LOCAL_EFFORT_KEYS = { codex: "reasoning_effort", claude: "effort" };
+
+/**
+ * @typedef {{
+ *   env: Record<string, string> | undefined,
+ *   acpxModel: string | null,
+ *   setEffortKey: string | null,
+ *   acpxAgentCommand: string | null,
+ *   requiredBuiltinAgent: string | null,
+ *   notes: string[],
+ *   dispose: () => void,
+ * }} HarnessInvocation
+ */
+
+/**
+ * @param {{ agent: string, model?: string | null, effort?: string | null }} options
+ * @returns {HarnessInvocation}
+ */
+export function prepareHarnessInvocation({ agent, model = null, effort = null }) {
+  const notes = [];
+  const cleanups = [];
+  const dispose = () => {
+    for (const fn of cleanups.splice(0)) {
+      try {
+        fn();
+      } catch {
+        // Temp wrappers are best-effort to remove.
+      }
+    }
+  };
+
+  const requestedModel = typeof model === "string" && model.trim() ? model.trim() : null;
+  const requestedEffort = typeof effort === "string" && effort.trim() ? effort.trim() : null;
+
+  if (!requestedModel && !requestedEffort) {
+    return {
+      env: undefined,
+      acpxModel: null,
+      setEffortKey: null,
+      acpxAgentCommand: null,
+      requiredBuiltinAgent: null,
+      notes,
+      dispose,
+    };
+  }
+
+  try {
+    if (agent === "pi") return piInvocation({ requestedModel, requestedEffort, notes, cleanups, dispose });
+    if (agent === "grok") return grokInvocation({ requestedModel, requestedEffort, notes, cleanups, dispose });
+    if (agent === "claude" || agent === "codex") {
+      return {
+        env: undefined,
+        acpxModel: requestedModel,
+        setEffortKey: requestedEffort ? SESSION_LOCAL_EFFORT_KEYS[agent] : null,
+        acpxAgentCommand: null,
+        requiredBuiltinAgent: agent,
+        notes,
+        dispose,
+      };
+    }
+    if (agent === "opencode") {
+      if (requestedEffort) {
+        notes.push(`${agent} does not advertise a reasoning-effort option; ran without effort=${requestedEffort}`);
+      }
+      return {
+        env: undefined,
+        acpxModel: requestedModel,
+        setEffortKey: null,
+        acpxAgentCommand: null,
+        requiredBuiltinAgent: agent,
+        notes,
+        dispose,
+      };
+    }
+    throw new UserError(
+      `${agent} has no proven invocation-scoped way to apply ${describeOverride(requestedModel, requestedEffort)} without writing persistent harness defaults`,
+      "pin pi, claude, codex, grok, or opencode, or omit the model and effort override",
+    );
+  } catch (err) {
+    dispose();
+    throw err;
+  }
+}
+
+function describeOverride(model, effort) {
+  const bits = [];
+  if (model) bits.push(`model=${model}`);
+  if (effort) bits.push(`effort=${effort}`);
+  return bits.join(" and ");
+}
+
+function piInvocation({ requestedModel, requestedEffort, notes, cleanups, dispose }) {
+  if (process.env.PI_ACP_PI_COMMAND) {
+    throw new UserError(
+      "cannot safely apply Pi model or effort overrides when PI_ACP_PI_COMMAND replaces the proven Pi command",
+      "unset PI_ACP_PI_COMMAND or omit the model and effort override",
+    );
+  }
+  const extra = [];
+  if (requestedModel) extra.push("--model", requestedModel);
+  if (requestedEffort) extra.push("--thinking", requestedEffort);
+  const real = resolveOnPath("pi");
+  if (!real || (process.platform === "win32" && /\.(?:cmd|bat)$/i.test(real))) {
+    throw new UserError(
+      `cannot apply ${describeOverride(requestedModel, requestedEffort)} as safe Pi process arguments on this platform`,
+      "install Pi as a directly executable binary, or omit the model and effort override",
+    );
+  }
+  const { wrapperPath, dir } = writeArgvWrapper({ realCommand: real, extraArgs: extra, binName: "pi" });
+  cleanups.push(() => fs.rmSync(dir, { recursive: true, force: true }));
+  return {
+    env: { PI_ACP_PI_COMMAND: wrapperPath },
+    acpxModel: null,
+    setEffortKey: null,
+    acpxAgentCommand: null,
+    requiredBuiltinAgent: "pi",
+    notes,
+    dispose,
+  };
+}
+
+function grokInvocation({ requestedModel, requestedEffort, notes, cleanups, dispose }) {
+  if (process.platform === "win32") {
+    throw new UserError(
+      `cannot apply ${describeOverride(requestedModel, requestedEffort)} through acpx --agent on Windows`,
+      "pin pi, claude, codex, or opencode, or omit the model and effort override",
+    );
+  }
+  const extra = [];
+  if (requestedModel) extra.push("-m", requestedModel);
+  if (requestedEffort) extra.push("--reasoning-effort", requestedEffort);
+  extra.push("agent", "stdio");
+  const real = resolveOnPath("grok");
+  if (!real) {
+    throw new UserError(
+      `cannot apply ${describeOverride(requestedModel, requestedEffort)} as grok process flags because grok was not found on PATH`,
+      "install the grok CLI, or pin a different agent / omit the model and effort override",
+    );
+  }
+  const { nodeCommand, dir } = writeArgvWrapper({ realCommand: real, extraArgs: extra, binName: "grok" });
+  cleanups.push(() => fs.rmSync(dir, { recursive: true, force: true }));
+  return {
+    env: undefined,
+    acpxModel: null,
+    setEffortKey: null,
+    acpxAgentCommand: nodeCommand,
+    requiredBuiltinAgent: null,
+    notes,
+    dispose,
+  };
+}
+
+/**
+ * Write a node wrapper that prepends `extraArgs` and execs `realCommand` with
+ * inherited stdio. Args are JSON-encoded so values with spaces or `$()` stay literal.
+ *
+ * @param {{ realCommand: string, extraArgs: string[], binName: string }} options
+ */
+function writeArgvWrapper({ realCommand, extraArgs, binName }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "backpass-harness-wrap-"));
+  const scriptPath = path.join(dir, `${binName}.cjs`);
+  const payload = JSON.stringify({ real: realCommand, extra: extraArgs });
+  fs.writeFileSync(
+    scriptPath,
+    `#!/usr/bin/env node
+const { spawn } = require("node:child_process");
+const { real, extra } = ${payload};
+const signals = ["SIGTERM", "SIGINT", "SIGHUP"];
+let child = null;
+let pendingSignal = null;
+let escalationTimer = null;
+const forwardSignal = (signal) => {
+  if (!child) {
+    pendingSignal ??= signal;
+    return;
+  }
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  try { child.kill(signal); } catch {}
+  if (!escalationTimer) {
+    escalationTimer = setTimeout(() => {
+      if (child.exitCode === null && child.signalCode === null) {
+        try { child.kill("SIGKILL"); } catch {}
+      }
+    }, 4000);
+    escalationTimer.unref();
+  }
+};
+const signalHandlers = new Map(signals.map((signal) => [signal, () => forwardSignal(signal)]));
+for (const [signal, handler] of signalHandlers) process.on(signal, handler);
+child = spawn(real, extra.concat(process.argv.slice(2)), { stdio: "inherit" });
+if (pendingSignal) forwardSignal(pendingSignal);
+child.on("error", (err) => {
+  console.error(err.message);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (escalationTimer) clearTimeout(escalationTimer);
+  for (const [name, handler] of signalHandlers) process.removeListener(name, handler);
+  if (signal) {
+    try {
+      process.kill(process.pid, signal);
+      return;
+    } catch {}
+  }
+  process.exit(code ?? 1);
+});
+`,
+  );
+  let wrapperPath = scriptPath;
+  if (process.platform === "win32") {
+    wrapperPath = path.join(dir, `${binName}.cmd`);
+    fs.writeFileSync(wrapperPath, `@echo off\r\n${cmdQuote(process.execPath)} ${cmdQuote(scriptPath)} %*\r\n`);
+  } else {
+    fs.chmodSync(scriptPath, 0o755);
+  }
+  return { wrapperPath, nodeCommand: renderCommandArgv([process.execPath, scriptPath]), dir };
+}
+
+function renderCommandArgv(argv) {
+  return argv.map((arg) => `'${arg.replaceAll("'", "'\\''")}'`).join(" ");
+}
+
+function cmdQuote(value) {
+  return `"${value.replaceAll("%", "%%").replaceAll('"', '""')}"`;
+}
+
+function resolveOnPath(bin) {
+  if (path.isAbsolute(bin) && isExecutable(bin)) return bin;
+  const extensions = process.platform === "win32" ? (process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    for (const extension of extensions) {
+      const candidate = path.join(dir, process.platform === "win32" ? `${bin}${extension.toLowerCase()}` : bin);
+      if (isExecutable(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+function isExecutable(file) {
+  try {
+    const st = fs.statSync(file);
+    return st.isFile() && (process.platform === "win32" || Boolean(st.mode & 0o111));
+  } catch {
+    return false;
+  }
+}

package/src/prompts/annotate-preface.md

@@ -0,0 +1,19 @@
+You are joining a synthesis run already in progress, so read this before the changes.
+
+An earlier session edited a staging copy of `{{MEMORY_PATH}}` for the {{REPO_NAME}} repository.
+**The edits below are already made.** Your fresh session did not make them and may not have seen
+prior annotation attempts. Your job is only to describe them - do not redo them, do not start
+over, and do not revert anything you would have written differently. If a change genuinely
+cannot ship, revert that one change in the staging copy first and say so.
+
+- Repository: `{{REPO_ROOT}}` (read it by absolute path when a change needs grounding)
+- Memory file under review: `{{MEMORY_PATH}}` - {{CURRENT_TOKENS}} tokens, {{BUDGET_STATE}}
+- Staging copy you are working in: `{{WORKSPACE_ROOT}}`
+
+Every edit you report needs a verbatim quote from the evidence below, so read it first.
+
+## Evidence from {{TRANSCRIPT_COUNT}} analyzed session(s)
+
+{{EVIDENCE}}
+
+---

package/src/prompts/annotate.md

@@ -1,5 +1,5 @@
-backpass measured the changes you made in the staging copy. Every change below is
-identified by an id; annotate each one so a human can review it with its evidence.
+{{PREFACE}}backpass measured the changes in the staging copy of {{MEMORY_PATH}}. Every change below
+is identified by an id; annotate each one so a human can review it with its evidence.
 
 ## Measured changes
 
@@ -39,10 +39,15 @@ Hard rules - a violation fails the whole proposal:
 4. **New instructions need evidence from at least {{MIN_GAP_EVIDENCE}} distinct
    sessions.** `transcripts` is how many distinct sessions back the edit; an edit that
    only adds text is a new instruction whatever its `kind` says.
-5. `kind: "extract"` is exactly an edit whose changes include one created `SKILL.md`
-   and at least one change to `{{MEMORY_PATH}}`. Any other edit must not include a
-   created file, and an edit changes one file only.
+5. `kind: "extract"` is an edit whose changes are one or more created `SKILL.md` files
+   plus the change(s) to {{MEMORY_PATH}} that pay for them. One skill per extract is the
+   normal shape. Several skills belong in ONE extract exactly when their removals landed
+   in a **single** measured change: adjacent removals are merged into one change, and a
+   merged change cannot be accepted in halves. If each skill has its own measured change,
+   give each its own extract. Any other kind must not include a created file, and an edit
+   changes one file only.
 6. **Budget:** {{BUDGET_RULE}}
 
 If you still need to change the files, do that first and then answer; backpass
-re-measures after this reply and shows you the new ids if anything moved.
+re-measures after this reply and shows you the new ids if anything moved. Re-measuring
+does not use up an annotation attempt.

package/src/proposal.js

@@ -1,4 +1,5 @@
 import { renderHunkLines } from "./diff.js";
+import { editSkills } from "./skills.js";
 import { budgetGateKind, budgetStatus, estimateTokens } from "./tokens.js";
 
 /**
@@ -14,7 +15,7 @@ import { budgetGateKind, budgetStatus, estimateTokens } from "./tokens.js";
  *   add      only inserts text                  (gated like a new instruction)
  *   remove   only deletes text
  *   rewrite  replaces text
- *   extract  memory-file change(s) + one created SKILL.md
+ *   extract  memory-file change(s) + the created SKILL.md file(s) they pay for
  *
  * Each hunk carries a `find`/`replace` pair copied out of the original file by
  * construction; `find` occurs exactly once there. That is what the writer applies later,
@@ -44,11 +45,30 @@ export function effectiveMaxEdits(memoryFile, config) {
   return Math.min(SHRINK_MAX_EDITS, Math.max(DEFAULT_MAX_EDITS, Math.ceil(overage / SHRINK_EDIT_TOKENS)));
 }
 
+/**
+ * A synthesis run that ended without a valid proposal, carrying *why* it ended.
+ *
+ * `reason` is the terminal condition - "gates", "empty", "unparseable", "editing" - and
+ * `saved` is the last parseable-but-gated proposal written to disk, if any, with the
+ * annotation attempt that produced it. They are separate because they can disagree: a run
+ * whose last turn was empty still leaves an older rejected proposal on disk, and reporting
+ * that proposal's violations as the empty turn's result is how a run gets diagnosed wrong.
+ */
 export class ProposalViolation extends Error {
-  constructor(message, violations) {
+  /**
+   * @param {string} message
+   * @param {string[]} violations
+   * @param {{ reason?: string, attempts?: number,
+   *   saved?: { attempt: number, violations: string[] } | null, proposalPath?: string | null }} [detail]
+   */
+  constructor(message, violations, detail = {}) {
     super(message);
     this.name = "ProposalViolation";
     this.violations = violations;
+    this.reason = detail.reason || "gates";
+    this.attempts = detail.attempts ?? 0;
+    this.saved = detail.saved || null;
+    this.proposalPath = detail.proposalPath || null;
   }
 }
 
@@ -265,18 +285,29 @@ export function buildProposal(rawResult, context) {
       continue;
     }
     if (edit.kind === "extract") {
-      if (created.length !== 1 || !hunks.length || files[0] !== memoryFile.path) {
+      if (!created.length || !hunks.length || files[0] !== memoryFile.path) {
         violations.push(
-          `edit ${edit.id}: kind "extract" must group exactly one created SKILL.md with change(s) to ${memoryFile.path}`,
+          `edit ${edit.id}: kind "extract" must group created SKILL.md file(s) with change(s) to ${memoryFile.path}`,
         );
         continue;
       }
-      if (!created[0].skill) {
+      // Several skills may share one extract only when their removals were merged into a
+      // single measured change - a merged change cannot be accepted in halves, so that
+      // grouping is the measurement's, not the model's. Skills whose removals were measured
+      // separately stay separately decidable.
+      if (created.length > 1 && hunks.length > 1) {
         violations.push(
-          `edit ${edit.id}: ${created[0].file} needs YAML frontmatter with \`name:\` and \`description:\``,
+          `edit ${edit.id}: groups ${created.length} created skills against ${hunks.length} separate changes to ` +
+            `${memoryFile.path} (${hunks.map((h) => h.id).join(", ")}); give each skill its own extract, or group ` +
+            `several skills only when they share one measured change`,
         );
         continue;
       }
+      const unusable = created.find((c) => !c.skill);
+      if (unusable) {
+        violations.push(`edit ${edit.id}: ${unusable.file} needs YAML frontmatter with \`name:\` and \`description:\``);
+        continue;
+      }
     } else if (created.length) {
       violations.push(`edit ${edit.id}: only kind "extract" may include a created file (${created[0].id})`);
       continue;
@@ -302,7 +333,7 @@ export function buildProposal(rawResult, context) {
       instructions: edit.instructions,
       evidence: edit.evidence,
       transcripts: edit.transcripts,
-      skill: created[0]?.skill || null,
+      skills: created.map((c) => c.skill),
       hunks: hunks.map((h) => ({
         id: h.id,
         find: h.find,
@@ -394,7 +425,7 @@ export function buildProposal(rawResult, context) {
       positive: summary?.totals?.positive ?? 0,
       negative: summary?.totals?.negative ?? 0,
       gapClusters: summary?.totals?.gapClusters ?? 0,
-      skillExtractions: accepted.filter((e) => e.kind === "extract").length,
+      skillExtractions: accepted.reduce((n, e) => n + editSkills(e).length, 0),
     },
     edits: accepted,
     verdicts: Array.isArray(rawResult?.verdicts) ? rawResult.verdicts : [],

package/src/skills.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 
 import { estimateTokens } from "./tokens.js";
 
@@ -103,20 +104,36 @@ export function renderSkillFile(skill) {
   return `---\n${frontmatter}\n---\n\n${skill.body.trim()}\n`;
 }
 
+/**
+ * The skills one extract creates.
+ *
+ * Usually one. Several arrive together when the measurement merged their removals into a
+ * single change (`anchoredHunks`), which makes them one accept/reject decision - accepting
+ * half a merged change is not a thing a file can do. Proposals written before that was
+ * possible carry a single `skill`, so both shapes read the same way here.
+ *
+ * @returns {object[]}
+ */
+export function editSkills(edit) {
+  if (Array.isArray(edit?.skills)) return edit.skills.filter(Boolean);
+  return edit?.skill ? [edit.skill] : [];
+}
+
 /**
  * The budget arithmetic that makes extraction worth it, reported per edit:
  * "-1,900 tok always-loaded, +140 tok description".
  */
 export function extractionBudgetEffect(edit) {
-  if (edit.kind !== "extract" || !edit.skill) return null;
+  const skills = editSkills(edit);
+  if (edit.kind !== "extract" || !skills.length) return null;
   const pairs = Array.isArray(edit.hunks) ? edit.hunks : [edit];
   const removedFromMemory = pairs.reduce((sum, p) => sum + estimateTokens(p.find) - estimateTokens(p.replace), 0);
-  const descriptionCost = estimateTokens(edit.skill.description);
+  const descriptionCost = skills.reduce((sum, skill) => sum + estimateTokens(skill.description), 0);
   return {
     alwaysLoadedDelta: -removedFromMemory,
     descriptionCost,
     net: descriptionCost - removedFromMemory,
-    skillBodyTokens: estimateTokens(edit.skill.body),
+    skillBodyTokens: skills.reduce((sum, skill) => sum + estimateTokens(skill.body), 0),
   };
 }
 
@@ -169,6 +186,110 @@ function inspectClaudeSkillsLink(repoRoot) {
   return { state: "other" };
 }
 
+function pathIdentity(stat) {
+  return { dev: stat.dev, ino: stat.ino };
+}
+
+function restoreQuarantinedPath(quarantine, destination) {
+  const stat = fs.lstatSync(quarantine);
+  if (stat.isDirectory()) {
+    // Restore the directory object itself. Recursively copying it can fail for valid
+    // entries such as Unix sockets and would turn restoration into a lossy clone. On
+    // POSIX, an empty directory created with mkdir is an atomic no-clobber reservation;
+    // rename may replace that reservation, but cannot replace it after another process
+    // has populated it.
+    if (process.platform === "win32") {
+      fs.renameSync(quarantine, destination);
+      return;
+    }
+
+    fs.mkdirSync(destination, { mode: stat.mode & 0o7777 });
+    try {
+      fs.renameSync(quarantine, destination);
+    } catch (err) {
+      try {
+        fs.rmdirSync(destination);
+      } catch {
+        // Another process populated the reservation. Preserve both directory trees.
+      }
+      throw err;
+    }
+    return;
+  }
+  if (stat.isSymbolicLink()) {
+    fs.symlinkSync(fs.readlinkSync(quarantine), destination);
+    fs.unlinkSync(quarantine);
+    return;
+  }
+  fs.linkSync(quarantine, destination);
+  fs.unlinkSync(quarantine);
+}
+
+export function removeOwnedSkillPaths(paths) {
+  const removed = [];
+  const conflicts = [];
+  for (const item of [...paths].reverse()) {
+    let stat;
+    try {
+      stat = fs.lstatSync(item.absolute);
+    } catch {
+      continue;
+    }
+    const observed = pathIdentity(stat);
+    if (observed.dev !== item.identity.dev || observed.ino !== item.identity.ino) {
+      conflicts.push(item);
+      continue;
+    }
+    if (item.text !== undefined) {
+      let text;
+      try {
+        text = fs.readFileSync(item.absolute, "utf8");
+      } catch {
+        conflicts.push(item);
+        continue;
+      }
+      if (text !== item.text) {
+        conflicts.push(item);
+        continue;
+      }
+    }
+
+    // Move the pathname out of the way atomically, then validate the object that was
+    // actually moved. A second pathname check followed by unlink would let a concurrent
+    // replacement slip between those operations and be deleted as if it were ours.
+    const quarantine = path.join(
+      path.dirname(item.absolute),
+      `.${path.basename(item.absolute)}.backpass-rollback-${randomUUID()}`,
+    );
+    let quarantined = false;
+    try {
+      fs.renameSync(item.absolute, quarantine);
+      quarantined = true;
+      const moved = pathIdentity(fs.lstatSync(quarantine));
+      const identityMatches = moved.dev === item.identity.dev && moved.ino === item.identity.ino;
+      const textMatches = item.text === undefined || fs.readFileSync(quarantine, "utf8") === item.text;
+      if (identityMatches && textMatches) {
+        fs.unlinkSync(quarantine);
+        removed.push(item);
+        continue;
+      }
+
+      restoreQuarantinedPath(quarantine, item.absolute);
+      conflicts.push(item);
+    } catch {
+      if (quarantined) {
+        try {
+          restoreQuarantinedPath(quarantine, item.absolute);
+        } catch {
+          fs.existsSync(quarantine);
+        }
+      }
+      conflicts.push(item);
+    }
+  }
+  return { removed, conflicts };
+}
+
 /**
  * Create the canonical skills dir and the `.claude/skills -> ../.agents/skills` symlink
  * so both harness families load the same files with no duplication. An existing
@@ -197,11 +318,39 @@ export function ensureSkillsLayout(repoRoot) {
 }
 
 /** Write an accepted skill extraction to disk, setting up the load layout on first use. */
-export function writeSkill(repoRoot, skill) {
+export function writeSkill(repoRoot, skill, { exclusive = false, ensureLayout = true } = {}) {
   const inCanonical = skill.path === CANONICAL_SKILLS_DIR || skill.path.startsWith(`${CANONICAL_SKILLS_DIR}/`);
-  const layout = inCanonical ? ensureSkillsLayout(repoRoot) : { created: [], warnings: [] };
+  const layout = inCanonical && ensureLayout ? ensureSkillsLayout(repoRoot) : { created: [], warnings: [] };
+  const canonicalWasMissing = inCanonical && !fs.existsSync(path.join(repoRoot, CANONICAL_SKILLS_DIR));
   const target = path.join(repoRoot, skill.path);
   fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.writeFileSync(target, renderSkillFile(skill));
-  return { target, ...layout };
+  if (!ensureLayout && canonicalWasMissing) layout.created.push(CANONICAL_SKILLS_DIR);
+  const text = renderSkillFile(skill);
+  if (!exclusive) {
+    fs.writeFileSync(target, text);
+    return { target, ...layout };
+  }
+
+  let fd;
+  /** @type {{ absolute: string, identity: { dev: number, ino: number }, relative: string, text?: string }[] | undefined} */
+  let ownership;
+  try {
+    fd = fs.openSync(target, "wx");
+    ownership = [{ absolute: target, identity: pathIdentity(fs.fstatSync(fd)), relative: skill.path }];
+    fs.writeFileSync(fd, text);
+    fs.closeSync(fd);
+    fd = undefined;
+    ownership[0].text = text;
+  } catch (err) {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // Preserve the original write error.
+      }
+    }
+    removeOwnedSkillPaths(ownership ?? []);
+    throw err;
+  }
+  return { target, ...layout, ownership };
 }

package/src/state.js

@@ -18,7 +18,7 @@ export const STATE_EXCLUDE_LINE = `${STATE_DIRNAME}/`;
  *   scan-cache.json        path+mtime+size -> association verdict (design section 2.2)
  *   evidence/<id>.json     per-transcript tier-1 analysis output (design section 3)
  *   evidence-summary.json  folded evidence (stage 2)
- *   proposal.json          latest tier-2 synthesis (stage 3)
+ *   proposal.json          latest parseable tier-2 synthesis; absent if none was produced (stage 3)
  *   rejections.json        edits the human rejected, and the evidence weight behind them
  *   gap-ledger.json        gap observations by gap and session, accumulated across runs (src/gap-ledger.js)
  *   agent-probe-cache.json TTL'd availability/auth verdicts per agent|model (src/agents.js)
@@ -113,6 +113,10 @@ export class State {
     this.writeJsonFile(this.proposalPath, proposal);
   }
 
+  clearProposal() {
+    fs.rmSync(this.proposalPath, { force: true });
+  }
+
   readRejections() {
     const value = this.readJsonFile(this.rejectionsPath, null);
     return value && value.version === 1 ? value : { version: 1, entries: {} };