@juzser/blacksmith 0.1.0 → 0.2.0

package/factory/orchestrator/dist/db/queries.js

@@ -6,7 +6,7 @@
 // is the normal case; a session filter is for debugging one run).
 import { and, eq, gte, inArray, lte } from 'drizzle-orm';
 import { isOperatorActor } from '../actors.js';
-import { foldAgents, liveAgents as foldLiveAgents, REGISTRY_EVENT_TYPES, } from '../agents-registry.js';
+import { foldAgents, liveAgents as foldLiveAgents, isWorkingAt, REGISTRY_EVENT_TYPES, } from '../agents-registry.js';
 import { compareLogOrder, isLaterEvent, parseEventId, ROOT_EVENT_TYPE } from '../events.js';
 import { waveLayers } from '../graph.js';
 import { judgeFailureKind } from '../providers/types.js';
@@ -514,14 +514,19 @@ function allAgentsForScope(db, scope) {
  * Ties on `lastEventAt` break on `sessionId` so the order is stable under the
  * dashboard's 5s poll rather than shuffling between renders.
  */
-export function runningSessions(db, scope = {}) {
+export function runningSessions(db, scope = {}, opts = {}) {
+    const nowIso = opts.nowIso ?? new Date().toISOString();
     const sessionCond = scopedToSessions(sessions.sessionId, scope);
     const rows = sessionCond
         ? db.select().from(sessions).where(sessionCond).all()
         : db.select().from(sessions).all();
     const liveBySession = new Map();
+    const workingBySession = new Map();
     for (const a of allAgentsForScope(db, scope)) {
         liveBySession.set(a.sessionId, (liveBySession.get(a.sessionId) ?? 0) + 1);
+        if (isWorkingAt(a.dispatchedAt, nowIso)) {
+            workingBySession.set(a.sessionId, (workingBySession.get(a.sessionId) ?? 0) + 1);
+        }
     }
     const projectsBySession = new Map();
     for (const t of allTasksForScope(db, scope)) {
@@ -555,6 +560,7 @@ export function runningSessions(db, scope = {}) {
         lastEventAt: s.lastEventAt,
         eventCount: s.eventCount,
         liveAgentCount: liveBySession.get(s.sessionId) ?? 0,
+        workingAgentCount: workingBySession.get(s.sessionId) ?? 0,
         lastEventType: lastEvent.get(s.sessionId)?.eventType ?? null,
         projects: [...(projectsBySession.get(s.sessionId) ?? [])].sort(),
     }))
@@ -621,8 +627,14 @@ function inFlightEpics(taskRows, closed) {
             .map((t) => t.epicId)),
     ].sort();
 }
