@ngockhoale/ukit 3.4.22 → 3.4.24

package/template_project/.claude/ukit/runtime/handoff-intent.mjs

@@ -27,21 +27,35 @@
 //        `intent` is the MOST RECENT qualifying intent, `known=false` when the scan
 //        could not complete (missing/unreadable path, budget overrun) — callers keep
 //        their fail-closed posture on `known=false`.
+//
+// Intent values stay the historical pair 'create' | 'fullstack': an exact
+// `handoff-implement` invocation CLAIMS the run (the fullstack command says so
+// itself), so it maps onto the existing 'fullstack' intent instead of adding a
+// new enum every consumer would have to learn (TASK-C97-004).
 
 import fs from 'node:fs/promises';
 
-export const HANDOFF_FULLSTACK_TAG = /<command-name>\/?(?:ukit:)?handoff-fullstack\b/;
-export const HANDOFF_CREATE_TAG = /<command-name>\/?(?:ukit:)?handoff-create\b/;
+// The `(?![\w-])` closer is the exact token boundary: a command name followed by
+// MORE name characters or a hyphen (`handoff-fullstack-custom`) is a different,
+// unsupported command — `\b` would still match there and let the suffix spoof
+// the intent.
+export const HANDOFF_FULLSTACK_TAG = /<command-name>\/?(?:ukit:)?handoff-fullstack(?![\w-])/;
+export const HANDOFF_CREATE_TAG = /<command-name>\/?(?:ukit:)?handoff-create(?![\w-])/;
 export const HANDOFF_RESUME_BANNER = 'UKIT HANDOFF RESUME — an unfinished handoff-fullstack run';
 
+// Sweeper for "which command tag came LAST in this entry": finds every exact
+// command-name tag occurrence with its position so the newest one wins.
+const COMMAND_TAG_SWEEP = /<command-name>\/?(?:ukit:)?handoff-(create|fullstack|implement)(?![\w-])/g;
+
 // omp and Codex do NOT wrap a slash command in `<command-name>` tags the way
 // Claude Code's user turn does. Their native evidence is the command *expansion*:
 // omp replaces `/ukit:handoff-fullstack` with the command body, whose FIRST
 // non-empty line is the H1 `# /ukit:handoff-fullstack — …`; Codex records the same
 // expanded body as a `response_item`/`message` with `input_text` blocks. Matching
 // the FIRST line only (not any heading in the body) keeps prose references to the
-// command inside the document from being mistaken for an invocation.
-const NATIVE_COMMAND_HEADING = /^\s{0,3}#{1,3}\s+\/?(?:ukit:)?(handoff-create|handoff-fullstack)\b/;
+// command inside the document from being mistaken for an invocation. The same
+// exact token boundary applies: `-custom` suffixed headings are not commands.
+const NATIVE_COMMAND_HEADING = /^\s{0,3}#{1,3}\s+\/?(?:ukit:)?(handoff-create|handoff-fullstack|handoff-implement)(?![\w-])/;
 
 // The unique customType the omp bridge stamps on host-injected UKit hook context
 // (`sendContext` → `hookContextMessage`). A resume banner only counts as intent
@@ -62,6 +76,19 @@ function firstNonEmptyLine(text) {
   return '';
 }
 
