@cluesmith/codev 3.3.5 → 3.3.7

package/dist/agent-farm/servers/agent-state/route.js

@@ -0,0 +1,170 @@
+/**
+ * `POST /api/agent-lifecycle`: the one write-only agent-state route (Spec 1595,
+ * Constraint 16).
+ *
+ * An agent's lifecycle reporter posts one `AgentLifecycleEvent` per harness hook.
+ * The route validates it strictly against the contract and its limits, resolves
+ * the launch identity to the agent Tower knows, applies it to the in-memory
+ * store, and answers an empty 204. It writes nothing else: no PTY, no mailbox,
+ * no database. There is no read route; state is served on the overview.
+ *
+ * Auth is the existing `isRequestAllowed` choke point in `handleRequest`; this
+ * route is not on the public allowlist. A rejection is a 4xx carrying only an
+ * error code. The reporter ignores every response.
+ */
+import { isAbsolute } from 'node:path';
+import { readBody } from '../../utils/server-utils.js';
+/** Request body cap, in bytes. */
+export const MAX_LIFECYCLE_BODY_BYTES = 8192;
+export const MAX_PATH_LENGTH = 4096;
+export const MAX_NAME_LENGTH = 128;
+export const MAX_SESSION_ID_LENGTH = 128;
+export const MAX_TOOL_LENGTH = 64;
+export const MAX_SUMMARY_LENGTH = 200;
+const EVENT_NAMES = new Set([
+    'session-started',
+    'turn-started',
+    'tool-activity',
+    'needs-input',
+    'turn-ended',
+]);
+const NEEDS_INPUT_KINDS = new Set(['permission', 'question', 'other']);
+const EVENT_KEYS = new Set(['agent', 'sessionId', 'event', 'at', 'needsInput', 'backgroundWork']);
+const BUILDER_KEYS = new Set(['kind', 'worktreePath']);
+const ARCHITECT_KEYS = new Set(['kind', 'workspacePath', 'name']);
+const DETAIL_KEYS = new Set(['kind', 'tool', 'summary']);
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).every(key => allowed.has(key));
+}
+function isBoundedString(value, maxLength) {
+    return typeof value === 'string' && value.length > 0 && value.length <= maxLength;
+}
+function isPlainText(value, maxLength) {
+    return isBoundedString(value, maxLength) && !CONTROL_CHARACTERS.test(value);
+}
+function isAbsolutePath(value) {
+    return isPlainText(value, MAX_PATH_LENGTH) && isAbsolute(value);
+}
+function parseIdentity(value) {
+    if (!isRecord(value))
+        return null;
+    if (value.kind === 'builder') {
+        if (!hasOnlyKeys(value, BUILDER_KEYS) || !isAbsolutePath(value.worktreePath))
+            return null;
+        return { kind: 'builder', worktreePath: value.worktreePath };
+    }
+    if (value.kind === 'architect') {
+        if (!hasOnlyKeys(value, ARCHITECT_KEYS) || !isAbsolutePath(value.workspacePath))
+            return null;
+        if (!isPlainText(value.name, MAX_NAME_LENGTH))
+            return null;
+        return { kind: 'architect', workspacePath: value.workspacePath, name: value.name };
+    }
+    return null;
+}
+function parseDetail(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, DETAIL_KEYS))
+        return null;
+    if (typeof value.kind !== 'string' || !NEEDS_INPUT_KINDS.has(value.kind))
+        return null;
+    const detail = { kind: value.kind };
+    if (value.tool !== undefined) {
+        if (!isPlainText(value.tool, MAX_TOOL_LENGTH))
+            return null;
+        detail.tool = value.tool;
+    }
+    if (value.summary !== undefined) {
+        if (!isPlainText(value.summary, MAX_SUMMARY_LENGTH))
+            return null;
+        detail.summary = value.summary;
+    }
+    return detail;
+}
+/**
+ * Validate a parsed body against the `AgentLifecycleEvent` contract, or `null`.
+ * Strict: unknown keys anywhere are rejected, `needsInput` is accepted only on a
+ * `needs-input` event and `backgroundWork` only on `turn-ended`.
+ */
+export function parseLifecycleEvent(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, EVENT_KEYS))
+        return null;
+    const agent = parseIdentity(value.agent);
+    if (agent === null)
+        return null;
+    if (!isPlainText(value.sessionId, MAX_SESSION_ID_LENGTH))
+        return null;
+    if (typeof value.event !== 'string' || !EVENT_NAMES.has(value.event))
+        return null;
+    if (typeof value.at !== 'number' || !Number.isFinite(value.at) || value.at <= 0)
+        return null;
+    const event = {
+        agent,
+        sessionId: value.sessionId,
+        event: value.event,
+        at: value.at,
+    };
+    if (value.needsInput !== undefined) {
+        if (event.event !== 'needs-input')
+            return null;
+        const detail = parseDetail(value.needsInput);
+        if (detail === null)
+            return null;
+        event.needsInput = detail;
+    }
+    if (value.backgroundWork !== undefined) {
+        if (event.event !== 'turn-ended' || typeof value.backgroundWork !== 'boolean')
+            return null;
+        event.backgroundWork = value.backgroundWork;
+    }
+    return event;
+}
+function reject(res, status, code) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: code }));
+}
+/** Handle one lifecycle report. Auth has already passed in `handleRequest`. */
+export async function handleAgentLifecycle(req, res, deps) {
+    let raw;
+    try {
+        raw = await readBody(req, MAX_LIFECYCLE_BODY_BYTES);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message === 'Request body too large') {
+            reject(res, 413, 'BODY_TOO_LARGE');
+        }
+        else {
+            reject(res, 400, 'UNREADABLE_BODY');
+        }
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        reject(res, 400, 'INVALID_JSON');
+        return;
+    }
+    const event = parseLifecycleEvent(parsed);
+    if (event === null) {
+        reject(res, 400, 'INVALID_EVENT');
+        return;
+    }
+    const agent = deps.resolve(event.agent);
+    if (agent === null) {
+        reject(res, 404, 'UNKNOWN_AGENT');
+        return;
+    }
+    if (deps.store.apply(agent.workspacePath, agent.agentId, event) === 'future') {
+        reject(res, 400, 'AT_IN_FUTURE');
+        return;
+    }
+    res.writeHead(204);
+    res.end();
+}
+//# sourceMappingURL=route.js.map