-/** One project's overview slice, computed by the same logic overview() itself uses (no drift). */
-function projectSummary(db, project, baseScope) {
+/**
+ * One project's overview slice, computed by the same logic overview() itself
+ * uses (no drift). `nowIso` is the caller's single instant, not a fresh
+ * read: overview() hands every per-project summary the same "now" it used
+ * for its own counts, so the project rows and the global card can never
+ * disagree about which agents are working.
+ */
+function projectSummary(db, project, baseScope, nowIso) {
     const scope = { ...baseScope, project };
     const liveRows = allAgentsForScope(db, scope);
     const taskRows = allTasksForScope(db, scope);
@@ -637,6 +649,7 @@ function projectSummary(db, project, baseScope) {
     return {
         project,
         liveAgentCount: liveRows.length,
+        workingAgentCount: liveRows.filter((a) => isWorkingAt(a.dispatchedAt, nowIso)).length,
         epicsInFlight,
         tokensSpent,
         tokensBudget,
@@ -664,7 +677,7 @@ const SNAPSHOT_EVENT_TYPES = REGISTRY_EVENT_TYPES;
  * project, so its agent stayed in the live count and vanished from the
  * historical one, and the StatCard reported an arrival that never happened.
  */
-function liveAgentCountAt(db, scope, cutoffIso) {
+function liveAgentsAt(db, scope, cutoffIso) {
     const conds = [lte(eventsRaw.ts, cutoffIso), inArray(eventsRaw.eventType, SNAPSHOT_EVENT_TYPES)];
     const sessionCond = scopedToSessions(eventsRaw.sessionId, scope);
     if (sessionCond)
@@ -690,9 +703,25 @@ function liveAgentCountAt(db, scope, cutoffIso) {
     }));
     const live = foldLiveAgents(foldAgents(storedEvents));
     if (scope.project === undefined)
-        return live.length;
+        return live;
     const scopedTaskIds = new Set(allTasksForScope(db, scope).map((t) => t.taskId));
-    return live.filter((a) => a.taskId !== null && scopedTaskIds.has(a.taskId)).length;
+    return live.filter((a) => a.taskId !== null && scopedTaskIds.has(a.taskId));
+}
+function liveAgentCountAt(db, scope, cutoffIso) {
+    return liveAgentsAt(db, scope, cutoffIso).length;
+}
+/**
+ * The "working" end of workingAgentCountDelta5m's subtraction: the agents
+ * live as of `cutoffIso` (the very re-fold liveAgentCountAt does, project
+ * scoping included) that were ALSO within DEFAULT_STALE_HOURS of dispatch
+ * *at that cutoff*. Judging the historical rows against today's clock
+ * instead would be D-170 again in a new disguise — the "now" end would
+ * apply a 4h window and the "ago" end a 4h05m one, and an agent that
+ * stalled since the cutoff would read as no change.
+ */
+function workingAgentCountAt(db, scope, cutoffIso) {
+    return liveAgentsAt(db, scope, cutoffIso).filter((a) => isWorkingAt(a.dispatchedAt, cutoffIso))
+        .length;
 }
 /**
  * Total tokens spent (task-result-recorded token_usage) across `epicByTask`'s tasks, as of `cutoffIso`.
@@ -781,7 +810,14 @@ function tokensBudgetedAt(db, scope, cutoffIso, epicByTask) {
     return total;
 }
 export function overview(db, scope = {}, opts = {}) {
+    // One instant for everything this call reports. runningSessions(), the
+    // per-project summaries and the deltas each take the clock as an argument
+    // rather than reading it, so a request that straddles a threshold cannot
+    // count an agent as working in one field and stalled in the next.
+    const now = opts.nowIso ? new Date(opts.nowIso) : new Date();
+    const nowIso = now.toISOString();
     const liveRows = allAgentsForScope(db, scope);
+    const workingRows = liveRows.filter((a) => isWorkingAt(a.dispatchedAt, nowIso));
     const taskRows = allTasksForScope(db, scope);
     const closedEpics = closedEpicsForScope(db, scope);
     const epicsInFlight = inFlightEpics(taskRows, closedEpics);
@@ -835,12 +871,12 @@ export function overview(db, scope = {}, opts = {}) {
         // Milestones carry no session_id and milestoneProgressRows() never
         // filters them by one, so they join the list under a session scope too.
         const declaredRows = db.select({ project: milestones.project }).from(milestones).all();
-        projects = distinctProjects(allTaskRowsUnfiltered, declaredRows).map((p) => projectSummary(db, p, scope));
+        projects = distinctProjects(allTaskRowsUnfiltered, declaredRows).map((p) => projectSummary(db, p, scope, nowIso));
     }
-    const now = opts.nowIso ? new Date(opts.nowIso) : new Date();
     const fiveMinAgo = new Date(now.getTime() - 5 * 60 * 1000).toISOString();
     const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000).toISOString();
     const liveAgentCountDelta5m = liveRows.length - liveAgentCountAt(db, scope, fiveMinAgo);
+    const workingAgentCountDelta5m = workingRows.length - workingAgentCountAt(db, scope, fiveMinAgo);
     const epicByTask = new Map(taskRows.filter((t) => t.epicId !== null).map((t) => [t.taskId, t.epicId]));
     const totalBudgetNow = [...budgetByEpic.values()].reduce((s, v) => s + v, 0);
     const totalSpentNow = [...spentByEpic.values()].reduce((s, v) => s + v, 0);
@@ -873,7 +909,9 @@ export function overview(db, scope = {}, opts = {}) {
             dispatchedAt: a.dispatchedAt,
         })),
         liveAgentCount: liveRows.length,
-        runningSessions: runningSessions(db, scope),
+        workingAgentCount: workingRows.length,
+        stalledAgentCount: liveRows.length - workingRows.length,
+        runningSessions: runningSessions(db, scope, { nowIso }),
         epicsInFlight,
         closedEpics,
         tokensByEpic,
@@ -881,6 +919,7 @@ export function overview(db, scope = {}, opts = {}) {
         milestoneProgress: milestoneProgressRows(db, scope),
         recentDispatches,
         liveAgentCountDelta5m,
+        workingAgentCountDelta5m,
         budgetUsedPctPointDelta1h,
         ...(projects ? { projects } : {}),
     };
@@ -959,6 +998,12 @@ export const FREE_TIMELINE_EVENT_TYPES = [
     'audit-cut',
     'audit-resolved',
     'audit-closed',
+    // The integration PR run.md step 17 opens, appended by hand through `smith
+    // event append` under `<epic>/integration`. It is the epic's terminal
+    // deliverable -- the one thing the operator is asked to merge -- and the
+    // only event written after `epic-closed`, so without it the timeline of a
+    // closed epic ends at the closing and never shows what the closing was for.
+    'integration-pr-opened',
 ];
 let cachedTaxonomy;
 /**
@@ -1174,7 +1219,8 @@ function worstSeverity(severities) {
  * task_status, tagged with case/origin/worst-open-finding severity plus
  * (Phase 6b) title/agent-role/milestone.
  */
-export function kanban(db, epicId, scope = {}) {
+export function kanban(db, epicId, scope = {}, opts = {}) {
+    const nowIso = opts.nowIso ?? new Date().toISOString();
     const epicCond = epicId !== undefined ? eq(tasks.epicId, epicId) : undefined;
     const sessionCond = scopedToSessions(tasks.sessionId, scope);
     const taskConds = [epicCond, sessionCond].filter((c) => c !== undefined);
@@ -1221,6 +1267,18 @@ export function kanban(db, epicId, scope = {}) {
                 modelTier: d.modelTier,
             });
     }
+    // Who is still on each task, from the agents rows (live only — see
+    // allAgentsForScope). A working row wins over a stalled one on the same
+    // task for the reason flowGraph gives: the chip says who is on the task.
+    const activityByTask = new Map();
+    for (const a of allAgentsForScope(db, scope)) {
+        if (!a.taskId)
+            continue;
+        if (isWorkingAt(a.dispatchedAt, nowIso))
+            activityByTask.set(a.taskId, 'working');
+        else if (!activityByTask.has(a.taskId))
+            activityByTask.set(a.taskId, 'stalled');
+    }
     // epicId -> milestoneId, from roadmap.md's milestones table.
     const milestoneRows = db.select().from(milestones).all();
     const milestoneByEpic = new Map();
@@ -1237,6 +1295,7 @@ export function kanban(db, epicId, scope = {}) {
             title: t.objective,
             agentRole: latestAgentRoleByTask.get(t.taskId)?.agentRole ?? null,
             agentModelTier: latestAgentRoleByTask.get(t.taskId)?.modelTier ?? null,
+            agentActivity: activityByTask.get(t.taskId) ?? null,
             milestoneId: t.epicId ? (milestoneByEpic.get(t.epicId) ?? null) : null,
             tags: {
                 case: t.caseTag,
@@ -1462,7 +1521,8 @@ export function analytics(db, scope = {}) {
  * stack.md: "no separate layout library" — this IS that orchestrator
  * utility, exposed via this query/endpoint per the same doc's instruction).
  */
-export function flowGraph(db, filter = {}) {
+export function flowGraph(db, filter = {}, opts = {}) {
+    const nowIso = opts.nowIso ?? new Date().toISOString();
     let taskRows = allTasksForScope(db, filter);
     if (filter.epicId)
         taskRows = taskRows.filter((t) => t.epicId === filter.epicId);
@@ -1526,9 +1586,17 @@ export function flowGraph(db, filter = {}) {
     const scopedEdges = edgeRows.filter((e) => taskIds.has(e.taskId) && taskIds.has(e.dependsOn));
     const liveRows = allAgentsForScope(db, filter);
     const liveRoleByTask = new Map();
+    // The same last-write-wins walk, over the working rows only. Where a task
+    // carries both a stalled live row and a working one, the working role is
+    // the one to name: the marker says who is on the task, not who was
+    // dispatched to it most recently.
+    const workingRoleByTask = new Map();
     for (const a of liveRows) {
-        if (a.taskId)
-            liveRoleByTask.set(a.taskId, a.agentRole);
+        if (!a.taskId)
+            continue;
+        liveRoleByTask.set(a.taskId, a.agentRole);
+        if (isWorkingAt(a.dispatchedAt, nowIso))
+            workingRoleByTask.set(a.taskId, a.agentRole);
     }
     const waveMap = waveLayers([...taskIds], scopedEdges.map((e) => ({ task: e.taskId, dependsOn: e.dependsOn })));
     const nodes = taskRows.map((t) => ({
@@ -1536,6 +1604,7 @@ export function flowGraph(db, filter = {}) {
         taskStatus: t.taskStatus,
         title: t.objective,
         liveAgentRole: liveRoleByTask.get(t.taskId) ?? null,
+        workingAgentRole: workingRoleByTask.get(t.taskId) ?? null,
         planVersion: t.planVersion,
         wave: waveMap.get(t.taskId) ?? 0,
     }));

package/factory/orchestrator/dist/db/schema.js

@@ -189,6 +189,13 @@ export const findings = sqliteTable('findings', {
     raisedAt: text('raised_at').notNull(),
     updatedAt: text('updated_at').notNull(),
     project: text('project'), // Phase 6b — see eventsRaw's project comment above.
+    // What a spec finding is about (findings.ts SpecRef). The scope is filled
+    // in from findingScope(), so an absent field lands as 'diff' rather than
+    // as a null the reader has to know the default for; the two spec_ref
+    // columns are null on every diff finding because there is no criterion.
+    findingScope: text('finding_scope').notNull().default('diff'),
+    specPlanVersion: integer('spec_plan_version'),
+    criterionRef: text('criterion_ref'),
 }, (t) => [
     index('findings_session_idx').on(t.sessionId),
     index('findings_task_idx').on(t.taskId),

package/factory/orchestrator/dist/events.js

@@ -203,10 +203,20 @@ async function readEventsAtPath(filePath, sessionId) {
         .trimEnd()
         .split('\n')
         .filter((line) => line.length > 0);
-    return lines.map((line, index) => ({
-        event_id: `${sessionId}#${index}`,
-        record: JSON.parse(line),
-    }));
+    return lines.map((line, index) => {
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch (err) {
+            // A bare SyntaxError says "Unexpected token" and nothing else: not which
+            // log, not which line. The dashboard prints this for every session it
+            // then fails to fold (the global folds read every log), so the message
+            // has to carry the path the operator needs to open.
+            throw new EventError('events.unreadable-session-log', `Line ${index + 1} of ${filePath} is not JSON, so session "${sessionId}" cannot be read: ${errorText(err)}.`, { session_id: sessionId, path: filePath, line: index + 1 });
+        }
+        return { event_id: `${sessionId}#${index}`, record };
+    });
 }
 /**
  * Per-log serialization *inside one process*: concurrent appendEvent calls on
@@ -504,7 +514,31 @@ function validatePayloadDimensions(taxonomy, record) {
 const TYPED_PAYLOAD_SCHEMAS = {
     'finding-raised': 'finding',
 };
+/**
+ * The one field of a `task-result-recorded` payload a reader iterates. The
+ * projector writes `artifacts[]` into rows inside the session's transaction,
+ * so an object here (csb-audit-1#100 carried `{ claude_half, external_half,
+ * repair_brief }`) rolled back the whole session and the dashboard drew
+ * nothing for it. Pinning only this field is deliberate: the full result
+ * schema is not enforced on the event, because real logs carry many
+ * hand-written result payloads that no reader rehydrates -- refusing them
+ * would refuse history for a shape nothing reads.
+ */
+function validateResultArtifactsShape(record) {
+    if (record.event_type !== 'task-result-recorded')
+        return;
+    const payload = record.payload;
+    const artifacts = payload?.artifacts;
+    if (artifacts === undefined || Array.isArray(artifacts))
+        return;
+    throw new EventError('events.invalid-typed-payload', 'Event payload for "task-result-recorded" carries an `artifacts` that is not an array. The projector iterates this list to write artifact rows, so any other shape becomes a crash that rolls back the whole session rather than an error here.', {
+        event_type: record.event_type,
+        schema: 'result',
+        errors: [{ path: '/artifacts', message: `must be an array, got ${typeof artifacts}` }],
+    });
+}
 function validateTypedPayload(schemas, taxonomy, record) {
+    validateResultArtifactsShape(record);
     const schemaName = TYPED_PAYLOAD_SCHEMAS[record.event_type];
     if (schemaName === undefined)
         return;
@@ -1013,3 +1047,53 @@ export function filterEvents(events, filter) {
         return true;
     });
 }
+/**
+ * How often `--follow` re-reads a log it is following.
+ *
+ * A second is well under the interval an operator perceives as lag, and a
+ * re-read costs what one `smith event tail` costs -- the poll is not what
+ * makes a busy factory expensive. There is no flag for it on purpose: a
+ * knob no answer depends on is a knob every reader of `--help` pays for.
+ */
+export const FOLLOW_TICK_MS = 1000;
+/**
+ * The events in `events` that `seen` does not already hold, in `events`'
+ * order.
+ *
+ * The cursor is a set of ids rather than a count because `--lineage` merges
+ * several logs by `ts` (mergeSessionLogs above): an event appended now can
+ * sort BEHIND one already printed, and a stream cannot un-print. A length
+ * cursor would either re-emit the tail or skip the new event outright, and
+ * both are worse than holding the ids -- which cost what the read they came
+ * from already cost.
+ */
+export function unseenEvents(events, seen) {
+    return events.filter((event) => !seen.has(event.event_id));
+}
+/**
+ * Read, emit what is new, sleep, repeat -- until `shouldContinue` says stop.
+ *
+ * The seams are runDaemon's, for the same reason: the contract of a loop is
+ * what it does AROUND the read, and a loop that owns its own clock can only
+ * be tested by waiting. `sleep` is where an interrupt lands, so the caller
+ * that wires SIGINT resolves the sleep rather than waiting out the interval.
+ *
+ * Returns how many events it emitted, which is the only thing about a stream
+ * worth having after it ends.
+ */
+export async function followEvents(opts) {
+    const intervalMs = opts.intervalMs ?? FOLLOW_TICK_MS;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const shouldContinue = opts.shouldContinue ?? (() => true);
+    const seen = new Set(opts.seen ?? []);
+    let emitted = 0;
+    while (shouldContinue()) {
+        for (const event of unseenEvents(await opts.read(), seen)) {
+            seen.add(event.event_id);
+            opts.emit(event);
+            emitted += 1;
+        }
+        await sleep(intervalMs);
+    }
+    return emitted;
+}