canon-ai 3.11.0 → 3.12.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 ## [Unreleased]
 
+## [3.12.0] — 2026-10-21
+
+### Added
+
+- **Broken references in a task's handoff or QA summary are fixed by the agent that wrote them, before the commit.** After implement, and again after QA, `canon run` checks the task's own artifacts with the docs-refs checker. If it finds a broken reference, it resumes the same agent session to fix it, up to two attempts. A fix session may change only the task's own artifacts; if it touches anything else, the run stops and names the files. If a reference is still broken after two attempts, canon warns and continues as before. The implement and QA prompts also now ask agents to cite repository files by full path and deleted files as markdown links.
+- **`--full-send` pushes its own scaffold commits to the base branch before opening the draft PR.** It pushes only commits that have the exact scaffold subject and change only task artifacts and pipeline telemetry, and it pushes the checked commit rather than the moving branch. If any other commit is unpushed on the base branch, nothing is pushed and the run stops at the divergence check as before. A rejected push (for example, a protected branch) stops with a hint to push or merge manually. The "Scaffold committed" hint now prints only when such commits exist.
+
+### Changed
+
+- **`--pr` and `--push` block only on real merge conflicts with the base.** A base branch that moved on files the task never touched, such as another task's artifacts, no longer stops the run; canon prints one line saying those files merge cleanly. A conflict with `origin/<base>`, including in a file the spec declared, still aborts before the push and names the conflicted files. The task's own out-of-scope changes still abort as before. `--force` bypasses a conflict with a warning. On Git older than 2.38, canon warns that conflicts weren't checked and proceeds.
+
+### Fixed
+
+- **`canon watch` reports a full-send run that died after QA as a death, not a clean stop.** A run that crashed while opening its draft PR now shows `reason=death` and exits 4, with the reason on stderr, whether watch was attached during the run or started after it. A tail that is still running keeps watch blocking.
+- **`canon task reset-spec-review` re-arms the spec gate.** The gate disarms itself when it halts, so a reset after that halt used to let the next run go straight through to human review. The reset now re-arms it and says so, unless the task is full-send.
+- **`--ship` no longer warns that the branch delete failed.** It merges with `gh pr merge --squash`, deletes the remote branch itself, and deletes the local branch after the worktree is removed; the old order made `gh` try to delete a branch the worktree still held.
+
 ## [3.11.0] — 2026-10-20
 
 ### Changed

package/README.md

@@ -257,7 +257,7 @@ Pipeline sessions are headless, so nobody is at the keyboard to answer a permiss
 - **Worktrees separate branch state by convention, not by enforcement.** Each task, or each bundle when you pass several task ids together, gets its own worktree and branch, and the pipeline's dirty-tree gates inspect the active worktree at phase boundaries. But Claude sessions are also given the main checkout via `--add-dir` and run with permissions skipped, so nothing stops a session from writing there, and an unrelated file dropped into the main checkout is not something those gates look for; tasks with `worktree: false` run in the main checkout outright. Validation commands run with your normal privileges.
 - **Budget caps bound cost, not access.** Each headless Claude phase runs with `--max-budget-usd`; hitting the cap stops the session. It does not narrow what the session may do beforehand, and interactive sessions (`--interactive`) run uncapped.
 - **Your code goes to the model providers.** Each agent phase sends prompts and repository context to the provider running it, Anthropic for Claude phases and OpenAI for Codex phases, with `code_review` using both, all through the Claude Code and Codex CLIs under whatever data terms your accounts have. Treat a `canon run` like any other agent session in that respect.
-- **Git side effects need a flag.** The pipeline never pushes, opens PRs, merges, or publishes on its own. `--pr` pushes the task branch and opens a draft PR, stopping at `human_review`. `--ship` squash-merges that PR; it checks the task's phase, not whether anyone approved, so PR approval is your prerequisite (or your branch protection's), not something canon enforces. `--full-send` skips the human spec gate and opens the draft PR on clean QA, still stopping before merge; on a `delicate` task it refuses without `--force`.
+- **Git side effects need a flag.** The pipeline never pushes, opens PRs, merges, or publishes on its own. `--pr` pushes the task branch and opens a draft PR, stopping at `human_review`. `--ship` squash-merges that PR; it checks the task's phase, not whether anyone approved, so PR approval is your prerequisite (or your branch protection's), not something canon enforces. `--full-send` skips the human spec gate and opens the draft PR on clean QA, still stopping before merge; its tail also pushes unpushed base commits that carry only task artifacts and pipeline telemetry, and leaves other unpushed commits to the divergence gate unless `--allow-divergent-base` is set. On a `delicate` task it refuses without `--force`.
 
 Run canon on repositories where you would be comfortable running your test suite unattended. If that is not your situation, keep it to a machine or container scoped for the purpose. Replacing the blanket permission skip with a narrower confinement is on the roadmap; the constraint to solve is that adopter validation commands legitimately need network and system access the sandbox would block. Security reports go through [SECURITY.md](SECURITY.md).
 