package/dist/agent-farm/servers/agent-state/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../../src/agent-farm/servers/agent-state/route.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/servers/agent-state/serve.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Serve an agent's attention state on the overview (Spec 1595).
+ *
+ * Gathers Tower's facts about one agent (porch's `blocked`, the caller already
+ * holds; the published liveness; the stored reported activity) and hands them to
+ * the one projection policy in codev-core. Called per request: nothing here is
+ * cached, so a served row is never older than the store and the liveness sweep.
+ */
+import type { ServedAgentState } from '@cluesmith/codev-types';
+import { type AgentStateStore } from './store.js';
+import { type AgentLiveness } from './liveness.js';
+/** The porch facts the overview already computed for the agent. */
+export interface AgentPorchFacts {
+    /** Whether porch reports a requested, pending gate (`detectBlocked` is non-null). */
+    blocked: boolean;
+    blockedSince: string | null;
+    /** The builder's display phase; `''` for an architect. */
+    phase: string;
+}
+export interface ServeAgentStateOptions {
+    store?: AgentStateStore;
+    liveness?: (workspacePath: string, agentId: string) => AgentLiveness | undefined;
+    now?: () => number;
+}
+/**
+ * The served state for the agent `(workspacePath, agentId)`, keyed as the store
+ * and liveness key it: the normalized workspace path and the canonical agent id
+ * (a builder's lowercased role id, an architect's name). `null` when unknown.
+ */
+export declare function serveAgentState(workspacePath: string, agentId: string, porch: AgentPorchFacts, options?: ServeAgentStateOptions): ServedAgentState | null;
+//# sourceMappingURL=serve.d.ts.map

package/dist/agent-farm/servers/agent-state/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/servers/agent-state/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAM/D,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAErE,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;IACjF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAoBD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,sBAA2B,GACnC,gBAAgB,GAAG,IAAI,CAYzB"}

package/dist/agent-farm/servers/agent-state/serve.js

