@juzser/blacksmith 0.1.0 → 0.2.0

package/factory/orchestrator/dist/agents-registry.js

@@ -38,14 +38,30 @@ import { epicOfTaskId } from './taskId.js';
  * entry still open under that task, because after a task-level failure nobody
  * is still running.
  *
+ * An epic-level dispatch — a planner, a spec-reviewer, a scribe, sent for
+ * the epic with no task id — closes on a terminal event that also names no
+ * task and does name its role (F2, the cross-provider UI check of
+ * 2026-09-14). Its Result is recorded as a `task-result-recorded` with no
+ * task id and `agent_role` in the payload, and until F2 every terminal branch
+ * was guarded on the task id, so ten such results across the real logs closed
+ * nothing: a planner that returned in four minutes read as live for the rest
+ * of the epic. The event speaks for the latest still-open epic-level entry of
+ * that role in the same session — latest because a result belongs to the
+ * dispatch that caused it, and that is the most recent one — and steps back
+ * when the two name different epics. There is no supersession at this level
+ * (D-244): a second planner dispatch is a second round, not a replacement,
+ * and a terminal event that names no role closes nothing here, because
+ * guessing which agent a session-level error was about is the D-244 mistake
+ * one level up.
+ *
  * Above all of those sits `epic-closed` (D-187). Every close named so far
- * needs a task id to speak through, so an agent whose task simply never
- * reported — and an epic-level dispatch, which has no task id to speak
- * through at all — stayed `live` past the verdict, past the end of the run,
- * forever. The epic's own terminal event is the only thing that can say
- * otherwise, and it closes what is still open under that epic in that session
- * as `abandoned`: not superseded (nothing replaced them) and not an error
- * (they were never judged), just outrun by the run they belonged to.
+ * needs a task id or a role to speak through, so an agent whose task simply
+ * never reported — and an epic-level dispatch whose Result never came —
+ * stayed `live` past the verdict, past the end of the run, forever. The
+ * epic's own terminal event is the only thing that can say otherwise, and it
+ * closes what is still open under that epic in that session as `abandoned`:
+ * not superseded (nothing replaced them) and not an error (they were never
+ * judged), just outrun by the run they belonged to.
  */
 export const DISPATCH_EVENT_TYPE = 'dispatch_decision';
 /** Phase 5 addition (deviation, noted in the final report): the terminal counterpart to dispatch_decision. */
@@ -147,6 +163,26 @@ function closeOpen(open, taskId, role, eventId, ts, terminalType) {
         open.delete(key);
     }
 }