package/dist/cli/index.js

@@ -403,6 +403,11 @@ function filterGitIgnoredPaths(paths, cwd) {
   const stdout = result.stdout ?? "";
   return new Set(stdout.split("\0").filter((p) => p.length > 0));
 }
+var CANON_TASK_ID_PATTERN = "[a-z0-9][a-z0-9._-]*";
+var SCAFFOLD_ARTIFACTS_SUBJECT = new RegExp(`^task\\(${CANON_TASK_ID_PATTERN}\\): commit artifacts pre-pipeline$`);
+var SCAFFOLD_TELEMETRY_SUBJECT = new RegExp(
+  `^chore: absorb pre-implement telemetry into scaffold for ${CANON_TASK_ID_PATTERN}(?:, ${CANON_TASK_ID_PATTERN})*$`
+);
 
 // src/orchestrator/worktree.ts
 var PIPELINE_TELEMETRY_FILES = [
@@ -1500,7 +1505,7 @@ function checkTemplates(cwd) {
 }
 function checkCanonVersion(cwd) {
   const versionPath = join(cwd, ".canon", "version");
-  const installedVersion = "3.11.0";
+  const installedVersion = "3.12.0";
   if (!existsSync(versionPath)) {
     return { label: ".canon/version", status: "warn", detail: "missing \u2014 run `canon upgrade`" };
   }
@@ -2025,7 +2030,7 @@ function initCmd(_args) {
 }
 function writeCanonVersion(cwd) {
   const versionPath = join2(cwd, ".canon", "version");
-  const version = "3.11.0";
+  const version = "3.12.0";
   mkdirSync(dirname2(versionPath), { recursive: true });
   writeFileSync(versionPath, version + "\n");
 }
@@ -2382,6 +2387,9 @@ function findFirstBlockedPhase(status) {
   }
   return null;
 }
+function isFullSendTailPending(status) {
+  return status.full_send === true && status.status === "human_review" && (status.phases.human_review?.status ?? "pending") === "pending";
+}
 function findPreviousDonePhase(status, beforePhase) {
   const index = PHASE_ORDER.indexOf(beforePhase);
   for (let i = index - 1; i >= 0; i -= 1) {
@@ -2518,6 +2526,8 @@ function parseWatchArgs(args2) {
 }
 function summarizeIdle(result) {
   switch (result.kind) {
+    case "live":
+      throw new Error("summarizeIdle called for live result");
     case "checkpoint":
       return { state: result.state, reason: "checkpoint", phase: result.phase, verdict: result.verdict, pid: result.pid };
     case "complete":
@@ -2572,6 +2582,15 @@ function classifyAttach(ctx, taskId, probeAlive, now) {
     return { kind: "launch_window", state };
   }
   if (status) {
+    if (isFullSendTailPending(status)) {
+      if (orchestratorLive && ctx.resolvedPid != null) {
+        return { kind: "live", pid: ctx.resolvedPid, state };
+      }
+      const heartbeatPrimary = ctx.heartbeatResult.kind === "found" ? ctx.heartbeatResult.record.task_ids[0] : void 0;
+      const primaryId = typeof heartbeatPrimary === "string" && heartbeatPrimary.length > 0 ? heartbeatPrimary : taskId;
+      const reason = findCrashEvidence(ctx, taskId, probeAlive, primaryId, orchestratorLive);
+      if (reason) return { kind: "death", state, hint: `run \`canon run ${taskId}\` to resume`, reason };
+    }
     const currentPhase = PHASE_ORDER.find((phase) => (status.phases[phase]?.status ?? "pending") !== "done");
     const currentStatus = currentPhase ? status.phases[currentPhase]?.status ?? "pending" : null;
     if (currentPhase && currentPhase !== "human_review" && (currentStatus === "pending" || currentStatus === "in_progress")) {
@@ -2634,6 +2653,13 @@ function classifyIdle(ctx, taskId, probeAlive = () => false, now = Date.now(), p
     return { kind: "auto_block", state: "blocked", phase: blockedPhase, pid: ctx.resolvedPid ?? void 0 };
   }
   if (state === "human_review") {
+    if (isFullSendTailPending(status)) {
+      if (orchestratorLive && ctx.resolvedPid != null) {
+        return { kind: "live", state, pid: ctx.resolvedPid };
+      }
+      const crashReason = findCrashEvidence(ctx, taskId, probeAlive, primaryTaskId, orchestratorLive);
+      if (crashReason) return { kind: "death", state, pid: ctx.resolvedPid ?? void 0, reason: crashReason };
+    }
     const verdict = status.phases.code_review?.verdict || void 0;
     return {
       kind: "checkpoint",
@@ -2689,6 +2715,7 @@ function orchestratorStillProgressing(ctx, probeAlive, now = Date.now()) {
   const status = ctx.statusResult.kind === "ok" && isStatusJson(ctx.statusResult.status) ? ctx.statusResult.status : null;
   if (status == null) return false;
   if (findFirstBlockedPhase(status) && !blockedPhaseLivenessTrusted(ctx, orchestratorLive, now)) return false;
+  if (isFullSendTailPending(status)) return true;
   const state = status.status;
   return state !== "human_review" && state !== "complete";
 }
@@ -3007,6 +3034,11 @@ function watchCmd(args2, deps = {}) {
       return exit(0);
     }
     const idleResult = classifyIdle(freshCtx, taskId, isOrchestratorAlive, now(), rememberedPrimaryTaskId ?? void 0);
+    if (idleResult.kind === "live") {
+      reportPhasePointer(freshCtx);
+      if (parsed.follow) tailRunLog(freshCtx, taskId, { stderr }, tailState, rememberedPrimaryTaskId ?? void 0);
+      continue;
+    }
     if (idleResult.kind === "death" && idleResult.reason) {
       stderr(`canon watch: ${idleResult.reason}; run \`canon run ${taskId}\` to resume
 `);
@@ -3036,7 +3068,7 @@ function watchCmd(args2, deps = {}) {
 }
 
 // src/task/index.ts
-import { spawnSync as spawnSync8 } from "child_process";
+import { spawnSync as spawnSync9 } from "child_process";
 import fs16 from "fs";
 import path16 from "path";
 
@@ -3049,7 +3081,7 @@ function isInstalledSourcePath(sourcePath) {
   return sourcePath.includes("/node_modules/") || sourcePath.includes("\\node_modules\\") || sourcePath.includes("/_npx/") || sourcePath.includes("\\_npx\\");
 }
 function resolveCanonVersion(explicit) {
-  return explicit ?? "3.11.0" ?? "dev";
+  return explicit ?? "3.12.0" ?? "dev";
 }
 function resolveOrchestratorCommit(repoRoot, upstreamCommit, runGitAt) {
   const ownToplevel = captureGitOutput(repoRoot, ["rev-parse", "--show-toplevel"], runGitAt);
@@ -3183,6 +3215,7 @@ function isPristineTaskArtifact(content, basename2, taskId, title) {
 }
 
 // src/orchestrator/validation.ts
+import { spawnSync as spawnSync8 } from "child_process";
 import fs14 from "fs";
 import path14 from "path";
 function computeLatestValidationResults(handoffContent) {
@@ -3852,13 +3885,13 @@ function writeStatusAtomic(filePath, status) {
 }
 function runGit(args2, options = {}) {
   if (options.stdio === "inherit") {
-    return spawnSync8("git", args2, {
+    return spawnSync9("git", args2, {
       cwd: options.cwd ?? process.cwd(),
       encoding: "utf8",
       stdio: "inherit"
     });
   }
-  return spawnSync8("git", args2, {
+  return spawnSync9("git", args2, {
     cwd: options.cwd ?? process.cwd(),
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"]
@@ -4562,9 +4595,16 @@ function taskResetSpecReview(id) {
   if (status.sessions && Object.hasOwn(status.sessions, "claude_spec")) {
     delete status.sessions.claude_spec;
   }
+  const rearmGate = status.full_send !== true && status.human_spec_gate !== true;
+  if (rearmGate) status.human_spec_gate = true;
   status.updated = today();
   writeStatusAtomic(statusPath, status);
   console.log(`Reset ${id}: spec \u2192 done, spec_review \u2192 pending (iter=0, verdict cleared, claude_spec session dropped)`);
+  if (rearmGate) {
+    console.log(
+      `Re-armed the spec gate: the next \`canon run ${id}\` stops after spec_review approves. To continue past it instead, run \`canon task set ${id} human_spec_gate false\` first.`
+    );
+  }
 }
 function taskResetCodeReview(id) {
   if (!id) throw new Error("Error: usage: canon task reset-code-review <TASK-ID>");
@@ -4615,7 +4655,7 @@ function taskResetCodeReview(id) {
   );
 }
 function ensureGitAvailable() {
-  const result = spawnSync8("git", ["--version"], { stdio: "ignore" });
+  const result = spawnSync9("git", ["--version"], { stdio: "ignore" });
   if (result.error || result.status !== 0) {
     throw new Error("Error: git is required.");
   }
@@ -4996,7 +5036,7 @@ function taskCmd2(args2) {
 import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync3, realpathSync as realpathSync2, writeFileSync as writeFileSync2 } from "fs";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { dirname as dirname4, join as join4 } from "path";
-import { spawnSync as spawnSync9 } from "child_process";
+import { spawnSync as spawnSync10 } from "child_process";
 var packageDir3 = join4(dirname4(fileURLToPath4(import.meta.url)), "../..");
 function detectInstallType(pkgDirOverride) {
   const dir = pkgDirOverride ?? packageDir3;
@@ -5049,7 +5089,7 @@ function nonInteractiveSshCommand(configuredCommand) {
   return `${command2} -oBatchMode=yes`;
 }
 function defaultGitRunner(args2) {
-  const result = spawnSync9("git", args2, {
+  const result = spawnSync10("git", args2, {
     encoding: "utf8",
     timeout: GIT_RESOLUTION_TIMEOUT_MS,
     env: {
@@ -5234,7 +5274,7 @@ function currentPinFromManifest(manifest) {
   return "unknown";
 }
 function bakedVersion() {
-  return "3.11.0";
+  return "3.12.0";
 }
 function ownPackageName(pkgDir) {
   try {
@@ -5246,7 +5286,7 @@ function ownPackageName(pkgDir) {
 }
 var NPM_VIEW_TIMEOUT_MS = 3e4;
 function defaultNpmViewRunner(args2, cwd) {
-  const result = spawnSync9("npm", args2, { encoding: "utf8", timeout: NPM_VIEW_TIMEOUT_MS, ...cwd ? { cwd } : {} });
+  const result = spawnSync10("npm", args2, { encoding: "utf8", timeout: NPM_VIEW_TIMEOUT_MS, ...cwd ? { cwd } : {} });
   if (result.error) return { status: null, stdout: "", stderr: result.error.message };
   return { status: result.status, stdout: result.stdout ?? "", stderr: (result.stderr ?? "").trim() };
 }
@@ -5302,7 +5342,7 @@ function updateCmd(args2, deps = {}) {
   const pkgDir = deps.packageDir ?? packageDir3;
   const pkgName = ownPackageName(pkgDir);
   const cwd = deps.cwd ?? process.cwd();
-  const spawn2 = deps.spawnRunner ?? ((cmd, cmdArgs, opts) => spawnSync9(cmd, cmdArgs, { stdio: "inherit", cwd: opts.cwd }));
+  const spawn2 = deps.spawnRunner ?? ((cmd, cmdArgs, opts) => spawnSync10(cmd, cmdArgs, { stdio: "inherit", cwd: opts.cwd }));
   const runGit2 = deps.gitRunner ?? defaultGitRunner;
   const nowIso = deps.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
   let options;
@@ -5433,7 +5473,7 @@ function updateCmd(args2, deps = {}) {
 import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "fs";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { basename, dirname as dirname5, join as join5, relative as relative3, resolve } from "path";
-import { spawnSync as spawnSync10 } from "child_process";
+import { spawnSync as spawnSync11 } from "child_process";
 
 // src/lib/canon-owned.ts
 var CANON_OWNED = [
@@ -5542,7 +5582,7 @@ function classifyDestinations(cwd, relPaths) {
   const classes = /* @__PURE__ */ new Map();
   const uniqueRelPaths = [...new Set(relPaths)];
   if (uniqueRelPaths.length === 0) return classes;
-  const probe = spawnSync10("git", ["rev-parse", "--is-inside-work-tree"], {
+  const probe = spawnSync11("git", ["rev-parse", "--is-inside-work-tree"], {
     cwd,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"]
@@ -5554,12 +5594,12 @@ function classifyDestinations(cwd, relPaths) {
     }
     return classes;
   }
-  const lsFiles = spawnSync10("git", ["ls-files", "-z", "--", ...uniqueRelPaths], {
+  const lsFiles = spawnSync11("git", ["ls-files", "-z", "--", ...uniqueRelPaths], {
     cwd,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"]
   });
-  const status = spawnSync10("git", ["status", "--porcelain=v1", "-z", "--", ...uniqueRelPaths], {
+  const status = spawnSync11("git", ["status", "--porcelain=v1", "-z", "--", ...uniqueRelPaths], {
     cwd,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"]
@@ -5711,7 +5751,7 @@ function runUpgrade(cwd, pkgDir, options = {}) {
     cutoverWarnings.push(docsRefsCheckRel);
   }
   const versionPath = join5(cwd, ".canon", "version");
-  const newVersion = "3.11.0";
+  const newVersion = "3.12.0";
   const currentVersion = existsSync5(versionPath) ? readFileSync4(versionPath, "utf8").trim() : null;
   if (currentVersion !== newVersion) {
     pending.push({ rel: ".canon/version", projectPath: versionPath, content: newVersion + "\n" });
@@ -5864,7 +5904,7 @@ function upgradeCmd(args2) {
     process.exit(2);
   }
   if (upgraded.length > 0 && !options.noStage) {
-    const r = spawnSync10("git", ["add", ...upgraded], { cwd: process.cwd(), stdio: "inherit" });
+    const r = spawnSync11("git", ["add", ...upgraded], { cwd: process.cwd(), stdio: "inherit" });
     if (r.status !== 0) {
       console.error("\nwarning: failed to stage changes \u2014 run `git add` manually.");
     }
@@ -5992,14 +6032,17 @@ canon run options:
                           protected/configured docs listed in spec.md's "### Affected Files"
                           table (all admitted docs once QA is done). Dirty files outside
                           that set die with a remediation message.
-                          Aborts if HEAD's tree differs from origin/<base> on files not in
-                          spec's Affected Files (bypass with --force).
+                          Aborts if merging origin/<base> conflicts, or branch changes files
+                          outside spec's Affected Files (bypass with --force).
   --push                  At human_review: push branch only, no PR (requires gh). Same allow-list
-                          as --pr. Aborts if HEAD's tree differs from origin/<base> on files not
-                          in spec's Affected Files (bypass with --force).
+                          as --pr. Aborts if merging origin/<base> conflicts, or branch changes
+                          files outside spec's Affected Files (bypass with --force).
   --full-send             Skip the spec gate and auto-open a draft PR after clean QA
-  --force                 Acknowledge high-commitment combinations (currently: --full-send on a delicate task)
-  --ship                  Merge the open PR (calls gh pr merge --squash --delete-branch), tear
+  --force                 Acknowledge high-commitment combinations and bypass
+                          explicit safety gates where documented (currently:
+                          --full-send on delicate tasks, reroute amendment gate,
+                          base-drift gate, and dirty REPO_ROOT worktree-start gate)
+  --ship                  Merge the open PR (gh pr merge --squash), delete its remote branch, tear
                           down the worktree, archive the task dir, and pull the base branch. Run
                           after the PR is approved \u2014 do NOT merge the PR manually first. If you
                           already merged externally, --ship detects the merged state and resumes
@@ -6020,7 +6063,7 @@ Global:
 `);
 }
 function printVersion() {
-  console.log("3.11.0");
+  console.log("3.12.0");
 }
 switch (command) {
   case "doctor":