@wrongstack/core 0.309.1 → 0.310.0

package/dist/execution/index.js

@@ -488,7 +488,9 @@ function hasToolUseBlock(message) {
   return message?.role === "assistant" && Array.isArray(message.content) && message.content.some((block) => block.type === "tool_use");
 }
 var ConversationState = class {
+  /** Owning context; public for structural typing (Roadmap 10A). */
   ctx;
+  /** Subscribers; public for structural typing (Roadmap 10A). */
   listeners = /* @__PURE__ */ new Set();
   _revision = 0;
   constructor(ctx) {
@@ -543,9 +545,8 @@ var ConversationState = class {
   }
   /**
    * How many of the oldest messages must be dropped to satisfy both retention
-   * caps — count ({@link Context.MAX_MESSAGES}) and size
-   * ({@link Context.MAX_MESSAGE_TOKENS}). Returns 0 when the history already
-   * fits, which is the overwhelmingly common case.
+   * caps — count and size (see {@link AgentContext.messageLimits}). Returns 0
+   * when the history already fits, which is the overwhelmingly common case.
    *
    * The size pass reads the per-message `_estTokens` cache populated at
    * mutation time, so it is a sum over numbers rather than a re-walk of
@@ -553,9 +554,7 @@ var ConversationState = class {
    * cap determines the starting index for the sum but does not gate it.
    */
   overflowCount(arr) {
-    const contextClass = this.ctx.constructor;
-    const maxMessages = contextClass.MAX_MESSAGES;
-    const maxMessageTokens = contextClass.MAX_MESSAGE_TOKENS;
+    const { maxMessages, maxMessageTokens } = this.ctx.messageLimits;
     let drop = maxMessages > 0 ? Math.max(0, arr.length - maxMessages) : 0;
     if (maxMessageTokens <= 0) return this.protocolSafeDropCount(arr, drop);
     let total = 0;
@@ -826,6 +825,10 @@ var Context = class _Context {
    * so storage operations can include it in `storage.*` events.
    */
   traceId;
+  /** Logical provider request whose response produced the current tool calls. */
+  activeLogicalRequestId = void 0;
+  /** Content-addressed prompt composition for {@link activeLogicalRequestId}. */
+  activePromptManifestId = void 0;
   /**
    * Session id pinned to the currently-executing run. Set by `Agent.run()`
    * at run start and cleared when the run ends. Event-emission sites must
@@ -851,6 +854,7 @@ var Context = class _Context {
     return resolveEventSessionId(this);
   }
   /** Callbacks fired when `setWorkingDir()` changes the working directory. */
+  /** WorkingDir-change callbacks; public for structural typing (Roadmap 10A). */
   _onWorkingDirChanged = [];
   /**
    * Serializes externally requested provider/model changes. Request creation
@@ -1106,7 +1110,16 @@ var Context = class _Context {
    * For hooks that must survive across run boundaries (mailbox heartbeat,
    * awareness polling, HQ publisher), prefer `registerAgentHook` instead.
    */
+  /** Run-scoped abort hooks (drained by drainAbortHooks). Public for structural typing (Roadmap 10A). */
   abortHooks = /* @__PURE__ */ new Set();
+  /** Retention limits honoring runtime subclass overrides of the statics. */
+  get messageLimits() {
+    const cls = this.constructor;
+    return Object.freeze({
+      maxMessages: cls.MAX_MESSAGES,
+      maxMessageTokens: cls.MAX_MESSAGE_TOKENS
+    });
+  }
   registerAbortHook(fn) {
     this.abortHooks.add(fn);
     return () => this.abortHooks.delete(fn);
@@ -1131,6 +1144,7 @@ var Context = class _Context {
    * awareness polling interval, HQ publisher connection, and auto-compaction
    * timer — resources that must survive from the first run to the last.
    */
+  /** Session-lifetime teardown hooks (drained by drainAgentHooks). Public for structural typing (Roadmap 10A). */
   agentHooks = /* @__PURE__ */ new Set();
   registerAgentHook(fn) {
     this.agentHooks.add(fn);
@@ -1311,6 +1325,9 @@ var Context = class _Context {
       agentName: this.agentName,
       provider: typeof this.provider === "object" ? this.provider.id : String(this.provider),
       model: this.model,
+      ...this.activeLogicalRequestId ? { logicalRequestId: this.activeLogicalRequestId } : {},
+      ...this.activePromptManifestId ? { promptManifestId: this.activePromptManifestId } : {},
+      provenanceConfidence: this.activeLogicalRequestId && this.activePromptManifestId ? "explicit" : "unknown",
       toolName: input.toolName,
       toolUseId: input.toolUseId,
       scope,
@@ -1338,6 +1355,9 @@ var Context = class _Context {
       agentName: this.agentName,
       provider: record.provider,
       model: record.model,
+      ...record.logicalRequestId ? { logicalRequestId: record.logicalRequestId } : {},
+      ...record.promptManifestId ? { promptManifestId: record.promptManifestId } : {},
+      provenanceConfidence: record.provenanceConfidence,
       toolName: input.toolName,
       toolUseId: input.toolUseId,
       scope,
@@ -3570,127 +3590,11 @@ function assertNever(x, message) {
 }
 
 // src/utils/regex-guard.ts
-var MAX_PATTERN_LEN = 256;
-var DANGEROUS_PATTERNS = [
-  // (a+)+, (.*)+, etc — nested quantifier on a group with internal quantifier
-  /(\([^)]*[+*][^)]*\))[+*]/,
-  /(\(\?:[^)]*[+*][^)]*\))[+*]/,
-  // Adjacent quantifiers: a++ a*+
-  /[+*]{2,}/,
-  // Quantifier on alternation with length 2+
-  /\([^|)]+\|[^)]+\)[+*][+*]/,
-  // Greedy quantifier inside lookahead/lookbehind — (?!.*a+)
-  /[([][^)\]]*[+*][^)\]]*[)\]][^)]*\?\??/
-];
-function hasAmbiguousQuantifiedAlternation(pattern) {
-  for (let i = 0; i < pattern.length; i++) {
-    if (pattern[i] !== "(") continue;
-    if (i > 0 && pattern[i - 1] === "\\") continue;
-    let depth = 0;
-    let inClass = false;
-    let j = i;
-    for (; j < pattern.length; j++) {
-      const ch = pattern[j];
-      if (ch === "\\") {
-        j++;
-        continue;
-      }
-      if (inClass) {
-        if (ch === "]") inClass = false;
-        continue;
-      }
-      if (ch === "[") {
-        inClass = true;
-        continue;
-      }
-      if (ch === "(") depth++;
-      else if (ch === ")") {
-        depth--;
-        if (depth === 0) break;
-      }
-    }
-    if (j >= pattern.length) return false;
-    const next = pattern[j + 1];
-    if (next !== "+" && next !== "*" && next !== "{") continue;
-    let inner = pattern.slice(i + 1, j);
-    inner = inner.replace(/^\?(?::|<?[=!])/u, "");
-    const branches = [];
-    let current = "";
-    let d = 0;
-    let cls = false;
-    for (let k = 0; k < inner.length; k++) {
-      const ch = inner[k];
-      if (ch === "\\") {
-        current += ch + (inner[k + 1] ?? "");
-        k++;
-        continue;
-      }
-      if (cls) {
-        if (ch === "]") cls = false;
-        current += ch;
-        continue;
-      }
-      if (ch === "[") {
-        cls = true;
-        current += ch;
-        continue;
-      }
-      if (ch === "(") d++;
-      if (ch === ")") d--;
-      if (ch === "|" && d === 0) {
-        branches.push(current);
-        current = "";
-        continue;
-      }
-      current += ch;
-    }
-    branches.push(current);
-    if (branches.length < 2) continue;
-    for (let a = 0; a < branches.length; a++) {
-      for (let b = a + 1; b < branches.length; b++) {
-        const x = branches[a];
-        const y = branches[b];
-        if (x === "" || y === "") return true;
-        if (x === y || x.startsWith(y) || y.startsWith(x)) return true;
-      }
-    }
-  }
-  return false;
-}
-function compileUserRegex(pattern, flags) {
-  if (typeof pattern !== "string") {
-    return { ok: false, reason: "pattern must be a string" };
-  }
-  if (pattern.length === 0) {
-    return { ok: false, reason: "pattern is empty" };
-  }
-  if (pattern.length > MAX_PATTERN_LEN) {
-    return { ok: false, reason: `pattern exceeds ${MAX_PATTERN_LEN} characters` };
-  }
-  for (const rx of DANGEROUS_PATTERNS) {
-    if (rx.test(pattern)) {
-      return {
-        ok: false,
-        reason: "pattern looks vulnerable to catastrophic backtracking \u2014 rewrite without nested quantifiers"
-      };
-    }
-  }
-  if (hasAmbiguousQuantifiedAlternation(pattern)) {
-    return {
-      ok: false,
-      reason: "pattern quantifies an alternation with overlapping branches \u2014 rewrite so no two branches can match the same text"
-    };
-  }
-  try {
-    return { ok: true, regex: new RegExp(pattern, flags) };
-  } catch (err) {
-    return {
-      ok: false,
-      reason: err instanceof Error ? err.message : "invalid regex"
-    };
-  }
-}
-var MAX_SUBJECT_LEN = 64 * 1024;
+import {
+  capSubject,
+  compileUserRegex,
+  MAX_SUBJECT_LEN
+} from "@wrongstack/primitives";
 
 // src/execution/autonomous-runner.ts
 var DoneConditionChecker = class {
@@ -5088,7 +4992,12 @@ function isContextOverflowShaped(err) {
   const providerErr = err;
   if (providerErr.kind === "context_overflow" || providerErr.status === 413) return true;
   if (providerErr.status < 400) return false;
-  const text = [providerErr.message, providerErr.body?.message, providerErr.body?.type, providerErr.body?.raw].filter(Boolean).join("\n");
+  const text = [
+    providerErr.message,
+    providerErr.body?.message,
+    providerErr.body?.type,
+    providerErr.body?.raw
+  ].filter(Boolean).join("\n");
   return CONTEXT_OVERFLOW_RE.test(text);
 }
 function describeStatus(status, type) {
@@ -10393,27 +10302,39 @@ var DefaultErrorHandler = class {
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
-// src/storage/goal-coordination.ts
-import { updateTask } from "@wrongstack/kanban";
+// src/storage/board-store-port.ts
+var notWired = () => {
+  throw new Error(
+    "Kanban BoardStorePort is not wired \u2014 register the implementation at the CLI composition root (see setBoardStorePort)."
+  );
+};
+var port = void 0;
+function boardStore() {
+  return port ?? notWired();
+}
+function tryBoardStore() {
+  return port ?? null;
+}
 
 // src/storage/goal-kanban.ts
-import { addTask, createBoard, getBoard, listBoards, removeBoard } from "@wrongstack/kanban";
 var GOAL_BOARD_TAG_PREFIX = "goal:";
 async function findGoalKanbanBoard(projectRoot, boardId) {
   if (!projectRoot || !boardId) return null;
   try {
-    return await getBoard(projectRoot, boardId);
+    return await boardStore().getBoard(projectRoot, boardId);
   } catch {
     return null;
   }
 }
 async function findGoalBoardByTag(projectRoot, goalFile) {
   if (!projectRoot) return null;
+  const store = tryBoardStore();
+  if (!store) return null;
   const tag = goalTag(goalFile);
-  const boards = await listBoards(projectRoot);
+  const boards = await store.listBoards(projectRoot);
   const matched = boards.find((b) => b.tags?.includes(tag));
   if (!matched) return null;
-  return getBoard(projectRoot, matched.id).catch(() => null);
+  return store.getBoard(projectRoot, matched.id).catch(() => null);
 }
 function goalTag(goalFile) {
   const goal = (goalFile.refinedGoal || goalFile.goal).replace(/\s+/g, "-").slice(0, 24).toLowerCase();
@@ -10577,7 +10498,7 @@ async function refreshGoalKanban(projectRoot, goal, completed, resolvedBoard) {
     const originMatch = task.origin?.system === "goal" && task.origin?.taskId ? originKeys.has(task.origin.taskId) : false;
     const titleMatch = !task.origin?.taskId && completedTitles.has(normalizeTitle(task.title));
     if (!originMatch && !titleMatch) continue;
-    const result = await updateTask(
+    const result = await boardStore().updateTask(
       projectRoot,
       board.id,
       task.id,
@@ -22043,6 +21964,8 @@ function logToolSuccess(opts, ctx, use, toolName, durationMs, outputChars) {
     id: use.id,
     sessionId: ctx.session.id,
     ...ctx.traceId ? { traceId: ctx.traceId } : {},
+    ...ctx.activeLogicalRequestId ? { logicalRequestId: ctx.activeLogicalRequestId } : {},
+    ...ctx.activePromptManifestId ? { promptManifestId: ctx.activePromptManifestId } : {},
     agentId: ctx.agentId ?? "<unknown>",
     durationMs,
     outputChars
@@ -22067,6 +21990,8 @@ function logToolFailure(opts, ctx, use, toolName, durationMs, err) {
     id: use.id,
     sessionId: ctx.session.id,
     ...ctx.traceId ? { traceId: ctx.traceId } : {},
+    ...ctx.activeLogicalRequestId ? { logicalRequestId: ctx.activeLogicalRequestId } : {},
+    ...ctx.activePromptManifestId ? { promptManifestId: ctx.activePromptManifestId } : {},
     agentId: ctx.agentId ?? "<unknown>",
     durationMs,
     category,
@@ -22136,14 +22061,20 @@ import { isDeepStrictEqual } from "node:util";
 // src/security/kanban-boundary.ts
 import { realpath } from "node:fs/promises";
 import * as path17 from "node:path";
-import {
-  evaluateContractGraphReadiness,
-  evaluateKanbanBoundaryOpaque,
-  evaluateKanbanBoundaryPath,
-  readBoard,
-  resolveKanbanBoundaryLayers
-} from "@wrongstack/kanban";
-var GOVERNANCE_CONTROL_TOOLS = /* @__PURE__ */ new Set(["kanban", "plan", "task", "todo"]);
+
+// src/security/kanban-governance-port.ts
+var notWired2 = () => {
+  throw new Error(
+    "KanbanGovernancePort is not wired \u2014 register the implementation at the CLI composition root (see setKanbanGovernance)."
+  );
+};
+var port2 = void 0;
+function kanbanGovernance() {
+  return port2 ?? notWired2();
+}
+
+// src/security/kanban-boundary.ts
+var GOVERNANCE_CONTROL_TOOLS = /* @__PURE__ */ new Set(["kanban", "plan", "task", "todo", "nextsteps"]);
 var PATH_KEYS = /* @__PURE__ */ new Set([
   "path",
   "paths",
@@ -22178,7 +22109,10 @@ async function evaluateToolKanbanBoundary(tool, input, ctx, options = {}) {
       reason: "Kanban governance is mandatory before product mutation. Create a managed card, add its required details and executable acceptance criteria, then call kanban start_task to bind it to this run."
     } : { decision: "allow" };
   }
-  const board = await readBoard(identity.policyRoot ?? ctx.projectRoot, identity.boardId);
+  const board = await kanbanGovernance().readBoard(
+    identity.policyRoot ?? ctx.projectRoot,
+    identity.boardId
+  );
   if (!board) {
     return governanceRequired ? {
       decision: "block",
@@ -22204,22 +22138,39 @@ async function evaluateToolKanbanBoundary(tool, input, ctx, options = {}) {
         taskId: identity.taskId
       };
     }
-    const readiness = evaluateContractGraphReadiness(board, task.id);
+    const readiness = kanbanGovernance().evaluateContractGraphReadiness(board, task.id);
     if (!readiness.ready) {
+      const issueLines = readiness.issues.map((issue, index) => `  ${index + 1}. ${issue.message}`).join("\n");
       return {
         decision: "block",
-        reason: "Active card is not implementation-ready: " + readiness.issues.map((issue) => issue.message).join(" | "),
+        reason: `Active card failed contract-readiness check (${readiness.issues.length} issue(s)):
+` + issueLines + `
+Resolve the readiness issues, then call kanban start_task to retry.`,
         boardId: board.id,
         taskId: task.id,
         readinessIssues: readiness.issues
       };
     }
-    if (task.lifecycle?.currentStage !== "running" || task.assignment?.status !== "running") {
-      const lifecycleStage = task.lifecycle?.currentStage ?? "missing";
-      const assignmentStatus = task.assignment?.status ?? "missing";
+    const lifecycleStage = task.lifecycle?.currentStage;
+    const assignmentStatus = task.assignment?.status;
+    const lifecycleOk = lifecycleStage === "running";
+    const assignmentOk = assignmentStatus === "running";
+    if (!lifecycleOk || !assignmentOk) {
+      const failed = [];
+      let reassessmentNote = "";
+      if (!lifecycleOk) {
+        failed.push(`lifecycle.currentStage (got: ${lifecycleStage ?? "missing"}; want: 'running')`);
+      }
+      if (!assignmentOk) {
+        failed.push(`assignment.status (got: ${assignmentStatus ?? "missing"}; want: 'running')`);
+        if (lifecycleOk && (assignmentStatus === "queued" || assignmentStatus === void 0 || assignmentStatus === null)) {
+          reassessmentNote = '\nNote: lifecycle is still "running" but the assignment was cleared \u2014 the automated kanban reassessment agent likely reset the binding. Re-issue kanban start_task to re-bind the leader to this card.';
+        }
+      }
       return {
         decision: "block",
-        reason: `Active card must be in Running with a live assignment before product mutation (lifecycle: ${lifecycleStage}; assignment: ${assignmentStatus}). Call kanban start_task after completing the required card details.`,
+        reason: `Active card failed ${failed.length} governance check(s) before product mutation:
+` + failed.map((line, index) => `  ${index + 1}. ${line}`).join("\n") + reassessmentNote,
         boardId: board.id,
         taskId: task.id
       };
@@ -22237,7 +22188,7 @@ async function evaluateToolKanbanBoundary(tool, input, ctx, options = {}) {
       };
     }
   }
-  const layers = resolveKanbanBoundaryLayers(board, task);
+  const layers = kanbanGovernance().resolveKanbanBoundaryLayers(board, task);
   if (layers.length === 0) return { decision: "allow" };
   const caps = tool.capabilities ?? [];
   const access2 = caps.includes("fs.write") || caps.includes("fs.write.outside-project") ? "write" : caps.includes("fs.read") ? "read" : void 0;
@@ -22245,10 +22196,10 @@ async function evaluateToolKanbanBoundary(tool, input, ctx, options = {}) {
   const candidates = access2 ? await extractCandidatePaths(tool.name, input, ctx) : [];
   let evaluation;
   if (shellLike || access2 && candidates.length === 0) {
-    evaluation = evaluateKanbanBoundaryOpaque(layers, tool.name);
+    evaluation = kanbanGovernance().evaluateKanbanBoundaryOpaque(layers, tool.name);
   } else if (access2) {
     const results = candidates.map(
-      (candidate) => evaluateKanbanBoundaryPath(layers, candidate, access2)
+      (candidate) => kanbanGovernance().evaluateKanbanBoundaryPath(layers, candidate, access2)
     );
     evaluation = results.find((result) => result.decision === "block") ?? results.find((result) => result.decision === "confirm") ?? { decision: "allow" };
   } else {
@@ -22775,6 +22726,8 @@ var ToolExecutor = class _ToolExecutor {
       this.opts.events?.emit("permission.evaluated", {
         sessionId: resolveEventSessionId(ctx),
         ...ctx.traceId ? { traceId: ctx.traceId } : {},
+        ...ctx.activeLogicalRequestId ? { logicalRequestId: ctx.activeLogicalRequestId } : {},
+        ...ctx.activePromptManifestId ? { promptManifestId: ctx.activePromptManifestId } : {},
         ...ctx.agentId ? { agentId: ctx.agentId } : {},
         name: tool.name,
         id: use.id,
@@ -22926,6 +22879,9 @@ ${post.additionalContext}`;
             agentName: ctx.agentName,
             provider: typeof ctx.provider === "object" ? ctx.provider.id : String(ctx.provider),
             model: ctx.model,
+            ...ctx.activeLogicalRequestId ? { logicalRequestId: ctx.activeLogicalRequestId } : {},
+            ...ctx.activePromptManifestId ? { promptManifestId: ctx.activePromptManifestId } : {},
+            provenanceConfidence: ctx.activeLogicalRequestId && ctx.activePromptManifestId ? "explicit" : "unknown",
             toolName: tool.name,
             toolUseId: use.id,
             scope: ctx.currentKanbanTaskId ? "task" : "session",
@@ -23068,6 +23024,8 @@ ${preToolContext.text}` : preToolContext.text;
     this.opts.events?.emit("tool.started", {
       sessionId: resolveEventSessionId(ctx),
       ...ctx.traceId ? { traceId: ctx.traceId } : {},
+      ...ctx.activeLogicalRequestId ? { logicalRequestId: ctx.activeLogicalRequestId } : {},
+      ...ctx.activePromptManifestId ? { promptManifestId: ctx.activePromptManifestId } : {},
       agentId: ctx.agentId,
       agentName: ctx.agentName,
       name: tool.name,

package/dist/goal/index.js

@@ -207,6 +207,13 @@ var TaskTracker = class _TaskTracker {
   graph = null;
   transitions = [];
   listeners = [];
+  /**
+   * Re-entrancy guard for status cascades: true while an auto-block /
+   * auto-unblock cascade is running. Listener-driven mutations during a
+   * cascade still record their own primary transition — only their
+   * cascading is skipped (prevents unbounded recursion).
+   */
+  cascading = false;
   static MAX_TRANSITIONS = 1e4;
   /**
    * Subscribe to live task mutations (add / update / status change). Returns an
@@ -282,6 +289,28 @@ var TaskTracker = class _TaskTracker {
         message: "No graph loaded",
         code: ERROR_CODES.SDD_INVALID_STATE
       });
+    if (!this.graph.nodes.has(from) || !this.graph.nodes.has(to)) {
+      throw new SddError({
+        message: `Cannot add ${type} edge ${from} -> ${to}: endpoint task is not in the graph`,
+        code: ERROR_CODES.SDD_NOT_READY,
+        context: { from, to, type }
+      });
+    }
+    if (from === to) {
+      throw new SddError({
+        message: `Cannot add ${type} edge: self-loop on task ${from}`,
+        code: ERROR_CODES.SDD_INVALID_STATE,
+        context: { nodeId: from, type }
+      });
+    }
+    if (this.graph.edges.some((e) => e.from === from && e.to === to && e.type === type)) return;
+    if (type === "depends_on" && this.dependsOnTransitively(from, to, /* @__PURE__ */ new Set())) {
+      throw new SddError({
+        message: `Cannot add depends_on edge ${from} -> ${to}: it would create a dependency cycle`,
+        code: ERROR_CODES.SDD_INVALID_STATE,
+        context: { from, to }
+      });
+    }
     this.graph.edges.push({
       id: crypto.randomUUID(),
       from,
@@ -382,7 +411,7 @@ var TaskTracker = class _TaskTracker {
     if (status === "in_progress") {
       node.startedAt = now;
     }
-    this.transitions.push({ from, to: status, timestamp: now, reason });
+    this.transitions.push({ nodeId: id, from, to: status, timestamp: now, reason });
     if (this.transitions.length > _TaskTracker.MAX_TRANSITIONS) {
       this.transitions.splice(0, this.transitions.length - _TaskTracker.MAX_TRANSITIONS);
     }
@@ -398,7 +427,7 @@ var TaskTracker = class _TaskTracker {
       type: "status_changed",
       nodeId: id,
       node,
-      transition: { from, to: status, timestamp: now, reason }
+      transition: { nodeId: id, from, to: status, timestamp: now, reason }
     });
   }
   updateNode(id, patch) {
@@ -489,40 +518,89 @@ var TaskTracker = class _TaskTracker {
     }
     return computeTaskProgress(this.graph);
   }
-  getTransitions(_taskId) {
-    return [...this.transitions];
+  /**
+   * Recorded transitions in insertion order (oldest first — the array is
+   * trimmed from the front). With `taskId`, only that task's transitions are
+   * returned, still oldest-first; a consumer wanting newest-first reverses
+   * the result. Per-task filtering is possible because every TaskTransition
+   * carries `nodeId` (BIZ-005).
+   */
+  getTransitions(taskId) {
+    return taskId === void 0 ? [...this.transitions] : this.transitions.filter((t) => t.nodeId === taskId);
+  }
+  /**
+   * Record a cascade-driven status change (BIZ-003): mutate the node, push a
+   * TaskTransition, persist, and notify subscribers — the same effects an
+   * explicit updateNodeStatus produces — so the board projector's live
+   * snapshot and the transition log observe auto-block/auto-unblock.
+   */
+  recordCascadeStatusChange(nodeId, node, to, reason) {
+    const from = node.status;
+    if (from === to) return;
+    const now = Date.now();
+    node.status = to;
+    node.updatedAt = now;
+    if (this.graph) this.graph.updatedAt = now;
+    this.transitions.push({ nodeId, from, to, timestamp: now, reason });
+    if (this.transitions.length > _TaskTracker.MAX_TRANSITIONS) {
+      this.transitions.splice(0, this.transitions.length - _TaskTracker.MAX_TRANSITIONS);
+    }
+    this.persist();
+    this.notifyChange({
+      type: "status_changed",
+      nodeId,
+      node,
+      transition: { nodeId, from, to, timestamp: now, reason }
+    });
   }
   unblockDependents(completedId) {
-    if (!this.graph) return;
-    const dependents = this.getDependents(completedId);
-    for (const depId of dependents) {
-      const dep = this.graph.nodes.get(depId);
-      if (dep?.status === "blocked") {
+    if (!this.graph || this.cascading) return;
+    this.cascading = true;
+    try {
+      const dependents = this.getDependents(completedId);
+      for (const depId of dependents) {
+        const dep = this.graph.nodes.get(depId);
+        if (dep?.status !== "blocked") continue;
         const remainingBlockers = this.getBlockers(depId);
         const allUnblocked = remainingBlockers.every((id) => {
           const blocker = this.graph?.nodes.get(id);
           return blocker?.status === "completed" || blocker?.status === "failed";
         });
         if (allUnblocked) {
-          dep.status = "pending";
-          dep.updatedAt = Date.now();
+          this.recordCascadeStatusChange(
+            depId,
+            dep,
+            "pending",
+            `auto-unblocked: blocker ${completedId} reached a terminal state`
+          );
         }
       }
+    } finally {
+      this.cascading = false;
     }
   }
   checkAndBlockIfNeeded(taskId) {
-    if (!this.graph) return;
-    const blockers = this.getBlockers(taskId);
-    const someBlocked = blockers.some((id) => {
-      const blocker = this.graph?.nodes.get(id);
-      return blocker?.status !== "completed" && blocker?.status !== "failed";
-    });
-    if (someBlocked) {
-      const node = this.graph.nodes.get(taskId);
-      if (node) {
-        node.status = "blocked";
-        node.updatedAt = Date.now();
+    if (!this.graph || this.cascading) return;
+    this.cascading = true;
+    try {
+      const blockers = this.getBlockers(taskId);
+      const incomplete = blockers.filter((id) => {
+        const blocker = this.graph?.nodes.get(id);
+        return blocker?.status !== "completed" && blocker?.status !== "failed";
+      });
+      if (incomplete.length > 0) {
+        const node = this.graph.nodes.get(taskId);
+        if (node) {
+          this.recordCascadeStatusChange(
+            taskId,
+            node,
+            "blocked",
+            `auto-blocked: incomplete blocker(s) ${incomplete.join(", ")}`
+          );
+        }
       }
+    } finally {
+      this.cascading = false;
     }
   }
   /**

package/dist/hq/auth-store.d.ts

@@ -167,6 +167,15 @@ export interface HqAuthFile {
      * reveal unused codes. Each code is consumed on first successful use.
      */
     totpRecoveryCodes?: string[];
+    /**
+     * Highest TOTP time-step counter already consumed by a successful 2FA
+     * verification (SEC-002: persisted to prevent replay after restart).
+     * Written by the 2FA verification route (`totp-routes.ts`) — not the
+     * initial password check — and read there to reject any counter <= this
+     * value, so an observed code cannot be replayed within its validity
+     * window even across a server restart.
+     */
+    totpLastUsedCounter?: number;
     /**
      * Operator-configured alert-rule thresholds. When present, these override
      * the built-in defaults for the alert engine (cost ceiling, stale-machine

package/dist/hq/cost-bridge.d.ts

@@ -16,8 +16,8 @@
  * @module hq/cost-bridge
  */
 import type { EventBus } from '../kernel/events.js';
-import type { HqEventEnvelope } from './protocol.js';
 import { type BridgeContextOptions } from './bridge-context.js';
+import type { HqEventEnvelope } from './protocol.js';
 export interface CostTelemetryBridgeOptions extends BridgeContextOptions {
     /** Local EventBus emitting `token.accounted`. */
     events: EventBus;