heyspex 0.1.0

package/vendor/heyspex-mcp/deferred-reclaim.mjs

@@ -0,0 +1,284 @@
+/**
+ * Deferred split-child reclaim + Resolution DLQ ([[HS-TASK-6OU5-deferred-work-reclaim-and-resolution-dlq]]).
+ * Consumes lease/heartbeat reclaim from [[HS-EPIC-96YK-claim-leases-heartbeats-and-passive-nudg]] —
+ * does not implement the sweep itself.
+ */
+
+import { readFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { allocateRandomVaultId } from '../../scripts/vault-id-lib.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import { mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
+import {
+  isoNow,
+  deriveSlug,
+  getFrontmatterBlock,
+  getScalarField,
+  setScalarField,
+  bumpUpdated,
+  appendChangeLogRow,
+  commitWrites,
+} from './promotion-helpers.mjs';
+import { extractHandoffEnvelopeYaml } from '../../spex-console/src/lib/indexer/handoff-envelope.mjs';
+import { buildDiagnoseSkeletonSections } from './diagnose-skeleton.mjs';
+
+/** Default cap when frontmatter omits `attempt_count` ([[HS-TASK-6OU5]]). */
+export const DEFAULT_DEFER_RECLAIM_ATTEMPT_CAP = 3;
+
+function collectOccupiedDiagnoseIds(vaultRoot) {
+  const occupied = new Set();
+  const dir = join(vaultRoot, 'specs', 'diagnoses');
+  if (!existsSync(dir)) return occupied;
+  for (const file of readdirSync(dir)) {
+    // Key the occupied set on the canonical family-first id (dual-read on both
+    // the basename and the frontmatter id) so suffix-collision detection matches
+    // what allocateRandomVaultId generates/compares ([[HS-EPIC-DLE3]]).
+    const fromName = parseSpecId(file.replace(/\.md$/i, ''));
+    if (fromName && fromName.typeLabel === 'DIAG') {
+      occupied.add(`HS-${fromName.familyKey}-DIAG`);
+    }
+    try {
+      const raw = readFileSync(join(dir, file), 'utf8');
+      const idMatch = raw.match(/^id:\s*(\S+)/m);
+      if (idMatch) {
+        const fromId = parseSpecId(idMatch[1].replace(/^['"]|['"]$/g, ''));
+        if (fromId && fromId.typeLabel === 'DIAG') {
+          occupied.add(`HS-${fromId.familyKey}-DIAG`);
+        }
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  return occupied;
+}
+
+export function readAttemptCount(fmBlock) {
+  const raw = getScalarField(fmBlock, 'attempt_count');
+  if (raw == null || raw === '') return 0;
+  const n = Number.parseInt(String(raw), 10);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+export function isDeferredSplitTaskRaw(raw) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) return false;
+  const splitOf = getScalarField(fm.block, 'split_of');
+  const splitIndex = getScalarField(fm.block, 'split_index');
+  return Boolean(splitOf && splitIndex);
+}
+
+function handoffEnvelopeSectionFromBody(body) {
+  const extracted = extractHandoffEnvelopeYaml(body);
+  if (!extracted || 'missingFence' in extracted) return '';
+  return `## Handoff envelope
+
+\`\`\`yaml
+${extracted.yaml.trimEnd()}
+\`\`\``;
+}
+
+function buildDlqDiagnoseContent({
+  diagnoseId,
+  fileKey,
+  familyKey,
+  taskBasename,
+  taskName,
+  attemptCount,
+  reclaimReason,
+  handoffSection,
+  now,
+}) {
+  const slugPart = deriveSlug(`Deferred work DLQ — ${taskName}`);
+  const today = now.slice(0, 10);
+  const fm = `---
+id: ${diagnoseId}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(`Deferred work DLQ — ${taskName}`)}
+type: diagnose
+status: open
+owner: pwher
+severity: warning
+summary: |-
+  Deferred split child [[${taskBasename}]] exceeded the reclaim attempt cap (${attemptCount}) after repeated lease/heartbeat expiry.
+  Routed to Resolution for human triage; verify partial work on disk before continuing.
+tags:
+  - delegation
+  - dlq
+related:
+  - '[[${taskBasename}]]'
+created: '${now}'
+updated: '${now}'
+---
+`;
+
+  const body = `## Symptom
+
+Deferred split child [[${taskBasename}]] was abandoned ${attemptCount} time(s). The last reclaim reason was \`${reclaimReason}\`.
+
+## Reproduction
+
+1. Open [[${taskBasename}]] and read the handoff envelope below.
+2. Compare \`summary_done\` / git diff against what remains in \`remaining\`.
+3. Decide whether to re-open the task, split again, or close as wont-fix.
+
+${handoffSection || '_(No handoff envelope block found on the deferred task.)_'}
+
+${buildDiagnoseSkeletonSections({
+  'Root cause': '_DLQ hint: likely repeated agent timeout / context loss on deferred pickup._',
+  Fix: '_DLQ hint: resume from verified partial state, or re-defer with a fresh handoff_id._',
+})}
+
+## Change log
+
+| Date | Author | Change |
+|---|---|---|
+| ${today} | deferred-reclaim | Auto-filed from [[${taskBasename}]] after attempt_count ≥ cap. |
+`;
+
+  // Era-3 file-key-first basename: `HS-<fileKey>-<familyKey>-DIAG-<slug>`.
+  return { content: fm + body, basename: `${diagnoseId}-${familyKey}-DIAG-${slugPart}` };
+}
+
+function bumpAttemptCountInContent(raw, { now, author, reclaimReason }) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) return { changed: false, content: raw, attemptCount: 0 };
+  const prev = readAttemptCount(fm.block);
+  const next = prev + 1;
+  let block = setScalarField(fm.block, 'attempt_count', String(next));
+  block = bumpUpdated(block, now);
+  let body = appendChangeLogRow(
+    fm.body,
+    now.slice(0, 10),
+    author,
+    `Reclaim attempt ${next} (${reclaimReason})`,
+  );
+  return {
+    changed: true,
+    content: `${fm.open}${block}${fm.close}${body}`,
+    attemptCount: next,
+  };
+}
+
+function cancelDeferredTaskContent(raw, diagnoseBasename, now, author) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) return { changed: false, content: raw };
+  let block = setScalarField(fm.block, 'status', 'cancelled');
+  block = setScalarField(block, 'close_reason', 'duplicate');
+  block = bumpUpdated(block, now);
+  let body = appendChangeLogRow(
+    fm.body,
+    now.slice(0, 10),
+    author,
+    `Routed to Resolution DLQ → [[${diagnoseBasename}]]`,
+  );
+  return { changed: true, content: `${fm.open}${block}${fm.close}${body}` };
+}
+
+/**
+ * After a lease/heartbeat reclaim on a deferred split child: bump attempt_count;
+ * past cap → file HS-DIAG + cancel the deferred task.
+ *
+ * @param {string} vaultRoot
+ * @param {{ absPath: string, relPath: string, basename: string, raw: string }} task
+ * @param {{ reclaimReason: string, author?: string, attemptCap?: number, randomUnit?: () => number }} opts
+ */
+export function executeDeferredSplitReclaim(vaultRoot, task, opts = {}) {
+  if (!isDeferredSplitTaskRaw(task.raw)) {
+    return { ok: true, skipped: true, reason: 'not_deferred_split' };
+  }
+
+  const now = isoNow();
+  const author = opts.author ?? 'deferred-reclaim';
+  const reclaimReason = opts.reclaimReason ?? 'lease_expired';
+  const attemptCap = opts.attemptCap ?? DEFAULT_DEFER_RECLAIM_ATTEMPT_CAP;
+
+  const bumped = bumpAttemptCountInContent(task.raw, { now, author, reclaimReason });
+  if (!bumped.changed) {
+    return { ok: false, error: 'INVALID_TASK', message: 'deferred task has no frontmatter' };
+  }
+
+  const writes = [{ kind: 'update', absPath: task.absPath, content: bumped.content }];
+
+  if (bumped.attemptCount < attemptCap) {
+    const commitResult = commitWrites(writes);
+    if (!commitResult.ok) {
+      return {
+        ok: false,
+        error: 'WRITE_FAILED',
+        message: commitResult.error?.message ?? 'unknown write failure',
+      };
+    }
+    return {
+      ok: true,
+      action: 'reopened',
+      attempt_count: bumped.attemptCount,
+      attempt_cap: attemptCap,
+    };
+  }
+
+  const fm = getFrontmatterBlock(task.raw);
+  const taskName = getScalarField(fm?.block ?? '', 'name') ?? task.basename;
+  const handoffSection = handoffEnvelopeSectionFromBody(fm?.body ?? '');
+
+  const occupied = collectOccupiedDiagnoseIds(vaultRoot);
+  // Era-3 file-key-first ([[naming-v3-7-rulings-hs-namespace-kept]]): the
+  // FAMILY token still comes from the legacy allocator's `HS-<family>-DIAG`
+  // draw; `id:` keys onto the file key alone.
+  const allocatedFamilyId = allocateRandomVaultId('diagnose', occupied, { randomUnit: opts.randomUnit });
+  const familyKey =
+    parseSpecId(allocatedFamilyId)?.familyKey ?? mintFamilyKey(vaultRoot, { randomUnit: opts.randomUnit });
+  // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+  // and (V3) the anchor for `id:` itself.
+  const fileKey = mintFileKey(vaultRoot, { randomUnit: opts.randomUnit });
+  const diagnoseId = `HS-${fileKey}`;
+  const built = buildDlqDiagnoseContent({
+    diagnoseId,
+    fileKey,
+    familyKey,
+    taskBasename: task.basename,
+    taskName: String(taskName).replace(/^['"]|['"]$/g, ''),
+    attemptCount: bumped.attemptCount,
+    reclaimReason,
+    handoffSection,
+    now,
+  });
+
+  const diagnoseDir = join(vaultRoot, 'specs', 'diagnoses');
+  if (!existsSync(diagnoseDir)) mkdirSync(diagnoseDir, { recursive: true });
+  const diagnoseAbsPath = join(diagnoseDir, `${built.basename}.md`);
+  writes.push({ kind: 'create', absPath: diagnoseAbsPath, content: built.content });
+
+  const cancelled = cancelDeferredTaskContent(bumped.content, built.basename, now, author);
+  if (cancelled.changed) {
+    writes[0] = { kind: 'update', absPath: task.absPath, content: cancelled.content };
+  }
+
+  const commitResult = commitWrites(writes);
+  if (!commitResult.ok) {
+    return {
+      ok: false,
+      error: 'WRITE_FAILED',
+      message: commitResult.error?.message ?? 'unknown write failure',
+    };
+  }
+
+  return {
+    ok: true,
+    action: 'dlq',
+    attempt_count: bumped.attemptCount,
+    attempt_cap: attemptCap,
+    diagnose_id: diagnoseId,
+    diagnose_basename: built.basename,
+    diagnose_path: join('specs', 'diagnoses', `${built.basename}.md`),
+  };
+}
+
+export const __testables = {
+  readAttemptCount,
+  isDeferredSplitTaskRaw,
+  bumpAttemptCountInContent,
+  buildDlqDiagnoseContent,
+};