@@ -0,0 +1,49 @@
+/**
+ * Serve an agent's attention state on the overview (Spec 1595).
+ *
+ * Gathers Tower's facts about one agent (porch's `blocked`, the caller already
+ * holds; the published liveness; the stored reported activity) and hands them to
+ * the one projection policy in codev-core. Called per request: nothing here is
+ * cached, so a served row is never older than the store and the liveness sweep.
+ */
+import { projectAgentState, } from '@cluesmith/codev-core/agent-state';
+import { agentStateStore } from './store.js';
+import { getAgentLiveness } from './liveness.js';
+function livenessFact(liveness) {
+    if (liveness === undefined)
+        return null;
+    return { alive: liveness.alive, since: new Date(liveness.since).toISOString() };
+}
+function reportedFact(store, workspacePath, agentId) {
+    const stored = store.get(workspacePath, agentId);
+    if (stored === undefined)
+        return null;
+    const fact = {
+        activity: stored.activity,
+        since: new Date(stored.activitySince).toISOString(),
+        at: new Date(stored.reportedAt).toISOString(),
+        backgroundWork: stored.backgroundWork,
+    };
+    if (stored.needsInput !== undefined)
+        fact.needsInput = stored.needsInput;
+    return fact;
+}
+/**
+ * The served state for the agent `(workspacePath, agentId)`, keyed as the store
+ * and liveness key it: the normalized workspace path and the canonical agent id
+ * (a builder's lowercased role id, an architect's name). `null` when unknown.
+ */
+export function serveAgentState(workspacePath, agentId, porch, options = {}) {
+    const store = options.store ?? agentStateStore;
+    const liveness = options.liveness ?? getAgentLiveness;
+    const now = options.now ?? Date.now;
+    return projectAgentState({
+        blocked: porch.blocked,
+        blockedSince: porch.blockedSince,
+        phase: porch.phase,
+        liveness: livenessFact(liveness(workspacePath, agentId)),
+        reported: reportedFact(store, workspacePath, agentId),
+        now: new Date(now()).toISOString(),
+    });
+}
+//# sourceMappingURL=serve.js.map

package/dist/agent-farm/servers/agent-state/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../../../src/agent-farm/servers/agent-state/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,iBAAiB,GAGlB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAwB,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAsB,MAAM,eAAe,CAAC;AAiBrE,SAAS,YAAY,CAAC,QAAmC;IACvD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;AAClF,CAAC;AAED,SAAS,YAAY,CAAC,KAAsB,EAAE,aAAqB,EAAE,OAAe;IAClF,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACjD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,IAAI,GAAyB;QACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE;QACnD,EAAE,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE;QAC7C,cAAc,EAAE,MAAM,CAAC,cAAc;KACtC,CAAC;IACF,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACzE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,aAAqB,EACrB,OAAe,EACf,KAAsB,EACtB,UAAkC,EAAE;IAEpC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,eAAe,CAAC;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IACtD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,OAAO,iBAAiB,CAAC;QACvB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACxD,QAAQ,EAAE,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC;QACrD,GAAG,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;KACnC,CAAC,CAAC;AACL,CAAC"}