+/**
+ * Close the epic-level entry a task-less terminal event speaks for: the
+ * latest still-open dispatch of `role` in `sessionId` (F2). `epicId` is the
+ * event's own claim about which epic it belongs to; when both sides name one
+ * and they differ, the event is another epic's and closes nothing here. The
+ * list is scanned from the end because the most recent dispatch of a role is
+ * the one whose Result this is.
+ */
+function closeOpenEpicLevel(openEpicLevel, sessionId, role, epicId, eventId, ts, terminalType) {
+    for (let i = openEpicLevel.length - 1; i >= 0; i--) {
+        const entry = openEpicLevel[i];
+        if (!entry || entry.sessionId !== sessionId || entry.agentRole !== role)
+            continue;
+        if (epicId && entry.epicId && entry.epicId !== epicId)
+            continue;
+        closeEntry(entry, eventId, ts, terminalType);
+        openEpicLevel.splice(i, 1);
+        return;
+    }
+}
 /**
  * Fold a session's full event history into agent registry rows. Pure
  * function over the event list — used identically by db/projector.ts's
@@ -156,7 +192,8 @@ function closeOpen(open, taskId, role, eventId, ts, terminalType) {
 export function foldAgents(events) {
     const open = new Map();
     // Dispatches with no task id have no correlation key, so they cannot live in
-    // `open` — but they are still open, and `epic-closed` still speaks for them.
+    // `open` — but they are still open: a task-less terminal naming their role
+    // closes the latest of them (F2), and `epic-closed` sweeps the rest.
     let openEpicLevel = [];
     const records = [];
     for (const { event_id, record } of events) {
@@ -205,13 +242,20 @@ export function foldAgents(events) {
         }
         if (record.event_type === TASK_RESULT_EVENT_TYPE) {
             // The Result names its author in `agent` (result.schema.json's required
-            // field). A hand-appended one that omits it still closes the task.
+            // field). A hand-appended one that omits it still closes the task. An
+            // epic-level one, recorded by hand with no task id, spells the role as
+            // `agent_role` — the dispatch's own key — in every real log so far, so
+            // the fold reads either.
             const payload = record.payload;
             // Both levels: result.schema.json names the task in the payload, and the
             // dispatch this closes may have named it only there too (D-245).
             const taskId = eventTaskId(record);
+            const role = payload.agent ?? payload.agent_role ?? null;
             if (taskId) {
-                closeOpen(open, taskId, payload.agent ?? null, event_id, record.ts, 'result');
+                closeOpen(open, taskId, role, event_id, record.ts, 'result');
+            }
+            else if (role) {
+                closeOpenEpicLevel(openEpicLevel, record.session_id, role, payload.epic_id, event_id, record.ts, 'result');
             }
             continue;
         }
@@ -221,19 +265,25 @@ export function foldAgents(events) {
             if (taskId) {
                 closeOpen(open, taskId, payload.agent_role ?? null, event_id, record.ts, 'result');
             }
+            else if (payload.agent_role) {
+                closeOpenEpicLevel(openEpicLevel, record.session_id, payload.agent_role, payload.epic_id, event_id, record.ts, 'result');
+            }
             continue;
         }
         if (record.event_type === JUDGE_VERDICT_EVENT_TYPE) {
             const payload = record.payload;
             const taskId = eventTaskId(record);
+            // A run that produced no schema-valid verdict did not do its job, and
+            // `ok: false` is how the log says so. Closing it as a result would let
+            // a provider failing every call read exactly like one answering every
+            // call — the distinction providerAgreement() exists to measure.
+            const terminal = payload.ok === false ? 'error' : 'result';
             if (taskId) {
-                // A run that produced no schema-valid verdict did not do its job, and
-                // `ok: false` is how the log says so. Closing it as a result would let
-                // a provider failing every call read exactly like one answering every
-                // call — the distinction providerAgreement() exists to measure.
-                const terminal = payload.ok === false ? 'error' : 'result';
                 closeOpen(open, taskId, payload.agent ?? null, event_id, record.ts, terminal);
             }
+            else if (payload.agent) {
+                closeOpenEpicLevel(openEpicLevel, record.session_id, payload.agent, payload.epic_id, event_id, record.ts, terminal);
+            }
             continue;
         }
         if (record.event_type === ERROR_EVENT_TYPE) {
@@ -244,6 +294,11 @@ export function foldAgents(events) {
             if (taskId) {
                 closeOpen(open, taskId, payload.agent_role ?? null, event_id, record.ts, 'error');
             }
+            else if (payload.agent_role) {
+                // Only with a role: a session-level error names nobody, and every
+                // epic-level agent stays where it was.
+                closeOpenEpicLevel(openEpicLevel, record.session_id, payload.agent_role, payload.epic_id, event_id, record.ts, 'error');
+            }
             continue;
         }
         if (record.event_type === EPIC_CLOSED_EVENT_TYPE) {
@@ -262,10 +317,10 @@ export function foldAgents(events) {
                 closeEntry(entry, event_id, record.ts, 'abandoned');
                 open.delete(key);
             }
-            // The epic-level half keeps D-187's reasoning for an entry nothing
-            // places -- no task id and no `epic_id` on its dispatch means no other
-            // terminal event can ever name it, so the run's own verdict is the last
-            // thing that can close it. But an entry that DID name an epic is placed,
+            // The epic-level half keeps D-187's reasoning for an entry whose Result
+            // never came -- no task id means only a terminal naming its role (F2)
+            // or the run's own verdict can close it, and this is the verdict. But
+            // an entry that DID name an epic is placed,
             // and one session runs several epics in a row: sweeping the lot closed
             // the next epic's planner, live and working, on the previous epic's
             // verdict (D-234).
@@ -306,3 +361,25 @@ export function detectStale(agents, nowIso, staleHours = DEFAULT_STALE_HOURS) {
 export function liveAgents(agents) {
     return agents.filter((a) => a.status === 'live');
 }
+/**
+ * Whether a dispatch at `dispatchedAt` still counts as *working* at `nowIso`:
+ * the dashboard's answer to "is anyone actually on this right now", as
+ * opposed to "has no terminal event closed it yet" (`liveAgents`). Same
+ * arithmetic and the same strict `>` as `detectStale` — working is the
+ * complement of stale over the live set — kept as one predicate so the
+ * queries that count, group and label agents cannot drift from the
+ * threshold the registry warns on.
+ *
+ * Two readings `detectStale`'s loop leaves implicit are pinned here because
+ * the dashboard renders them: a dispatch whose timestamp does not parse is
+ * NOT working (NaN compares false in both directions, which would otherwise
+ * read as "not stale, so working" — an unreadable clock is never evidence
+ * of activity), and a future-dated dispatch IS working (clock skew between
+ * the writer and the reader is not staleness).
+ */
+export function isWorkingAt(dispatchedAt, nowIso, staleHours = DEFAULT_STALE_HOURS) {
+    const liveHours = (new Date(nowIso).getTime() - new Date(dispatchedAt).getTime()) / 3.6e6;
+    if (Number.isNaN(liveHours))
+        return false;
+    return liveHours <= staleHours;
+}

