heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/claim-tools.mjs

@@ -0,0 +1,1147 @@
+// Claim lifecycle tools: heyspex_claim_spec, report_progress, submit_for_review,
+// release_spec, record_wip, defer_spec, record_alignment, claim_acquire/release/list,
+// claim_file, release_file_claim. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { findSpecFile, parseFrontmatter, resolveSpecIdViaTier } from './vault-io.mjs';
+import { join } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { childKindFor, getChildRefs, upsertFrontmatterKeys } from './alignment-gate.mjs';
+import { measureDiskLanding, resolveSpecIdForMutation } from './tool-helpers.mjs';
+import { stampSkippedDespiteFindingsOnBreakdownMarker } from './plan-review.mjs';
+import { resolveNextOnDeckPayload } from './on-deck-brief.mjs';
+import { consoleReadErrorFrom, ConsoleUnreachableCloudModeError, readViaSelector, resolveReadTier } from './read-path.mjs';
+import { detectAgentIdentity, effectiveConsoleUrl } from './mcp-config.mjs';
+import { consoleFetch, controlError, controlOk, enrichConsoleFailurePayloadAsync, postClaimEndpoint } from './console-transport.mjs';
+import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
+import { executeSubmitForReview } from './submit-for-review.mjs';
+import { deferControlWrite } from './write-outbox.mjs';
+
+const isCloudReliant = async () => (await resolveReadTier()) === 'neon';
+
+/**
+ * Minimum length for an alignment override reason. Matches the bar the milestone
+ * attach override already uses (promote-research.mjs) so the two overrides in
+ * this system hold to one standard.
+ */
+export const ALIGNMENT_OVERRIDE_REASON_MIN_LENGTH = 40;
+
+/**
+ * Record that ONE part of a `heyspex_record_alignment` call did not happen, on a
+ * call whose main write did ([[HS-IOJW-5YDH-DIAG]] sweep).
+ *
+ * The old shape put the failure in `payload.skipped_despite_findings_error` and
+ * still returned `ok: true` with no `isError`, so a half-happened write read
+ * exactly like a write that happened. This marks the payload so
+ * `alignmentResult` can flip it to an explicit partial — while keeping every
+ * fact that DID land (the read-back alignment stamp, the chained on-deck brief),
+ * because the checkpoint is real and must not be re-done.
+ *
+ * @param {Record<string, unknown>} payload
+ * @param {string} part — the sub-write that failed, e.g. 'skipped_despite_findings'
+ * @param {unknown} detail — the failure as reported by the writer
+ */
+export function markAlignmentPartial(payload, part, detail) {
+  payload.ok = false;
+  payload.partial = true;
+  payload.alignment_recorded = true;
+  payload[`${part}_recorded`] = false;
+  payload[`${part}_error`] = detail;
+  const failed = Array.isArray(payload.failed_parts) ? payload.failed_parts : [];
+  failed.push(part);
+  payload.failed_parts = failed;
+  payload.partial_message =
+    `PARTIAL: the alignment checkpoint for ${payload.spec_id ?? 'this spec'} WAS recorded and read back, ` +
+    `but ${failed.join(', ')} was NOT. Do not re-run record_alignment to fix this — the checkpoint is already ` +
+    'stamped; act on the per-part error below.';
+  return payload;
+}
+
+/** Wrap a record_alignment payload, surfacing a partial as an error, not a success. */
+export function alignmentResult(payload) {
+  const text = JSON.stringify(payload, null, 2);
+  return payload.partial === true
+    ? { isError: true, content: [{ type: 'text', text }] }
+    : { content: [{ type: 'text', text }] };
+}
+
+/**
+ * Stamp the alignment checkpoint onto an epic/milestone's frontmatter so the
+ * pre-execution gate clears. Writes only `alignment_reviewed_at` (+ optional
+ * summary/override); AGV2/DSIG dropped `alignment_signature` because it was
+ * non-deterministic across reads. The next /hs-next sees the fresh timestamp
+ * and stays quiet until the fuse expires (or corpus drift surfaces).
+ *
+ * AGV2/286X: after the write, chain into `resolveNextOnDeckPayload` and embed
+ * the result as `next_on_deck` so the agent can execute the next brief without
+ * a manual `/hs-next` re-invoke. The chain is best-effort — if it errors, we
+ * still return `ok: true` so the recorded checkpoint is not lost.
+ * [[pre-execution-alignment-gate]] [[HS-TASK-286X]]
+ */
+export function handleRecordAlignment(vaultRoot, config, args) {
+  const specId = args.spec_id;
+  if (!specId) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'MISSING_SPEC_ID' }) }],
+    };
+  }
+  const specPath = findSpecFile(vaultRoot, specId);
+  if (!specPath) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'SPEC_NOT_FOUND', message: `Spec ${specId} not found` }) }],
+    };
+  }
+  const fullPath = join(vaultRoot, specPath);
+  const raw = readFileSync(fullPath, 'utf-8');
+  const { frontmatter } = parseFrontmatter(raw);
+  const grain =
+    frontmatter.type === 'milestone' ? 'milestone' : 'epic';
+  const childIds = getChildRefs(frontmatter, grain);
+  const reviewedAt = new Date().toISOString();
+
+  const kv = {
+    alignment_reviewed_at: reviewedAt,
+  };
+  if (args.summary) {
+    kv.alignment_summary = JSON.stringify(String(args.summary));
+  }
+  // An override clears a real drift finding, so it has to say something. Any
+  // non-empty string used to be enough — "x" cleared the gate — which made the
+  // override a formality rather than a decision. Same ≥40-char bar the milestone
+  // attach override already carries in promote-research.mjs, and the same reason
+  // the plan gate refuses a summary under 80: a question only works when a thin
+  // answer is rejected.
+  //
+  // The `reason.length > 0` guard used to sit on the refusal, which meant a
+  // whitespace-only reason trimmed to EMPTY, skipped the refusal entirely, stored
+  // nothing, and still came back `overridden: true` — forty spaces cleared a real
+  // drift finding and reported that a reason had been recorded
+  // ([[HS-N71O-P3XQ-DIAG-six-new-qc-gates-fail-cold-verification]] item 3c).
+  // Whitespace-only is a thin answer, not an absent one: pass no
+  // `override_reason` at all if the review was clean.
+  let storedOverride = false;
+  if (args.override_reason !== undefined && args.override_reason !== null) {
+    const reason = String(args.override_reason).trim();
+    if (reason.length < ALIGNMENT_OVERRIDE_REASON_MIN_LENGTH) {
+      return {
+        isError: true,
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: 'ALIGNMENT_OVERRIDE_REASON_TOO_THIN',
+            message:
+              `override_reason is ${reason.length} characters after trimming${reason.length === 0 ? ' (it was empty or whitespace only)' : ''} — it must be at least ${ALIGNMENT_OVERRIDE_REASON_MIN_LENGTH} and say WHY the drift finding is a false positive or an intentional supersession. It is stored on the spec as the audit record of that call, so ${reason.length === 0 ? 'blank space' : `"${reason}"`} tells the next reader nothing. Omit override_reason entirely if the review was clean.`,
+            override_reason_length: reason.length,
+            minimum: ALIGNMENT_OVERRIDE_REASON_MIN_LENGTH,
+          }),
+        }],
+      };
+    }
+    kv.alignment_override = JSON.stringify(reason);
+    storedOverride = true;
+  }
+  const updated = upsertFrontmatterKeys(raw, kv);
+  try {
+    writeFileSync(fullPath, updated, 'utf-8');
+  } catch (e) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'WRITE_FAILED', message: e.message }) }],
+    };
+  }
+
+  // Report on the RESULT, not the request ([[HS-IOJW-5YDH-DIAG]] sweep). This is
+  // a frontmatter rewrite, so "the file exists" proves nothing — read it back
+  // and confirm the stamp is actually in it. The diagnosis' second-order
+  // failure was exactly a status flip that answered success over unchanged
+  // frontmatter.
+  const alignmentLanding = measureDiskLanding(vaultRoot, fullPath);
+  try {
+    alignmentLanding.stamp_readback = readFileSync(fullPath, 'utf-8').includes(
+      `alignment_reviewed_at: ${reviewedAt}`,
+    );
+  } catch {
+    alignmentLanding.stamp_readback = false;
+  }
+  if (!alignmentLanding.on_disk || alignmentLanding.stamp_readback !== true) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'WRITE_NOT_ON_DISK',
+          message:
+            `The write reported success but ${specPath} does not carry alignment_reviewed_at: ${reviewedAt} on read-back. ` +
+            'Treat the checkpoint as NOT recorded.',
+          spec_path: specPath,
+          landed: alignmentLanding,
+        }, null, 2),
+      }],
+    };
+  }
+
+  const resolvedSpecId = frontmatter.id || specId;
+  const payload = {
+    ok: true,
+    spec_id: resolvedSpecId,
+    spec_path: specPath,
+    landed: alignmentLanding,
+    alignment_reviewed_at: reviewedAt,
+    child_count: childIds.length,
+    // What was actually WRITTEN to the spec, not what was passed in. The old
+    // `Boolean(args.override_reason)` reported `true` for a reason that stored
+    // nothing ([[HS-N71O-P3XQ-DIAG-six-new-qc-gates-fail-cold-verification]]).
+    overridden: storedOverride,
+    message: `Alignment checkpoint recorded for ${resolvedSpecId} (${childIds.length} ${childKindFor(grain)}${childIds.length === 1 ? '' : 's'}). The response includes the next on-deck brief inline.`,
+  };
+
+  if (typeof args.skipped_despite_findings === 'boolean') {
+    const stamp = stampSkippedDespiteFindingsOnBreakdownMarker({
+      vaultRoot,
+      epicId: resolvedSpecId,
+      skippedDespiteFindings: args.skipped_despite_findings,
+    });
+    if (stamp.error) {
+      // A FAILURE MUST NOT RIDE ALONG INSIDE A SUCCESS ([[HS-IOJW-5YDH-DIAG]]
+      // sweep). This used to set `skipped_despite_findings_error` and still return
+      // `ok: true` with no `isError`, so the caller saw a green tool call over a
+      // flag that was never stamped. The alignment checkpoint itself DID land (it
+      // was read back above), so nothing is re-done and nothing is lost — the
+      // payload below carries every recorded fact. What changes is that the caller
+      // can now tell a full success from a partial one.
+      markAlignmentPartial(payload, 'skipped_despite_findings', stamp);
+    } else {
+      payload.skipped_despite_findings = stamp.skipped_despite_findings;
+      payload.review_marker_path = stamp.review_marker_path;
+    }
+  }
+
+  // [[HS-TASK-286X]] — chain into the next on-deck brief so the agent does not
+  // need a manual /hs-next re-invoke. The just-stamped checkpoint clears the
+  // alignment gate for the same spec; the focus-pinned path picks up next
+  // from the children. Best-effort — chain errors do not corrupt the recorded
+  // checkpoint, the field is just omitted.
+  if (config) {
+    try {
+      const chained = resolveNextOnDeckPayload(vaultRoot, config, {
+        spec_id: resolvedSpecId,
+        roadmap_id: args.roadmap_id,
+      });
+      if (chained && chained.result) {
+        payload.next_on_deck = chained.result;
+      } else if (chained && chained.error) {
+        payload.next_on_deck_error = chained.error;
+      }
+    } catch (e) {
+      payload.next_on_deck_error = { error: 'CHAIN_FAILED', message: e.message };
+    }
+  }
+
+  return alignmentResult(payload);
+}
+
+/**
+ * Cloud-reliant sibling of `handleRecordAlignment` ([[HS-DJWP-MCPC-TASK]]
+ * "Spec load + alignment read-back" family, backing `heyspex_record_alignment`).
+ *
+ * `handleRecordAlignment` itself is left completely untouched — it is
+ * imported and called directly (synchronously, no `await`) by
+ * `alignment-gate-holes.test.mjs`, so it must keep returning a plain object,
+ * never a Promise. This wrapper is a NEW function used only by the live tool
+ * dispatch: it resolves the tier ONCE, then either calls the untouched disk
+ * path or `handleRecordAlignmentCloud` below. Any thrown error from the cloud
+ * branch (network failure, a non-404 non-ok console response) is the ONE
+ * decision point (`readViaSelector`) turning it into
+ * `CONSOLE_UNREACHABLE_CLOUD_MODE` — never a silent disk fallback.
+ */
+export async function handleRecordAlignmentViaTier(vaultRoot, config, args) {
+  const specId = args.spec_id;
+  if (!specId) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'MISSING_SPEC_ID' }) }],
+    };
+  }
+  const tier = await resolveReadTier();
+  const consoleUrl = effectiveConsoleUrl();
+  try {
+    return await readViaSelector({
+    allowDiskFallback: false,
+      tier,
+      diskRead: () => handleRecordAlignment(vaultRoot, config, args),
+      neonRead: () => handleRecordAlignmentCloud(vaultRoot, config, args, { consoleUrl }),
+      routeLabel: 'PUT /api/specs/[id]',
+      consoleUrl,
+    });
+  } catch (err) {
+    if (err instanceof ConsoleUnreachableCloudModeError) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: err.name, message: err.message }) }],
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Cloud-tier alignment-checkpoint stamp: `GET /api/specs/resolve` (id →
+ * relPath, mirrors `findSpecFile`) + `GET /api/specs/[id]` (load) + `PUT
+ * /api/specs/[id]` (write) + a second `GET /api/specs/[id]` (read-back
+ * verification — "report on the RESULT, not the request", same discipline
+ * the disk path follows). Never touches `readFileSync`/`writeFileSync`.
+ *
+ * `skipped_despite_findings` and the chained `next_on_deck` brief both stay
+ * best-effort / out of scope here: the marker file and the on-deck resolver
+ * are disk-based mechanisms this read-path task does not extend to cloud
+ * reliance — the chain is already wrapped in try/catch (degrades to
+ * `next_on_deck_error`), and the marker request is answered with an explicit
+ * "not supported in cloud reliance yet" rather than attempting a local write
+ * that would fail with no vault checkout.
+ */
+export async function handleRecordAlignmentCloud(vaultRoot, config, args, { consoleUrl }) {
+  const specId = args.spec_id;
+
+  let storedOverride = false;
+  let overrideReasonTrimmed;
+  if (args.override_reason !== undefined && args.override_reason !== null) {
+    overrideReasonTrimmed = String(args.override_reason).trim();
+    if (overrideReasonTrimmed.length < ALIGNMENT_OVERRIDE_REASON_MIN_LENGTH) {
+      return {
+        isError: true,
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: 'ALIGNMENT_OVERRIDE_REASON_TOO_THIN',
+            message:
+              `override_reason is ${overrideReasonTrimmed.length} characters after trimming${overrideReasonTrimmed.length === 0 ? ' (it was empty or whitespace only)' : ''} — it must be at least ${ALIGNMENT_OVERRIDE_REASON_MIN_LENGTH} and say WHY the drift finding is a false positive or an intentional supersession. It is stored on the spec as the audit record of that call, so ${overrideReasonTrimmed.length === 0 ? 'blank space' : `"${overrideReasonTrimmed}"`} tells the next reader nothing. Omit override_reason entirely if the review was clean.`,
+            override_reason_length: overrideReasonTrimmed.length,
+            minimum: ALIGNMENT_OVERRIDE_REASON_MIN_LENGTH,
+          }),
+        }],
+      };
+    }
+    storedOverride = true;
+  }
+
+  const relPath = await resolveSpecIdViaTier(vaultRoot, specId, { tier: 'neon', consoleUrl });
+  if (!relPath) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'SPEC_NOT_FOUND', message: `Spec ${specId} not found` }) }],
+    };
+  }
+
+  const getRes = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}`);
+  if (!getRes.ok) {
+    throw consoleReadErrorFrom(getRes, `GET /api/specs/${specId} returned ${getRes.status}: ${getRes.error || JSON.stringify(getRes.body ?? {})}`, null);
+  }
+  const spec = getRes.body?.spec;
+  if (!spec) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'SPEC_NOT_FOUND', message: `Spec ${specId} not found` }) }],
+    };
+  }
+
+  const frontmatter = spec.frontmatter || {};
+  const grain = frontmatter.type === 'milestone' ? 'milestone' : 'epic';
+  const childIds = getChildRefs(frontmatter, grain);
+  const reviewedAt = new Date().toISOString();
+
+  const updatedFrontmatter = { ...frontmatter, alignment_reviewed_at: reviewedAt };
+  if (args.summary) updatedFrontmatter.alignment_summary = String(args.summary);
+  if (storedOverride) updatedFrontmatter.alignment_override = overrideReasonTrimmed;
+
+  const putRes = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}`, {
+    method: 'PUT',
+    body: { frontmatter: updatedFrontmatter, body: spec.body ?? '' },
+  });
+  if (!putRes.ok) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'WRITE_FAILED',
+          message: consoleErrorMessage(putRes, `PUT /api/specs/${specId} returned ${putRes.status}`),
+        }),
+      }],
+    };
+  }
+
+  // Re-read for the stamp, independent of the PUT response.
+  const verifyRes = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}`);
+  const stampReadback =
+    verifyRes.ok && verifyRes.body?.spec?.frontmatter?.alignment_reviewed_at === reviewedAt;
+  const alignmentLanding = {
+    tier: 'neon',
+    reported_by: 'measured',
+    abs_path: null,
+    rel_path: relPath,
+    on_disk: null, // not applicable in cloud reliance — see `stamp_readback` instead.
+    bytes: null,
+    stamp_readback: stampReadback,
+  };
+  if (!stampReadback) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'WRITE_NOT_ON_DISK',
+          message:
+            `The write reported success but ${specId} does not carry alignment_reviewed_at: ${reviewedAt} on read-back. ` +
+            'Treat the checkpoint as NOT recorded.',
+          spec_path: relPath,
+          landed: alignmentLanding,
+        }, null, 2),
+      }],
+    };
+  }
+
+  const resolvedSpecId = frontmatter.id || specId;
+  const payload = {
+    ok: true,
+    spec_id: resolvedSpecId,
+    spec_path: relPath,
+    landed: alignmentLanding,
+    alignment_reviewed_at: reviewedAt,
+    child_count: childIds.length,
+    overridden: storedOverride,
+    message: `Alignment checkpoint recorded for ${resolvedSpecId} (${childIds.length} ${childKindFor(grain)}${childIds.length === 1 ? '' : 's'}). The response includes the next on-deck brief inline.`,
+  };
+
+  if (typeof args.skipped_despite_findings === 'boolean') {
+    // Same rule as the disk tier above, and here the failure is UNCONDITIONAL:
+    // cloud reliance cannot stamp the local breakdown-review marker at all, so
+    // every caller that passes this flag was being told, in a green response,
+    // that it had been recorded.
+    markAlignmentPartial(payload, 'skipped_despite_findings', {
+      error: 'UNSUPPORTED_IN_CLOUD_RELIANCE',
+      message:
+        'skipped_despite_findings stamping writes a local breakdown-review marker file and is not yet wired for cloud reliance.',
+    });
+  }
+
+  if (config) {
+    try {
+      const chained = resolveNextOnDeckPayload(vaultRoot, config, {
+        spec_id: resolvedSpecId,
+        roadmap_id: args.roadmap_id,
+      });
+      if (chained && chained.result) {
+        payload.next_on_deck = chained.result;
+      } else if (chained && chained.error) {
+        payload.next_on_deck_error = chained.error;
+      }
+    } catch (e) {
+      payload.next_on_deck_error = { error: 'CHAIN_FAILED', message: e.message };
+    }
+  }
+
+  return alignmentResult(payload);
+}
+
+// ── claim-bound worktree binding ────────────────────────────────────────────
+// [[HS-QDQA]] (epic [[HS-03DO]] "Claim-bound worktree isolation for parallel
+// agent sessions"). A session worktree carries `<root>/.hsewt-owner.json`
+// (`kind: "session"`) and is allocated / released / rebound by
+// dev-factory/lib/worktree-allocator.mjs. The claim lifecycle is where that
+// marker's own lifecycle has to be kept honest:
+//
+//   release → mark the worktree RELEASED (never delete — release only makes it
+//             eligible for a later `reap`, which still refuses a dirty tree).
+//   claim   → a BARE spawn keys its marker on `launch-<id>` because no spec was
+//             claimed yet; the first real claim REBINDS it to the claimed id
+//             (and renames the branch), so the worktree the agent is sitting in
+//             is named after the work it is actually doing.
+//
+// Both are BEST-EFFORT by design: the console round trip is the authoritative
+// part of a claim/release, and a missing/broken dev-factory checkout (the MCP
+// server also runs against sibling repos that have no dev-factory at all) must
+// never turn a successful release into a failure. Every outcome — including the
+// failure — is reported under `worktree` in the tool result rather than thrown.
+
+/** Real allocator, loaded lazily so a claim never pays for dev-factory. */
+const loadWorktreeAllocator = () => import('../../dev-factory/lib/worktree-allocator.mjs');
+
+/**
+ * Resolve the injectable allocator. `deps.worktree` may be the module object
+ * itself (a test stub) or a factory returning one; absent, the real module is
+ * dynamically imported. Kept as ONE resolver so both handlers below inject the
+ * same way.
+ */
+async function resolveWorktreeAllocator(deps = {}) {
+  const injected = deps.worktree;
+  if (!injected) return loadWorktreeAllocator();
+  return typeof injected === 'function' ? injected() : injected;
+}
+
+/** Default owner-marker basename, mirrored only as a fallback for a stub that
+ *  does not re-export the allocator's own OWNER_FILE. */
+const DEFAULT_OWNER_FILE = '.hsewt-owner.json';
+
+/**
+ * Best-effort "this claim is over, the worktree may be reclaimed" stamp.
+ * @returns {Promise<{found: boolean, alreadyReleased: boolean} | {error: string}>}
+ */
+export async function markWorktreeReleased(specId, deps = {}) {
+  try {
+    const wt = await resolveWorktreeAllocator(deps);
+    const ctx = wt.makeCtx();
+    const result = wt.markReleased(ctx, { specId });
+    return {
+      found: Boolean(result?.found),
+      alreadyReleased: Boolean(result?.alreadyReleased),
+    };
+  } catch (e) {
+    return { error: e?.message ?? String(e) };
+  }
+}
+
+/**
+ * Read the owner marker of the worktree this MCP call is running inside, if
+ * any. `null` whenever there is no `HEYSPEX_WORKTREE_PATH`, no marker file, or
+ * the marker is unreadable — every one of which means "nothing to rebind".
+ */
+function readCurrentWorktreeMarker(deps = {}, ownerFile = DEFAULT_OWNER_FILE) {
+  const env = deps.env ?? process.env;
+  const root = typeof env.HEYSPEX_WORKTREE_PATH === 'string' ? env.HEYSPEX_WORKTREE_PATH.trim() : '';
+  if (!root) return null;
+  const read = deps.readFile ?? ((p) => readFileSync(p, 'utf-8'));
+  try {
+    const parsed = JSON.parse(read(join(root, ownerFile)));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Re-point a BARE-spawn worktree (`launch-<id>`) at the spec that was just
+ * claimed. Returns `null` when this session is not in a worktree, or its marker
+ * is already bound to a real spec — so the caller only ever reports a `worktree`
+ * field when something actually applied.
+ *
+ * @returns {Promise<{rebound: boolean, branch: string|null} | {error: string} | null>}
+ */
+export async function rebindLaunchWorktreeForClaim(specId, deps = {}) {
+  const env = deps.env ?? process.env;
+  const root = typeof env.HEYSPEX_WORKTREE_PATH === 'string' ? env.HEYSPEX_WORKTREE_PATH.trim() : '';
+  if (!root) return null; // not a spawned worktree session — never touch the allocator
+  try {
+    const wt = await resolveWorktreeAllocator(deps);
+    const marker = readCurrentWorktreeMarker(deps, wt.OWNER_FILE ?? DEFAULT_OWNER_FILE);
+    const from = typeof marker?.specId === 'string' ? marker.specId : '';
+    // Only a BARE spawn is rebound. A marker already bound to a real spec id is
+    // somebody's live claim, and renaming its branch out from under it is the
+    // class of breakage this epic exists to avoid.
+    if (!from.startsWith('launch-')) return null;
+    if (from === specId) return null;
+    const ctx = wt.makeCtx();
+    const result = wt.rebind(ctx, { fromSpecId: from, toSpecId: specId });
+    return { rebound: Boolean(result?.found), branch: result?.branch ?? null };
+  } catch (e) {
+    return { error: e?.message ?? String(e) };
+  }
+}
+
+export async function handleClaimSpec(args = {}, deps = {}) {
+  if (!args.spec_id || typeof args.spec_id !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'spec_id is required' }) }],
+    };
+  }
+  // Resolve the id ONCE ([[HS-05ZW-XHR4-DIAG]]): a bare era-3 file key is what
+  // `heyspex_file_spec` hands back, and in cloud reliance only the console can
+  // prove it names one spec — so the guard resolves it to the full basename
+  // instead of refusing it.
+  const claimResolved = await resolveSpecIdForMutation(args.spec_id);
+  if (claimResolved.response) return claimResolved.response;
+  const claimSpecId = claimResolved.specId;
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const agentProfile =
+    typeof args.agent_profile === 'string' && args.agent_profile.trim()
+      ? args.agent_profile.trim()
+      : undefined;
+  const post = deps.postClaimEndpoint ?? postClaimEndpoint;
+  const result = await post('POST', claimSpecId, {
+    agent: identity.agent,
+    sessionId: identity.sessionId,
+    ...(agentProfile ? { agent_profile: agentProfile } : {}),
+  });
+  if (!result.ok) {
+    const payload = await enrichConsoleFailurePayloadAsync(result, {
+      error: consoleErrorCode(result, 'CLAIM_FAILED'),
+      message: consoleErrorMessage(result, `Claim endpoint returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: { spec_id: claimSpecId, agent: identity.agent, session_id: identity.sessionId },
+    });
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  const consoleBody = result.body && typeof result.body === 'object' ? result.body : {};
+  const stompWarnings = Array.isArray(consoleBody.stomp_warnings) ? consoleBody.stomp_warnings : [];
+  const identityNudges = Array.isArray(consoleBody.identity_nudges) ? consoleBody.identity_nudges : [];
+  // The claim LANDED — everything below is reporting, and must not be able to
+  // unland it ([[HS-QDQA]]).
+  const worktree = await rebindLaunchWorktreeForClaim(claimSpecId, deps);
+  const payload = {
+    spec_id: claimSpecId,
+    agent: identity.agent,
+    session_id: identity.sessionId,
+    ...(agentProfile ? { agent_profile: agentProfile } : {}),
+    console_url: result.url,
+    console_response: result.body,
+    ...(stompWarnings.length ? { stomp_warnings: stompWarnings } : {}),
+    ...(identityNudges.length ? { identity_nudges: identityNudges } : {}),
+    ...(worktree ? { worktree } : {}),
+  };
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+  };
+}
+
+// Closed work-stage vocabulary. SSOT is spex-console/src/lib/work-stages.ts +
+// the execute procedure; this list is the agent-facing mirror. The console route
+// (PATCH /api/specs/:id/claim/status) is the authoritative validator, so a drift
+// here is caught there rather than silently accepted.
+export const WORK_STAGES = ['Grounding', 'Breaking down', 'Drafting', 'Validating', 'Testing', 'Reviewing'];
+
+/**
+ * Build the PATCH /api/specs/:id/claim/status request body from
+ * heyspex_report_progress args + the resolved caller identity. Pure and
+ * exported so the sessionId-forwarding contract is unit-testable without a
+ * live console — [[HS-0BQ8-3TY6-TASK-send-the-agent-s-session-with-every]].
+ * Every sibling handler in this file already sends `identity.sessionId` on
+ * its PATCH/POST body; this brings handleReportProgress in line so the
+ * console's claim-fence guard (which only engages when a session rides the
+ * request) actually engages on the one path every agent uses.
+ */
+export function buildReportProgressBody(args = {}, acProgress, identity) {
+  const body = { status: 'working', currentStage: args.current_stage, sessionId: identity.sessionId };
+  if (acProgress !== undefined) body.acProgress = acProgress;
+  return body;
+}
+
+export async function handleReportProgress(args = {}) {
+  if (!args.spec_id || typeof args.spec_id !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'spec_id is required' }) }],
+    };
+  }
+  if (typeof args.current_stage !== 'string' || !WORK_STAGES.includes(args.current_stage)) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            error: 'INVALID_ARGS',
+            message: `current_stage must be one of: ${WORK_STAGES.join(', ')}`,
+          }),
+        },
+      ],
+    };
+  }
+  let acProgress;
+  if (args.ac_progress !== undefined && args.ac_progress !== null) {
+    if (typeof args.ac_progress !== 'number' || !Number.isInteger(args.ac_progress) || args.ac_progress < 0) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ error: 'INVALID_ARGS', message: 'ac_progress must be a non-negative integer' }),
+          },
+        ],
+      };
+    }
+    acProgress = args.ac_progress;
+  }
+
+  // Same guard as claim/submit/defer ([[HS-05ZW-XHR4-DIAG]] surface sweep): a
+  // progress PATCH is a claim-scoped mutation, so an id that names a whole
+  // family must not be forwarded to pick an arbitrary member.
+  const progressResolved = await resolveSpecIdForMutation(args.spec_id);
+  if (progressResolved.response) return progressResolved.response;
+  const progressSpecId = progressResolved.specId;
+
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const body = buildReportProgressBody(args, acProgress, identity);
+
+  const result = await consoleFetch(
+    `/api/specs/${encodeURIComponent(progressSpecId)}/claim/status`,
+    { method: 'PATCH', body },
+  );
+  if (!result.ok) {
+    // Append-only progress is safe to queue on an outage (degrade, don't die).
+    const deferred = await deferControlWrite(result, {
+      route: `/api/specs/${encodeURIComponent(progressSpecId)}/claim/status`,
+      method: 'PATCH',
+      request_body: body,
+      spec_id: progressSpecId,
+      acting_agent: identity.agent,
+      session_id: identity.sessionId,
+    }, { isCloud: isCloudReliant });
+    if (deferred) return deferred;
+    const payload = {
+      error: consoleErrorCode(result, 'REPORT_PROGRESS_FAILED'),
+      message: consoleErrorMessage(result, `Claim status endpoint returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: { spec_id: progressSpecId, current_stage: args.current_stage, ac_progress: acProgress },
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(
+          { spec_id: progressSpecId, current_stage: args.current_stage, ac_progress: acProgress, console_response: result.body },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+export async function handleSubmitForReview(vaultRoot, args = {}) {
+  const submitResolved = await resolveSpecIdForMutation(args.spec_id);
+  if (submitResolved.response) return submitResolved.response;
+  const result = await executeSubmitForReview({
+    vaultRoot,
+    consoleFetch,
+    postClaimEndpoint,
+    args: { ...args, spec_id: submitResolved.specId },
+  });
+  if (result.error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  }
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+export async function handleReleaseSpec(args = {}, deps = {}) {
+  if (!args.spec_id || typeof args.spec_id !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'spec_id is required' }) }],
+    };
+  }
+  // Same guard as claim ([[HS-05ZW-XHR4-DIAG]] surface sweep): DELETE-ing the
+  // claim of an arbitrary family member is the same class of harm as claiming
+  // one, so release goes through the shared resolver too.
+  const releaseResolved = await resolveSpecIdForMutation(args.spec_id);
+  if (releaseResolved.response) return releaseResolved.response;
+  const releaseSpecId = releaseResolved.specId;
+  const post = deps.postClaimEndpoint ?? postClaimEndpoint;
+  const result = await post('DELETE', releaseSpecId);
+  if (!result.ok) {
+    const payload = {
+      error: consoleErrorCode(result, 'RELEASE_FAILED'),
+      message: consoleErrorMessage(result, `Release endpoint returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: { spec_id: releaseSpecId },
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  // The console released the claim. Now (and ONLY now) mark the session
+  // worktree eligible for reaping — best-effort, never fatal ([[HS-QDQA]]).
+  const worktree = await markWorktreeReleased(releaseSpecId, deps);
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(
+        { spec_id: releaseSpecId, released: true, console_response: result.body, worktree },
+        null,
+        2,
+      ),
+    }],
+  };
+}
+
+/**
+ * Record the machine-readable WIP ledger for an epic at session close
+ * ([[HS-EPIC-FCSM]] forensic-reconstruction incident). Thin forwarder to
+ * console `POST /api/specs/:id/wip`, which captures the touched/untracked file
+ * lists from `git status` server-side (code-first — not narrated) and merges
+ * the agent-supplied semantic fields. The on-deck brief surfaces the entry so
+ * the next agent reads state instead of reconstructing it.
+ */
+/** Every argument heyspex_record_wip accepts. Anything else is refused by name. */
+export const RECORD_WIP_ACCEPTED_ARGS = [
+  'spec_id',
+  'specs_filed',
+  'remaining',
+  'verified',
+  'notes',
+  'agent',
+  'session_id',
+];
+
+/**
+ * Arguments an agent plausibly reaches for that this tool has never had, and
+ * where the content actually belongs. Named in the refusal so the error tells
+ * the caller what to do instead of just saying no.
+ */
+export const RECORD_WIP_ARG_REDIRECTS = {
+  summary: 'this tool has no "summary" field — put the hand-off prose in "notes"',
+  handoff: 'no such field — put the hand-off prose in "notes"',
+  note: 'did you mean "notes"?',
+  current_stage: 'belongs to heyspex_report_progress (currentStage), not the WIP ledger',
+  currentStage: 'belongs to heyspex_report_progress (currentStage), not the WIP ledger',
+  ac_progress: 'belongs to heyspex_report_progress (acProgress), not the WIP ledger',
+  acProgress: 'belongs to heyspex_report_progress (acProgress), not the WIP ledger',
+  files_touched: 'captured server-side from git status — do not pass it',
+  untracked_artifacts: 'captured server-side from git status — do not pass it',
+  filesTouched: 'captured server-side from git status — do not pass it',
+  untrackedArtifacts: 'captured server-side from git status — do not pass it',
+};
+
+/**
+ * Mirror of `MAX_NOTES_CHARS` in `spex-console/src/lib/wip-state.ts` — refused
+ * here so an over-long hand-off fails before the round trip, with the same
+ * number in the message. Keep the two in sync.
+ */
+export const RECORD_WIP_MAX_NOTES_CHARS = 4000;
+
+/**
+ * Pure verdict on a `heyspex_record_wip` argument bag: either the console body
+ * to POST, or the refusal to hand back ([[HS-IRX0-5KFT-DIAG]] AC2).
+ *
+ * Store it or refuse it. The old code built the body from a fixed whitelist, so
+ * an argument the store does not keep (four hand-offs were written into
+ * `summary`) vanished with no signal while the call returned success. Anything
+ * unlisted, or listed with the wrong type, is now a named refusal — no partial
+ * write, no silent drop.
+ *
+ * Identity (agent / sessionId) is stamped by the caller, so this stays pure.
+ */
+export function recordWipArgsVerdict(args = {}) {
+  if (!args.spec_id || typeof args.spec_id !== 'string') {
+    return { ok: false, error: { error: 'INVALID_ARGS', message: 'spec_id is required' } };
+  }
+
+  const unknown = Object.keys(args).filter((k) => !RECORD_WIP_ACCEPTED_ARGS.includes(k));
+  if (unknown.length > 0) {
+    const detail = unknown
+      .map((k) => (RECORD_WIP_ARG_REDIRECTS[k] ? `${k} (${RECORD_WIP_ARG_REDIRECTS[k]})` : k))
+      .join(', ');
+    return {
+      ok: false,
+      error: {
+        error: 'UNKNOWN_FIELD',
+        message: `heyspex_record_wip cannot store: ${detail}. NOTHING WAS WRITTEN — re-send using only the accepted arguments.`,
+        field: unknown[0],
+        unknown_fields: unknown,
+        accepted_fields: RECORD_WIP_ACCEPTED_ARGS,
+        attempted: { spec_id: args.spec_id },
+      },
+    };
+  }
+
+  const body = {};
+  const listArgs = { specs_filed: 'specsFiled', remaining: 'remaining', verified: 'verified' };
+  for (const [argName, bodyName] of Object.entries(listArgs)) {
+    if (args[argName] === undefined) continue;
+    if (!Array.isArray(args[argName]) || args[argName].some((v) => typeof v !== 'string')) {
+      return {
+        ok: false,
+        error: {
+          error: 'INVALID_FIELD',
+          message: `"${argName}" must be an array of strings. NOTHING WAS WRITTEN.`,
+          field: argName,
+          accepted_fields: RECORD_WIP_ACCEPTED_ARGS,
+        },
+      };
+    }
+    body[bodyName] = args[argName];
+  }
+  if (args.notes !== undefined) {
+    if (typeof args.notes !== 'string') {
+      return {
+        ok: false,
+        error: {
+          error: 'INVALID_FIELD',
+          message: '"notes" must be a string. NOTHING WAS WRITTEN.',
+          field: 'notes',
+          accepted_fields: RECORD_WIP_ACCEPTED_ARGS,
+        },
+      };
+    }
+    if (args.notes.length > RECORD_WIP_MAX_NOTES_CHARS) {
+      return {
+        ok: false,
+        error: {
+          error: 'NOTES_TOO_LONG',
+          message: `"notes" is ${args.notes.length} characters, over the ${RECORD_WIP_MAX_NOTES_CHARS} the ledger stores. NOTHING WAS WRITTEN — shorten it, or move the long-form detail into the spec body and leave a pointer here.`,
+          field: 'notes',
+          accepted_fields: RECORD_WIP_ACCEPTED_ARGS,
+        },
+      };
+    }
+    body.notes = args.notes;
+  }
+
+  return { ok: true, body };
+}
+
+/**
+ * Record the WIP hand-off ledger — POST /api/specs/:id/wip. Refuses what it
+ * cannot store, and surfaces the console's measured `stored` receipt on success
+ * ([[HS-IRX0-5KFT-DIAG]]).
+ */
+export async function handleRecordWip(args = {}) {
+  const verdict = recordWipArgsVerdict(args);
+  if (!verdict.ok) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(verdict.error, null, 2) }],
+    };
+  }
+
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const body = { ...verdict.body, agent: identity.agent, sessionId: identity.sessionId };
+
+  const result = await consoleFetch(
+    `/api/specs/${encodeURIComponent(args.spec_id)}/wip`,
+    { method: 'POST', body },
+  );
+  if (!result.ok) {
+    const deferred = await deferControlWrite(result, {
+      route: `/api/specs/${encodeURIComponent(args.spec_id)}/wip`,
+      method: 'POST',
+      request_body: body,
+      spec_id: args.spec_id,
+      acting_agent: identity.agent,
+      session_id: identity.sessionId,
+    }, { isCloud: isCloudReliant });
+    if (deferred) return deferred;
+    const payload = {
+      error: consoleErrorCode(result, 'WIP_FAILED'),
+      message: consoleErrorMessage(result, `WIP endpoint returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: { spec_id: args.spec_id },
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  // The console's `stored` block is MEASURED from a re-read of the ledger — lift
+  // it to the top level so the receipt is the first thing the agent sees.
+  const stored = result.body && typeof result.body === 'object' ? result.body.stored : undefined;
+  const warnings = result.body && typeof result.body === 'object' ? result.body.warnings : undefined;
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        spec_id: args.spec_id,
+        stored,
+        ...(Array.isArray(warnings) && warnings.length ? { warnings } : {}),
+        console_response: result.body,
+      }, null, 2),
+    }],
+  };
+}
+
+/**
+ * Delegation defer — POST /api/specs/:id/defer ([[HS-TASK-1U0Z]]).
+ * Files split child + handoff envelope; console orchestrates pin / claim release / WIP.
+ */
+export async function handleDeferSpec(args = {}) {
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  let specId = typeof args.spec_id === 'string' && args.spec_id.trim() ? args.spec_id.trim() : null;
+  if (!specId) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'INVALID_ARGS',
+          message: 'spec_id is required — pass the claimed parent HS-TASK-* id',
+        }),
+      }],
+    };
+  }
+  const deferResolved = await resolveSpecIdForMutation(specId);
+  if (deferResolved.response) return deferResolved.response;
+  specId = deferResolved.specId;
+
+  const body = {
+    reason: args.reason,
+    summary_done: args.summary_done,
+    remaining: args.remaining,
+    success_criteria: args.success_criteria,
+    agent: identity.agent,
+    session_id: identity.sessionId,
+    ...(args.parent_status ? { parent_status: args.parent_status } : {}),
+    ...(args.effort !== undefined ? { effort: args.effort } : {}),
+    ...(typeof args.child_name === 'string' ? { child_name: args.child_name } : {}),
+    ...(typeof args.handoff_id === 'string' && args.handoff_id.trim()
+      ? { handoff_id: args.handoff_id.trim() }
+      : {}),
+    ...(args.pin_on_deck === false ? { pin_on_deck: false } : {}),
+    ...(args.release_claim === false ? { release_claim: false } : {}),
+    ...(args.record_wip === false ? { record_wip: false } : {}),
+  };
+
+  const result = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}/defer`, {
+    method: 'POST',
+    body,
+  });
+  if (!result.ok) {
+    const payload = {
+      error: consoleErrorCode(result, 'DEFER_FAILED'),
+      message: consoleErrorMessage(result, `Defer endpoint returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: { spec_id: specId },
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({ spec_id: specId, ...result.body }, null, 2),
+    }],
+  };
+}
+
+/**
+ * Build the POST /api/control/active-claims/acquire request body from
+ * heyspex_claim_acquire args + the resolved caller identity. Pure and exported
+ * so the field-forwarding contract (in particular wait_if_held) is
+ * unit-testable without a live console — [[HS-SESO]] AC3.
+ */
+export function buildClaimAcquireBody(args = {}, identity) {
+  return {
+    spec_id: args.spec_id,
+    agent: identity.agent,
+    session_id: identity.sessionId,
+    ...(args.ttl_ms !== undefined ? { ttl_ms: args.ttl_ms } : {}),
+    ...(args.wait_if_held !== undefined ? { wait_if_held: args.wait_if_held } : {}),
+  };
+}
+
+/**
+ * Atomically acquire a claim — [[HS-EPIC-NCPS]] active_claims /
+ * [[HS-EPIC-CLMW]] `hs claim acquire`. POST /api/control/active-claims/acquire.
+ * A 409 is a legitimate "already claimed" outcome (not a transport error): it is
+ * surfaced as a normal result with acquired:false + the existing claimant.
+ */
+export async function handleClaimAcquire(args = {}) {
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const result = await consoleFetch('/api/control/active-claims/acquire', {
+    method: 'POST',
+    body: buildClaimAcquireBody(args, identity),
+  });
+  if (result.ok) return controlOk(result.body);
+  if (result.status === 409) return controlOk(result.body); // already_claimed + existing
+  return controlError(result, 'CLAIM_ACQUIRE_FAILED', { spec_id: args.spec_id });
+}
+
+/**
+ * Release a claim — [[HS-EPIC-NCPS]] active_claims / [[HS-EPIC-CLMW]]
+ * `hs claim release`. DELETE /api/control/active-claims/:spec_id. A 404 is a
+ * legitimate "no active claim" outcome, surfaced as released:false.
+ */
+export async function handleClaimRelease(args = {}) {
+  const specId = typeof args.spec_id === 'string' ? args.spec_id.trim() : '';
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const path =
+    `/api/control/active-claims/${encodeURIComponent(specId)}` +
+    `?agent=${encodeURIComponent(identity.agent)}`;
+  const result = await consoleFetch(path, { method: 'DELETE' });
+  if (result.ok) return controlOk(result.body);
+  if (result.status === 404) return controlOk(result.body); // released:false + not_found
+  return controlError(result, 'CLAIM_RELEASE_FAILED', { spec_id: args.spec_id });
+}
+
+/**
+ * List all active claims — [[HS-EPIC-NCPS]] active_claims / [[HS-EPIC-CLMW]]
+ * `hs claim list`. GET /api/control/active-claims → { claims: [] }.
+ */
+export async function handleClaimList(_args = {}) {
+  const result = await consoleFetch('/api/control/active-claims');
+  if (!result.ok) return controlError(result, 'CLAIM_LIST_FAILED');
+  return controlOk(result.body);
+}
+
+/**
+ * [[HS-Y00G-EPIC]] — Claim a file path for exclusive editing.
+ * POST /api/file-claims/acquire. Default TTL 5 minutes.
+ */
+export async function handleClaimFile(args = {}) {
+  if (!args.file_path || typeof args.file_path !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'file_path is required' }) }],
+    };
+  }
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const body = {
+    file_path: args.file_path,
+    agent: identity.agent,
+    session_id: identity.sessionId,
+  };
+  if (args.ttl_ms !== undefined) body.ttl_ms = args.ttl_ms;
+  if (args.working_spec_id && typeof args.working_spec_id === 'string') {
+    body.working_spec_id = args.working_spec_id;
+  }
+  const result = await consoleFetch('/api/file-claims/acquire', { method: 'POST', body });
+  if (result.ok) return controlOk(result.body);
+  if (result.status === 409) return controlOk(result.body); // already_claimed + existing
+  return controlError(result, 'FILE_CLAIM_FAILED', { file_path: args.file_path });
+}
+
+/**
+ * [[HS-Y00G-EPIC]] — Release a file claim.
+ * DELETE /api/file-claims/release.
+ */
+export async function handleReleaseFileClaim(args = {}) {
+  if (!args.file_path || typeof args.file_path !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'file_path is required' }) }],
+    };
+  }
+  const result = await consoleFetch('/api/file-claims/release', {
+    method: 'DELETE',
+    body: { file_path: args.file_path },
+  });
+  if (result.ok) return controlOk(result.body);
+  if (result.status === 404) return controlOk(result.body); // released:false + not_found
+  return controlError(result, 'FILE_CLAIM_RELEASE_FAILED', { file_path: args.file_path });
+}