package/dist/agent-farm/servers/agent-state/store.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Tower's in-memory agent activity store (Spec 1595).
+ *
+ * Holds, per agent, the latest activity its harness reported through the
+ * lifecycle route: the harness session id, the activity and when it began, the
+ * hook time of the latest accepted report, whether background work is pending,
+ * and the needs-input detail while (and only while) the agent needs input.
+ *
+ * Memory only, by owner ruling (2026-10-21): nothing here is ever written to
+ * `global.db` or any other store, so no served state can outlive the Tower
+ * process that received its report. A fresh store holds nothing.
+ *
+ * Keys are `(normalized workspace path, canonical agent id)`; callers resolve
+ * both through `resolveAgentIdentity` before touching the store.
+ *
+ * Ordering (SC17): a report older than the stored hook time is ignored; a report
+ * from a different harness session supersedes the stored one only with a newer
+ * hook time; a hook time more than `MAX_FUTURE_SKEW_MS` ahead of Tower's clock is
+ * rejected.
+ *
+ * Background work (SC5): a turn end with `backgroundWork: true` holds the agent
+ * `working`. A later same-session turn end that makes no background-work claim
+ * (the field absent) does not release that hold; a new turn does.
+ */
+import { EventEmitter } from 'node:events';
+import type { AgentActivity, AgentLifecycleEvent, NeedsInputDetail } from '@cluesmith/codev-types';
+/** How far ahead of Tower's clock a report's hook time may be. */
+export declare const MAX_FUTURE_SKEW_MS = 60000;
+/** Raised on every accepted report that changes a served field. */
+export declare const AGENT_STATE_CHANGED = "agent-state-changed";
+/** One agent's reported activity, as held in memory. */
+export interface StoredAgentActivity {
+    /** The harness session the activity belongs to. */
+    sessionId: string;
+    activity: AgentActivity;
+    /** Hook time (epoch ms) at which `activity` began. */
+    activitySince: number;
+    /** Hook time (epoch ms) of the latest report that set the served state; the served `at`. */
+    reportedAt: number;
+    /**
+     * Hook time (epoch ms) of the latest accepted report, including one that
+     * changed nothing served. The ordering watermark (SC17): never behind `reportedAt`.
+     */
+    latestHookAt: number;
+    /** True when the agent ended its turn with its own background work running. */
+    backgroundWork: boolean;
+    /** Present only while `activity` is `needs-input`. */
+    needsInput?: NeedsInputDetail;
+}
+/** The payload of `AGENT_STATE_CHANGED`. */
+export interface AgentStateChange {
+    workspacePath: string;
+    agentId: string;
+}
+/**
+ * What `apply` did with a report: `changed` (accepted, a served field moved),
+ * `unchanged` (accepted, nothing served moved), `stale` (ignored by ordering),
+ * or `future` (rejected: hook time implausibly far ahead).
+ */
+export type ApplyOutcome = 'changed' | 'unchanged' | 'stale' | 'future';
+export declare class AgentStateStore extends EventEmitter {
+    private readonly now;
+    private readonly entries;
+    constructor(now?: () => number);
+    /** The stored activity for an agent, or `undefined` when it has reported nothing. */
+    get(workspacePath: string, agentId: string): StoredAgentActivity | undefined;
+    /** Apply one validated report for a resolved agent. */
+    apply(workspacePath: string, agentId: string, event: AgentLifecycleEvent): ApplyOutcome;
+    /** Every agent the store holds state for. */
+    agents(): AgentStateChange[];
+    /** Forget an agent's reported state (it was removed). */
+    drop(workspacePath: string, agentId: string): void;
+}
+/** Tower's one store. Nothing subscribes to its change event except the broadcaster. */
+export declare const agentStateStore: AgentStateStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/agent-farm/servers/agent-state/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/servers/agent-state/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEnG,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD,wDAAwD;AACxD,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,aAAa,CAAC;IACxB,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,4FAA4F;IAC5F,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,cAAc,EAAE,OAAO,CAAC;IACxB,sDAAsD;IACtD,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAyDxE,qBAAa,eAAgB,SAAQ,YAAY;IAGnC,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;gBAErC,GAAG,GAAE,MAAM,MAAiB;IAIzD,qFAAqF;IACrF,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAI5E,uDAAuD;IACvD,KAAK,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,YAAY;IA8CvF,6CAA6C;IAC7C,MAAM,IAAI,gBAAgB,EAAE;IAS5B,yDAAyD;IACzD,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;CAGnD;AAED,wFAAwF;AACxF,eAAO,MAAM,eAAe,iBAAwB,CAAC"}

package/dist/agent-farm/servers/agent-state/store.js