package/factory/orchestrator/dist/artifacts.js

@@ -1,7 +1,7 @@
 import { existsSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { SmithError } from './errors.js';
-import { STATE_ARTIFACTS_DIR } from './paths.js';
+import { STATE_ARTIFACTS_DIR, WORK_ROOT } from './paths.js';
 /**
  * Where a task's artifacts belong: `state/artifacts/<task-id>/`, beside
  * `state/results/<task-id>.json`. One home per task, named by the task, so the
@@ -38,6 +38,33 @@ function realOf(p) {
         return p;
     }
 }
+/**
+ * How the home is spelled from the work root — `state/artifacts/<task-id>` in
+ * production — or null when it does not sit under that root at all, in which
+ * case no relative declaration can be naming it.
+ */
+function spellingFromWorkRoot(home, workRoot) {
+    const rel = path.relative(path.resolve(workRoot), home);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    return rel;
+}
+/**
+ * The declared path with the home's own spelling stripped off, when it starts
+ * with one: `state/artifacts/<task-id>/round2.txt` becomes `round2.txt`, and
+ * the bare spelling becomes `''`, which is the home itself and reports as
+ * `no-path`. Anything else — an absolute path, a plain filename, another
+ * task's home — is handed back as written.
+ */
+function withinHome(declared, homeSpelling) {
+    if (homeSpelling === null || path.isAbsolute(declared))
+        return declared;
+    const normalized = path.normalize(declared);
+    if (normalized === homeSpelling)
+        return '';
+    const prefix = homeSpelling + path.sep;
+    return normalized.startsWith(prefix) ? normalized.slice(prefix.length) : declared;
+}
 /** True when `child` is `root` itself or lives beneath it. */
 function contains(root, child) {
     if (child === root)
@@ -48,7 +75,11 @@ function contains(root, child) {
 /**
  * Check every path a result declares as evidence. Relative paths resolve
  * against the task's home, so `coverage.txt` means the obvious thing and the
- * short spelling is also the correct one.
+ * short spelling is also the correct one. A path that already begins with the
+ * home's own spelling from the work root — `state/artifacts/<task-id>/x` — is
+ * read as that spelling, not as a subtree of the home: the template says
+ * "under `state/artifacts/<task-id>/`", a coder wrote exactly that, and the
+ * doubled path came back `missing` for a file that existed (FD-5).
  *
  * Two properties, in this order. Inside the home first: a path in the wrong
  * place is wrong whether or not the file happens to be there today, and saying
@@ -79,8 +110,9 @@ export function checkArtifacts(artifacts, opts) {
     const realHome = existsSync(home) ? realOf(home) : home;
     const expectedHome = existsSync(home) ? homeUnder(realOf(root), opts.taskId) : home;
     const homeEscaped = realHome !== expectedHome;
+    const homeSpelling = spellingFromWorkRoot(home, opts.workRoot ?? WORK_ROOT);
     for (const decl of artifacts) {
-        const resolved = path.resolve(home, decl.path);
+        const resolved = path.resolve(home, withinHome(decl.path, homeSpelling));
         if (resolved === home) {
             issues.push({ declared: decl.path, resolved, problem: 'no-path' });
             continue;
@@ -90,7 +122,7 @@ export function checkArtifacts(artifacts, opts) {
             continue;
         }
         if (homeEscaped) {
-            const real = path.resolve(realHome, decl.path);
+            const real = path.resolve(realHome, withinHome(decl.path, homeSpelling));
             issues.push({ declared: decl.path, resolved: real, problem: 'outside-home' });
             continue;
         }

package/factory/orchestrator/dist/budgets.js

@@ -157,11 +157,13 @@ export function loadBudgetPolicy(filePath = BUDGETS_POLICY_PATH) {
  * visible, so plan validation can say "you wrote down a limit nobody can
  * apply" instead of the plan quietly implying otherwise.
  *
- * `max_turns` is null on purpose, and not because the wiring is pending: a turn
- * limit has to live in the dispatch harness, and the Agent tool exposes no
- * turns parameter (agent-interviews.md M-4, answered (c) on 2026-08-05 — the
- * number is carried into the dispatch prompt by the /bs skill, where it is a
- * request to the agent, not a limit on it).
+ * `max_turns` is null on purpose, and not because the wiring is pending: the
+ * turn limit lives in the dispatch harness, which reads the role template's
+ * `maxTurns` (`.claude/agents/<role>.md`) — per role, never per task
+ * (agent-interviews.md M-4, answered (c) on 2026-08-05 and corrected
+ * 2026-09-11 once the cap was measured). A plan cannot raise or lower a
+ * role's ceiling, so a number here would be a second copy the harness never
+ * consults; the /bs dispatch contract restates the template's value instead.
  */
 export const TASK_BUDGET_FIELD_READERS = Object.freeze({
     tokens: 'gate: compared against the result’s token_usage.total_tokens',

package/factory/orchestrator/dist/claims.js

@@ -226,7 +226,33 @@ export function readClaimList(task) {
             'wave for the reason that it may not edit anything. Admitting it defers the mistake to ' +
             'the first out-of-claim edit; task-spec.schema.json requires at least one claim.', { task_id: task.task_id });
     }
-    return { task_id: task.task_id, claims: claims };
+    const promises = readPromiseList(task);
+    return promises === undefined
+        ? { task_id: task.task_id, claims: claims }
+        : { task_id: task.task_id, claims: claims, keeps_exports: promises };
+}
+/**
+ * The `keeps_exports` half of the same door. A promise the wave gate cannot
+ * read must not read as "no promise": that direction is safe for the gate
+ * (the crossing serializes), but it also hides the plan error until a
+ * `plan validate` nobody re-ran. The field is optional; absent stays absent.
+ */
+function readPromiseList(task) {
+    const promises = task.keeps_exports;
+    if (promises === undefined)
+        return undefined;
+    if (!Array.isArray(promises)) {
+        throw new ClaimsError('claims.unreadable-promises', `Task "${task.task_id}" declares keeps_exports as ${describeType(promises)}, not a list ` +
+            'of file paths, so the wave gate cannot tell which crossings it promised to keep. ' +
+            'keeps_exports is a list of repo-relative file paths (task-spec.schema.json).', { task_id: task.task_id, received: describeType(promises) });
+    }
+    const badIndex = promises.findIndex((file) => typeof file !== 'string' || file === '');
+    if (badIndex !== -1) {
+        const received = promises[badIndex] === '' ? 'an empty string' : describeType(promises[badIndex]);
+        throw new ClaimsError('claims.unreadable-promises', `Task "${task.task_id}" declares keeps_exports entry ${badIndex} as ${received}, not a ` +
+            'file path, so the wave gate cannot tell which crossings it promised to keep.', { task_id: task.task_id, index: badIndex, received });
+    }
+    return promises;
 }
 /**
  * Refuse an edge list no traversal can read, before it is traversed.