+/**
+ * Map an exact command token (full `handoff-implement` or the captured suffix
+ * `implement`) onto the two intent values. `handoff-implement` CLAIMS the run,
+ * so it maps onto the existing 'fullstack' intent.
+ * @returns {'create' | 'fullstack' | null}
+ */
+function commandTokenIntent(token) {
+  const t = String(token).toLowerCase().replace(/^handoff-/, '');
+  if (t === 'create') return 'create';
+  if (t === 'fullstack' || t === 'implement') return 'fullstack';
+  return null;
+}
+
 /**
  * Does this text open with a native (omp/Codex) command-expansion heading?
  * Only the FIRST non-empty line is inspected, so an H1 that appears later in the
@@ -72,7 +99,7 @@ function firstNonEmptyLine(text) {
 function nativeCommandIntent(text) {
   const m = firstNonEmptyLine(text).match(NATIVE_COMMAND_HEADING);
   if (!m) return null;
-  return m[1] === 'handoff-create' ? 'create' : 'fullstack';
+  return commandTokenIntent(m[1]);
 }
 
 // Bounds for the tail scan. Recency is what matters, so the reader walks the
@@ -109,51 +136,61 @@ function splitUserContent(content) {
   return { text, blocks, hasToolOutput };
 }
 
+/**
+ * Classify one user text block. Structured evidence only: exact Claude Code
+ * `<command-name>` tags (the LAST one in the block wins) or a native
+ * command-expansion heading on the block's first line.
+ * @returns {'fullstack' | 'create' | null}
+ */
+function classifyUserText(text) {
+  const tags = [...String(text ?? '').matchAll(COMMAND_TAG_SWEEP)];
+  if (tags.length > 0) return commandTokenIntent(tags[tags.length - 1][1]);
+  return nativeCommandIntent(text);
+}
+
 /**
  * Classify a user turn (Claude Code `type:'user'`, omp `type:'message'` role user,
- * Codex `type:'response_item'` payload message role user). Structured evidence only:
- * a Claude Code `<command-name>` tag, or a native command-expansion heading on the
- * first line of a user text block.
+ * Codex `type:'response_item'` payload message role user). The LATEST qualifying
+ * evidence inside the entry wins — a later tag/block supersedes an earlier one,
+ * while trailing non-qualifying content never erases it. Tool-output blocks
+ * (`tool_result` round-trips) are not user words and never carry intent, so a
+ * turn that is purely tool output has no user text to match.
  * @returns {'fullstack' | 'create' | null}
  */
 function classifyUserTurn(content) {
-  const { text, blocks, hasToolOutput } = splitUserContent(content);
-  // Check the planning tag first: a single turn carrying both is a create turn.
-  if (HANDOFF_CREATE_TAG.test(text)) return 'create';
-  if (HANDOFF_FULLSTACK_TAG.test(text)) return 'fullstack';
-  // Native (omp / Codex) command expansion — the FIRST line of a user text block.
-  // A user turn that is purely tool output has no user text to match, so a
-  // `tool_result` carrying the marker string can never register as intent.
+  const { blocks } = splitUserContent(content);
+  let latest = null;
   for (const block of blocks) {
-    const intent = nativeCommandIntent(block);
-    if (intent) return intent;
+    const intent = classifyUserText(block);
+    if (intent) latest = intent;
   }
-  if (hasToolOutput) return null;
-  return null;
+  return latest;
 }
 
 /**
  * Classify assistant tool-call blocks. Handles both Claude Code (`tool_use`, name
- * `Skill`, input.skill) and omp (`toolCall`, name/arguments.skill).
+ * `Skill`, input.skill) and omp (`toolCall`, name/arguments.skill). The LAST
+ * qualifying block wins; unrelated tool blocks never erase it.
  */
 function classifyAssistantBlocks(blocks) {
   if (!Array.isArray(blocks)) return null;
+  let latest = null;
   for (const b of blocks) {
     if (!b || typeof b !== 'object') continue;
     if (b.type === 'tool_use' && b.name === 'Skill') {
       const skill = String(b.input?.skill ?? '');
-      if (/^(?:ukit:)?handoff-create$/.test(skill)) return 'create';
-      if (/^(?:ukit:)?handoff-fullstack$/.test(skill)) return 'fullstack';
+      const m = /^(?:ukit:)?handoff-(create|fullstack|implement)$/.exec(skill);
+      if (m) latest = commandTokenIntent(m[1]);
       continue;
     }
     if (b.type === 'toolCall') {
       const name = String(b.name ?? '');
       const skill = String(b.arguments?.skill ?? '');
-      if (/^(?:ukit:)?handoff-create$/i.test(name) || /^(?:ukit:)?handoff-create$/.test(skill)) return 'create';
-      if (/^(?:ukit:)?handoff-fullstack$/i.test(name) || /^(?:ukit:)?handoff-fullstack$/.test(skill)) return 'fullstack';
+      const m = /^(?:ukit:)?handoff-(create|fullstack|implement)$/i.exec(name) || /^(?:ukit:)?handoff-(create|fullstack|implement)$/.exec(skill);
+      if (m) latest = commandTokenIntent(m[1]);
     }
   }
-  return null;
+  return latest;
 }
 
 /**
@@ -170,7 +207,9 @@ function classifyAssistantBlocks(blocks) {
  *   - Codex:        `{ type:'response_item', payload:{ type:'message', role:'user', content:[input_text…] } }`
  *
  * Anything else — including a format we do not recognise — returns null (never a
- * guessed intent), so the caller's fail-closed posture is preserved.
+ * guessed intent), so the caller's fail-closed posture is preserved. Within one
+ * entry the LATEST qualifying evidence wins; `-custom` suffixed command names and
+ * tool-result / unknown-namespace content are never intent.
  * @returns {'fullstack' | 'create' | null}
  */
 export function classifyHandoffEntry(entry) {
@@ -263,11 +302,30 @@ export async function transcriptHandoffIntent(transcriptPath, {
       const line = lines[i];
       if (!line) continue;
       // Cheap prefilter — skip JSON.parse for lines that cannot be evidence.
-      if (!line.includes('handoff-create') && !line.includes('handoff-fullstack') && !line.includes('HANDOFF RESUME')) {
+      // `handoff-implement` is included: an implement invocation after a create
+      // must be seen as the NEWEST intent, not lost to the older create line.
+      if (!line.includes('handoff-create') && !line.includes('handoff-fullstack') && !line.includes('handoff-implement') && !line.includes('HANDOFF RESUME')) {
         continue;
       }
-      const intent = classifyHandoffLine(line);
+      // This is the NEWEST line carrying intent evidence. A host append can be
+      // cut mid-record (killed turn, torn write), leaving this line as unparseable
+      // JSON. Skipping it like any other non-qualifying line would fall through to
+      // an OLDER — possibly OPPOSITE — intent and misreport the session's current
+      // ownership (a torn `handoff-implement` after a create released a real
+      // fullstack run). An incomplete newest evidence-bearing record is therefore
+      // UNDETERMINED, not "no intent": return unknown so fail-closed callers keep
+      // their blocking/conservative posture (MODULE02-SPEC FR-M2-002).
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        return { intent: null, known: false };
+      }
+      const intent = classifyHandoffEntry(entry);
       if (intent) return { intent, known: true };
+      // Complete record that carries no recognised intent (tool output, a foreign
+      // envelope, a malformed-but-whole unrelated line): not evidence — keep
+      // walking older lines.
     }
     // Nothing found. Only a scan of the WHOLE transcript proves "no handoff
     // intent"; a tail window that missed it (the invoking turn usually appears

package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -43,6 +43,23 @@ const FAIL_CLOSED_SCRIPTS = new Set([
 
 const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
 
+// C97 (SPEC §FR-002): bound for replaying a triggering step's already-captured
+// stderr diagnostic in the skippedFailClosed verdict. Large enough for real
+// causes, small enough that a flooded capture cannot drown the skipped-gate
+// notice. The excerpt is cut at a UTF-8 code-point boundary so the emitted
+// diagnostic is always valid UTF-8.
+const CAUSE_EXCERPT_MAX_BYTES = 4096;
+
+function boundedUtf8Excerpt(text, maxBytes = CAUSE_EXCERPT_MAX_BYTES) {
+  const buf = Buffer.from(String(text ?? ''), 'utf8');
+  if (buf.length <= maxBytes) return { text: buf.toString('utf8'), truncated: false };
+  let end = maxBytes;
+  // Back off over UTF-8 continuation bytes (0b10xxxxxx) so the cut never
+  // splits a code point.
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end--;
+  return { text: buf.subarray(0, end).toString('utf8'), truncated: true };
+}
+
 // TASK-234 review fix (critical): stdin staging must be bounded. The old
 // `fs.readFileSync(0)` blocked until the producer closed the pipe — a stalled
 // producer held the runner until the settings timeout SIGKILLed it, so every
@@ -700,14 +717,57 @@ try {
       // TASK-234 review fix (critical): a mid-chain break that skipped a
       // fail-closed gate must fail CLOSED — the old per-script path ran every
       // hook independently, so a killed advisory never skipped a gate.
+      // C97 (SPEC §FR-002): the old emission named the unrun gates but dropped
+      // the triggering step's already-captured diagnostic entirely (the
+      // sibling fail-closed branch below DOES replay `last.stderr`), so an
+      // exit-1 gate's cause never reached the operator. Provenance now names
+      // the triggering result's step + failureKind — an actual child as the
+      // attempted step; the synthetic budget-exhausted result (elapsedMs 0,
+      // killed true: the script never launched) explicitly as unattempted —
+      // and replays the step's captured stderr ONCE, bounded. An
+      // output-overflow capture is truncated mid-stream and may embed anything
+      // (payloads, secrets), so it never leaves this process; the generic
+      // stdout message carries no raw stderr.
       if (contextStdout) process.stdout.write(contextStdout);
+      const broke = chain.results[chain.results.length - 1] ?? null;
       const skipped = scriptPaths
         .slice(chain.results.length)
         .map((p) => failClosedName(p))
         .filter((name) => FAIL_CLOSED_SCRIPTS.has(name))
         .join(', ');
+      const unattempted = broke?.failureKind === 'budget-exhausted';
+      const causeLabel = !broke
+        ? 'unknown step'
+        : unattempted
+          ? `${broke.scriptName} (${broke.failureKind}, unattempted — budget exhausted before launch)`
+          : `${broke.scriptName} (${broke.failureKind}, attempted step)`;
+      const provenanceMsg = `UKit hook chain broke at ${causeLabel}.\n`;
       const brokeMsg = `UKit hook chain broke before fail-closed gate(s) ran: ${skipped}\n`;
+      process.stderr.write(provenanceMsg);
+      const causeText = broke
+        && broke.failureKind !== 'output-overflow'
+        && typeof broke.stderr === 'string'
+        ? broke.stderr
+        : '';
+      if (causeText.trim()) {
+        const excerpt = boundedUtf8Excerpt(causeText);
+        process.stderr.write(
+          excerpt.truncated
+            ? `${excerpt.text}\n[ukit] cause excerpt truncated at ${CAUSE_EXCERPT_MAX_BYTES} UTF-8 bytes\n`
+            : (excerpt.text.endsWith('\n') ? excerpt.text : `${excerpt.text}\n`),
+        );
+      }
       process.stderr.write(brokeMsg + breakerAdvice(brokeMsg));
+      if (!contextStdout) {
+        // Otherwise-empty stdout: emit exactly ONE parseable JSON document so
+        // the host still gets a single valid verdict — the generic failure
+        // (step/kind/skipped gates), never the raw cause. Appending it after
+        // prior stdout would create an invalid two-document stream, so prior
+        // stdout suppresses it entirely.
+        process.stdout.write(JSON.stringify({
+          systemMessage: `${provenanceMsg.trimEnd()} ${brokeMsg.trimEnd()}`,
+        }));
+      }
       process.exitCode = 2;
     } else if (!last) {
       // No script ran at all (empty chain or budget spent before the first

package/template_project/.claude/ukit/runtime/observability-emit.mjs

@@ -143,9 +143,19 @@ const REASON_CODES = new Set([
 
 const RESOURCE_SEMANTICS = new Set(['model.completed', 'model.failed']);
 
+// Schema v1.3 additive payload extension (C98 FR-02): closed usage-category
+// key set — mirror of USAGE_CATEGORY_KEYS in schema/constants.js.
+const USAGE_CATEGORY_KEYS = Object.freeze([
+  'fresh_input_tokens',
+  'cache_read_tokens',
+  'cache_write_tokens',
+  'output_tokens',
+  'reasoning_tokens',
+]);
+
 // --- frozen privacy contract (mirror of privacy/allowlist.js) ------------
 
-const REDACTION_VERSION = 'df-redact-6';
+const REDACTION_VERSION = 'df-redact-7';
 const ALLOWED_FIELDS = ENVELOPE_FIELDS;
 const DENIED_PAYLOAD_FIELDS = new Set([
   'error_detail', 'feedback', 'comment', 'note_text', 'prompt', 'prompt_text',
@@ -299,7 +309,47 @@ function sanitizeObserved(record, options = {}) {
 
 // --- validate (mirror of schema/validate.js, sans cross-record context) ----
 
-function validateSemanticRecord(record) {
+// Schema v1.3 additive payload extension (SPEC FR-02): typed per-category
+// token usage on model.completed|failed. Accept/reject outcomes must match
+// validateUsageCategories in src/core/observability/schema/validate.js
+// exactly; message texts may differ.
+function validateUsageCategories(payload, semanticName, errors) {
+  const categories = payload.usage_categories;
+  if (categories === undefined || categories === null) return;
+  if (semanticName !== 'model.completed' && semanticName !== 'model.failed') {
+    errors.push('payload.usage_categories is only valid on model.completed|model.failed');
+    return;
+  }
+  if (!isPlainObject(categories)) {
+    errors.push('payload.usage_categories must be an object keyed by usage category');
+    return;
+  }
+  for (const [key, category] of Object.entries(categories)) {
+    if (!USAGE_CATEGORY_KEYS.includes(key)) {
+      errors.push(`payload.usage_categories.${key} is not a known usage category`);
+      continue;
+    }
+    if (!isPlainObject(category)) {
+      errors.push(`payload.usage_categories.${key} must be an object {value, source}`);
+      continue;
+    }
+    if (!RESOURCE_SOURCES.has(category.source)) {
+      errors.push(`payload.usage_categories.${key}.source invalid`);
+    }
+    const { value } = category;
+    if (value === null) {
+      if (category.source !== 'UNKNOWN') {
+        errors.push(`payload.usage_categories.${key}.value must be null only when source is UNKNOWN`);
+      }
+    } else if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+      errors.push(`payload.usage_categories.${key}.value must be a finite integer >= 0 or null`);
+    } else if (category.source === 'UNKNOWN') {
+      errors.push(`payload.usage_categories.${key}.value must be null when source is UNKNOWN`);
+    }
+  }
+}
+
+export function validateSemanticRecord(record) {
   const errors = [];
   if (!isPlainObject(record)) return { ok: false, errors: ['record must be a plain object'] };
 
@@ -385,6 +435,7 @@ function validateSemanticRecord(record) {
     errors.push('payload must be an object');
   } else {
     const payload = record.payload;
+    validateUsageCategories(payload, record.semantic_name, errors);
     if (payload.resource !== undefined && payload.resource !== null) {
       const resource = payload.resource;
       if (!isPlainObject(resource)) {

package/template_project/.claude/ukit/runtime/output-compression.mjs

@@ -1204,6 +1204,18 @@ function extractExitCode(payload) {
   return null;
 }
 
+// FR-M5-004 (TASK-C97-014): child identity is a top-level, nonempty, trimmed string
+// `agent_id` OR `agent_type` — the same documented subagent marker skill-router.sh
+// reads for its sidechain guard. Nested output text that merely contains marker
+// words is never authority, and missing/blank/nonstring markers fall through to the
+// existing main-session accounting unchanged.
+function isChildToolPayload(payload) {
+  if (!payload || typeof payload !== 'object') return false;
+  return [payload.agent_id, payload.agent_type].some(
+    (marker) => typeof marker === 'string' && marker.trim() !== '',
+  );
+}
+
 function extractText(payload, preferredKeys = []) {
   const queue = [payload];
   const seen = new Set();
@@ -1376,6 +1388,10 @@ async function main() {
 
   const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const config = await loadRuntimeConfig(projectRoot);
+  // FR-M5-004 (TASK-C97-014): resolved once from the parsed payload and applied at
+  // BOTH raw-output pressure updates below. Deliberately NOT an early exit — the
+  // compression, cache, history, tee and hard-cap paths all keep running for a child.
+  const isChildOutput = isChildToolPayload(payload);
   // Session-scoped pressure bookkeeping: output tokens must land in the calling
   // session's record, never a sibling session's.
   const sessionConfig = {
@@ -1448,16 +1464,21 @@ async function main() {
         recoveryReason: cached.metadata?.recoveryReason ?? null,
         truncated: Boolean(cached.metadata?.truncated),
       });
-      await updateCompactPressureFromOutput(projectRoot, {
-        timestamp: Date.now(),
-        command: cachedCommand,
-        profile: cachedProfile,
-        summary: String(cached.content),
-        tokensBefore: cached.tokensBefore ?? 0,
-        tokensAfter: cached.tokensAfter ?? 0,
-        savedTokens: cached.savedTokens ?? 0,
-        exitCode,
-      }, sessionConfig);
+      // FR-M5-004: a subagent's raw output must not be charged to its parent's
+      // compact pressure. Suppress ONLY this pressure write — cache/history/tee
+      // writes above, the summary on stdout below, and every safety gate are untouched.
+      if (!isChildOutput) {
+        await updateCompactPressureFromOutput(projectRoot, {
+          timestamp: Date.now(),
+          command: cachedCommand,
+          profile: cachedProfile,
+          summary: String(cached.content),
+          tokensBefore: cached.tokensBefore ?? 0,
+          tokensAfter: cached.tokensAfter ?? 0,
+          savedTokens: cached.savedTokens ?? 0,
+          exitCode,
+        }, sessionConfig);
+      }
       process.stdout.write(String(cached.content));
       return;
     }
@@ -1548,16 +1569,21 @@ async function main() {
     savedTokens: result.savedTokens,
     metadata: { command: result.command, exitCode },
   });
-  await updateCompactPressureFromOutput(projectRoot, {
-    timestamp: Date.now(),
-    command: result.command,
-    profile: result.profile,
-    summary: result.summary,
-    tokensBefore: result.tokensBefore,
-    tokensAfter: result.tokensAfter,
-    savedTokens: result.savedTokens,
-    exitCode,
-  }, sessionConfig);
+  // FR-M5-004: same suppression on the fresh path — a child's raw output never
+  // charges the parent's compact estimate; compression, history, tee, the recovery
+  // anchor and every downstream gate keep their existing behavior.
+  if (!isChildOutput) {
+    await updateCompactPressureFromOutput(projectRoot, {
+      timestamp: Date.now(),
+      command: result.command,
+      profile: result.profile,
+      summary: result.summary,
+      tokensBefore: result.tokensBefore,
+      tokensAfter: result.tokensAfter,
+      savedTokens: result.savedTokens,
+      exitCode,
+    }, sessionConfig);
+  }
 
   if (config?.tokenPipeline?.promptCache) {
     await writePromptCacheEntry(projectRoot, {

package/template_project/.claude/ukit/runtime/stop-coordinator.mjs

@@ -966,7 +966,7 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   } catch {
     return { kind: 'none' };
   }
-  const { goal, phase, cursor, next, exitPredicate } = parseRunCursor(text);
+  const { command, goal, phase, cursor, next, exitPredicate } = parseRunCursor(text);
   // Shared terminal predicate — tests/handoff/cycle21 greps this exact shape across
   // all four RUN.md consumers; keep `^(done|blocked)` as one expression.
   const terminal = String(phase).match(/^(done|blocked)\b/i)?.[1]?.toLowerCase() || '';
@@ -980,7 +980,8 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   // must not be bounced into a stale run. Only a positive "scanned the whole
   // transcript, latest intent is not fullstack" releases; unknown (null) keeps
   // the block, so a real run is never released by a lost read.
-  if (gate.scope === 'session' && await transcriptShowsHandoffRun(transcriptPath) === false) {
+  const transcriptOwner = gate.scope === 'session' ? await transcriptShowsHandoffRun(transcriptPath) : true;
+  if (gate.scope === 'session' && transcriptOwner === false) {
     return { kind: 'none' };
   }
 
@@ -1008,6 +1009,19 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
     return { kind: 'block', reason: lines.join('\n') };
   }
 
+  // Nonterminal planning cursor (TASK-C97-006, FR-M2-003): a RUN.md whose Command
+  // is EXACTLY `handoff-create` is the planner's own cursor — it does not demand
+  // fullstack implementation even when the session's intent is unknown (no
+  // transcript path, unreadable, known-null). Stop releases UNLESS the latest
+  // structured intent positively reacquired the run (`fullstack`: an explicit
+  // handoff-implement or handoff-fullstack turn). This is the ONLY command
+  // exception: actual handoff-fullstack/implement/review and a missing/unknown
+  // Command keep the legacy posture, including the unknown fail-closed block. The
+  // terminal `done` branch above is untouched.
+  if (String(command).trim().toLowerCase() === 'handoff-create' && transcriptOwner !== true) {
+    return { kind: 'none' };
+  }
+
   const signature = `${phase}|${cursor}|${next}`;
   const streak = await bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs });
   if (streak !== null && streak > gate.maxStalledBlocks) {

package/template_project/.omp/agents/feature-implementer.md

@@ -138,9 +138,16 @@ mode only; daily flow does not get a Progress section.
   reports `undeclared-drift`.
 - **Milestone commit.** The commit lives on your worktree branch only (e.g.
   `handoff/task-xxx`). Use a `-m "milestone: <name>"` message. Never commit outside your
-  worktree, never push. The orchestrator's copy-back step (`git diff --name-only` against
-  base) diffs the working tree, so intermediate commits on the worktree branch are free —
-  **copy-back is unaffected** by milestone commits.
+  worktree, never push. The orchestrator's copy-back step lands the branch's final
+  base-relative snapshot (`land-worktree.mjs` diffs the working tree against the immutable
+  base), so intermediate commits on the worktree branch are free — **copy-back is
+  unaffected** by milestone commits.
+- **Final clean milestone commit (required before PASS).** End your run with one final
+  milestone commit so the worktree's snapshot equals its committed tree — nothing staged,
+  nothing unstaged, no nonignored untracked file left behind. A Git-clean snapshot is what
+  lets a later receipt-gated cleanup remove the worktree without `--force`; a tree dirty
+  against the snapshot is retained with a named reason, never forced. Do not report PASS on
+  a dirty worktree.
 - **Resume.** When a previous run aborted, you will be respawned. Read `## Progress`,
   jump straight to the last entry whose `last-green:` is not `none`, and continue from
   there. Do NOT re-plan, do NOT restart from RED, do NOT re-write tests that already