@@ -0,0 +1,157 @@
+/**
+ * Tower's in-memory agent activity store (Spec 1595).
+ *
+ * Holds, per agent, the latest activity its harness reported through the
+ * lifecycle route: the harness session id, the activity and when it began, the
+ * hook time of the latest accepted report, whether background work is pending,
+ * and the needs-input detail while (and only while) the agent needs input.
+ *
+ * Memory only, by owner ruling (2026-10-21): nothing here is ever written to
+ * `global.db` or any other store, so no served state can outlive the Tower
+ * process that received its report. A fresh store holds nothing.
+ *
+ * Keys are `(normalized workspace path, canonical agent id)`; callers resolve
+ * both through `resolveAgentIdentity` before touching the store.
+ *
+ * Ordering (SC17): a report older than the stored hook time is ignored; a report
+ * from a different harness session supersedes the stored one only with a newer
+ * hook time; a hook time more than `MAX_FUTURE_SKEW_MS` ahead of Tower's clock is
+ * rejected.
+ *
+ * Background work (SC5): a turn end with `backgroundWork: true` holds the agent
+ * `working`. A later same-session turn end that makes no background-work claim
+ * (the field absent) does not release that hold; a new turn does.
+ */
+import { EventEmitter } from 'node:events';
+/** How far ahead of Tower's clock a report's hook time may be. */
+export const MAX_FUTURE_SKEW_MS = 60_000;
+/** Raised on every accepted report that changes a served field. */
+export const AGENT_STATE_CHANGED = 'agent-state-changed';
+function storeKey(workspacePath, agentId) {
+    return `${workspacePath}\0${agentId}`;
+}
+function sameDetail(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a.kind === b.kind && a.tool === b.tool && a.summary === b.summary;
+}
+/** The activity a lifecycle event moves the agent into. */
+function activityFor(event) {
+    switch (event.event) {
+        case 'session-started':
+            return 'idle';
+        case 'turn-started':
+        case 'tool-activity':
+            return 'working';
+        case 'needs-input':
+            return 'needs-input';
+        case 'turn-ended':
+            if (event.backgroundWork === true)
+                return 'working';
+            return 'idle';
+    }
+}
+/**
+ * True when `event` is a turn end that makes no background-work claim, arriving
+ * while the same session's turn end with background work is held. Such a report
+ * carries nothing new: Claude's 60 s `idle_prompt` (the second chance for a lost
+ * turn end) fires while the agent's own background task still runs, and must not
+ * end the background-work hold early. Real-session finding, Phase 8.
+ */
+function repeatsBackgroundTurnEnd(event, previous) {
+    return event.event === 'turn-ended'
+        && event.backgroundWork === undefined
+        && previous !== undefined
+        && previous.sessionId === event.sessionId
+        && previous.backgroundWork;
+}
+/**
+ * The needs-input detail for an accepted `needs-input` report. A report without
+ * a tool (the redundant permission notification names none) keeps the detail
+ * already held for the same episode.
+ */
+function detailFor(event, previous) {
+    const continuesEpisode = previous !== undefined
+        && previous.sessionId === event.sessionId
+        && previous.activity === 'needs-input';
+    if (continuesEpisode && previous.needsInput !== undefined && event.needsInput?.tool === undefined) {
+        return previous.needsInput;
+    }
+    return event.needsInput;
+}
+export class AgentStateStore extends EventEmitter {
+    now;
+    entries = new Map();
+    constructor(now = Date.now) {
+        super();
+        this.now = now;
+    }
+    /** The stored activity for an agent, or `undefined` when it has reported nothing. */
+    get(workspacePath, agentId) {
+        return this.entries.get(storeKey(workspacePath, agentId));
+    }
+    /** Apply one validated report for a resolved agent. */
+    apply(workspacePath, agentId, event) {
+        if (event.at > this.now() + MAX_FUTURE_SKEW_MS)
+            return 'future';
+        const key = storeKey(workspacePath, agentId);
+        const previous = this.entries.get(key);
+        if (previous !== undefined) {
+            if (event.at < previous.latestHookAt)
+                return 'stale';
+            if (event.sessionId !== previous.sessionId && event.at === previous.latestHookAt)
+                return 'stale';
+        }
+        if (previous !== undefined && repeatsBackgroundTurnEnd(event, previous)) {
+            // The hold and its served time stay; only the ordering watermark moves, so a
+            // delayed report older than this one is still ignored.
+            this.entries.set(key, { ...previous, latestHookAt: event.at });
+            return 'unchanged';
+        }
+        const activity = activityFor(event);
+        let activitySince = event.at;
+        if (previous !== undefined && previous.sessionId === event.sessionId && previous.activity === activity) {
+            activitySince = previous.activitySince;
+        }
+        const next = {
+            sessionId: event.sessionId,
+            activity,
+            activitySince,
+            reportedAt: event.at,
+            latestHookAt: event.at,
+            backgroundWork: event.event === 'turn-ended' && event.backgroundWork === true,
+        };
+        if (activity === 'needs-input') {
+            const detail = detailFor(event, previous);
+            if (detail !== undefined)
+                next.needsInput = detail;
+        }
+        this.entries.set(key, next);
+        const changed = previous === undefined
+            || previous.activity !== next.activity
+            || previous.reportedAt !== next.reportedAt
+            || previous.backgroundWork !== next.backgroundWork
+            || !sameDetail(previous.needsInput, next.needsInput);
+        if (!changed)
+            return 'unchanged';
+        const change = { workspacePath, agentId };
+        this.emit(AGENT_STATE_CHANGED, change);
+        return 'changed';
+    }
+    /** Every agent the store holds state for. */
+    agents() {
+        const agents = [];
+        for (const key of this.entries.keys()) {
+            const separator = key.indexOf('\0');
+            agents.push({ workspacePath: key.slice(0, separator), agentId: key.slice(separator + 1) });
+        }
+        return agents;
+    }
+    /** Forget an agent's reported state (it was removed). */
+    drop(workspacePath, agentId) {
+        this.entries.delete(storeKey(workspacePath, agentId));
+    }
+}
+/** Tower's one store. Nothing subscribes to its change event except the broadcaster. */
+export const agentStateStore = new AgentStateStore();
+//# sourceMappingURL=store.js.map

package/dist/agent-farm/servers/agent-state/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../../src/agent-farm/servers/agent-state/store.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/servers/decisions/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/servers/decisions/parse.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,YAAY,EAEZ,cAAc,EAEd,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAoD,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAGjG,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,qDAAqD;IACrD,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;IACnB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AA0CD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,MAAM,GAAG,cAAc,EAAE,CAuBvE;AAmGD,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAgD5D;AA8DD,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAmB5F"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/servers/decisions/parse.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EACV,YAAY,EAEZ,cAAc,EAGd,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAoD,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAGjG,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,qDAAqD;IACrD,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;IACnB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AA4DD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,MAAM,GAAG,cAAc,EAAE,CAuBvE;AAmGD,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAiD5D;AA+DD,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAmB5F"}

package/dist/agent-farm/servers/decisions/parse.js

@@ -1,11 +1,20 @@
 // Decisions file parser (Spec 1819).
 //
-// A pure function from the decisions file's text to its read model. The file is
-// the only state: this runs on every read, nothing is cached. Structure comes
-// from `grammar.ts`; this module adds the format's conventions:
+// A function from the decisions file's text, and the clock, to its read model. The
+// file is the only state: this runs on every read, nothing is cached. The clock
+// enters only through time-only stamps, which are read as today in their zone
+// (#1836), so the same text can parse to different instants on different days:
+//   - `version` (the client's cache key) hashes the text alone and does not cover
+//     that: a client keeps the instants it has until the file changes.
+//   - `splice.ts`'s `verify()` re-parses at a later moment than the parse it checks
+//     against; it is safe only because it compares no stamps.
+// Structure comes from `grammar.ts`; this module adds the format's conventions:
 //   - `## Open` / `## Ruled` sections; items are `###` headings inside `## Open`,
 //     running to the next heading of level 1–3 (or end of file).
-//   - item id = the heading's first token; ` · ` separates id, stamp and question.
+//   - item id = the heading's first token; ` · ` separates id, stamp and question. A first
+//     part that is not a stamp belongs to the question.
+//   - a `_Zone: <zone>_` line in the header (above the first `##`) is the zone of every
+//     stamp that names none.
 //   - options = backticked words on the `**Your word:**` line, first recommended; an
 //     option with no `= …` there takes its description from the body's `**Options:**`.
 //   - current ruling = everything after the `**Your word:**` line, verbatim.
@@ -16,6 +25,7 @@ import { createHash } from 'node:crypto';
 import { YOUR_WORD_LABEL, classifyLines, detectLineEnding } from './grammar.js';
 import { resolveStamp } from './stamp.js';
 const SEPARATOR = ' · ';
+const ZONE_LINE_RE = /^ {0,3}_Zone:[ \t]*(\S+?)\.?_[ \t]*$/;
 const ASKED_RE = /^ {0,3}- \*\*You asked \(([^)]*)\):\*\*[ \t]*(.*)$/;
 const ANSWER_RE = /^ {0,3}- \*\*(.+?)['’]s answer \(([^)]*)\):\*\*[ \t]*(.*)$/;
 const CONTINUATION_INDENT_RE = /^(?: {2}|\t)/;
@@ -42,17 +52,36 @@ function joinTrimmed(lines) {
     return lines.slice(from, to).map(l => l.text).join('\n');
 }
 /**
- * Split a heading's text into id, stamp text and question: the first token is the id;
- * after a ` · `, the first part is the stamp and the rest (re-joined) the question. A
- * heading without separators has a question and no stamp.
+ * The file's zone: the one `_Zone: <zone>_` line above the first `##` heading. None, or
+ * more than one, gives no file zone.
  */
-function splitHeading(headingText) {
+function fileZone(lines) {
+    const zones = [];
+    for (const line of lines) {
+        if (line.headingLevel >= 2)
+            break;
+        const zone = line.fenced ? null : ZONE_LINE_RE.exec(line.text);
+        if (zone)
+            zones.push(zone[1]);
+    }
+    return zones.length === 1 ? zones[0] : null;
+}
+/**
+ * Split a heading's text into id, stamp and question: the first token is the id; after a
+ * ` · `, the first part is the stamp and the rest (re-joined) the question. A heading
+ * without separators, or whose first part is not a stamp, has a question and no stamp.
+ */
+function splitHeading(headingText, zone) {
     const id = headingText.split(/\s+/)[0] ?? '';
     const rest = headingText.slice(id.length);
     if (!rest.startsWith(SEPARATOR))
-        return { id, stampText: null, question: rest.trim() };
-    const [stampText, ...questionParts] = rest.slice(SEPARATOR.length).split(SEPARATOR);
-    return { id, stampText: stampText.trim(), question: questionParts.join(SEPARATOR).trim() };
+        return { id, stamp: null, question: rest.trim() };
+    const afterId = rest.slice(SEPARATOR.length);
+    const [stampText, ...questionParts] = afterId.split(SEPARATOR);
+    const stamp = resolveStamp(stampText.trim(), zone);
+    if (!stamp)
+        return { id, stamp: null, question: afterId.trim() };
+    return { id, stamp, question: questionParts.join(SEPARATOR).trim() };
 }
 /**
  * Options from a `**Your word:**` line. An option starts at a backticked span at the
@@ -202,6 +231,7 @@ export function parseDecisions(text) {
     if (ruledHeadings.length > 1)
         problems.push('ruled-multiple');
     const offsetOf = (lineIndex) => (lineIndex < lines.length ? lines[lineIndex].start : text.length);
+    const zone = fileZone(lines);
     const items = [];
     for (const open of openHeadings) {
         const openEnd = sectionEnd(open.index);
@@ -215,7 +245,7 @@ export function parseDecisions(text) {
                     break;
                 }
             }
-            items.push(parseItem(text, lines, i, endLine, offsetOf));
+            items.push(parseItem(text, lines, i, endLine, offsetOf, zone));
             i = endLine - 1;
         }
     }
@@ -232,9 +262,9 @@ export function parseDecisions(text) {
     const ruledMarkdown = ruled ? joinTrimmed(lines.slice(ruled.index + 1, sectionEnd(ruled.index))) : '';
     return { lines, eol: detectLineEnding(lines), items, ruledMarkdown, problems, version: sha256(text) };
 }
-function parseItem(text, lines, headingLine, endLine, offsetOf) {
+function parseItem(text, lines, headingLine, endLine, offsetOf, zone) {
     const heading = lines[headingLine];
-    const { id, stampText, question } = splitHeading(heading.headingText);
+    const { id, stamp, question } = splitHeading(heading.headingText, zone);
     const start = heading.start;
     const end = offsetOf(endLine);
     const itemLines = lines.slice(headingLine + 1, endLine);
@@ -268,7 +298,7 @@ function parseItem(text, lines, headingLine, endLine, offsetOf) {
     }
     return {
         id,
-        stamp: stampText === null ? null : resolveStamp(stampText),
+        stamp,
         question,
         bodyMarkdown: joinTrimmed(rest),
         options,