@cluesmith/codev 3.3.2 → 3.3.3

package/dist/agent-farm/db/mailbox.d.ts

@@ -21,7 +21,7 @@
  *   that is still `held`.
  */
 import type Database from 'better-sqlite3';
-import type { DbMailbox, MailboxReason } from './types.js';
+import type { DbMailbox, MailboxGateDetail, MailboxReason } from './types.js';
 /**
  * Fields a caller supplies to persist a new held row. The repository fills in the
  * id, `held` status, `escalated=0`, and the timestamps.
@@ -126,13 +126,32 @@ export declare function heldSummaryForWorkspace(db: Database.Database, workspace
  */
 export declare function markDelivered(db: Database.Database, id: string, now?: number): boolean;
 /**
- * Refresh the why-held `reason` on a still-held row (informational — the value
- * `afx inbox` shows and the send response reports). Only touches `held` rows, so
- * it can never relabel or resurrect a terminal row. Returns true if a held row was
- * updated. The delivery pass calls this so a held row's reason tracks the current
- * gate verdict (e.g. `busy` → `no-live-pty` when the terminal dies).
+ * Refresh the why-held verdict — `reason` AND its gate `detail` — on a still-held row
+ * (informational: the values `afx inbox`, the send response, the escalation broadcast and the
+ * owner starvation notice report). Only touches `held` rows, so it can never relabel or
+ * resurrect a terminal row. Returns true if a held row was updated. The delivery pass calls
+ * this so a held row's verdict tracks the current gate verdict (e.g. `busy` → `no-live-pty`
+ * when the terminal dies).
+ *
+ * ONE statement, not two (Issue #1482): the pair is a single verdict, and writing it in two
+ * updates would leave a window — and a second `updated_at` bump — where a reader could see a
+ * new reason beside the previous reason's detail. Callers that hold for a NON-gate cause pass
+ * `detail: null` so a stale detail can never outlive the verdict that produced it.
+ *
+ * `updated_at` therefore keeps meaning "when this row's verdict last MOVED", and that is
+ * enforced HERE, by the `(reason IS NOT ? OR detail IS NOT ?)` predicate — not merely by the
+ * callers that happen to check first. The delivery pass does guard before calling (see
+ * `mailbox-delivery.ts`), but a guard living only at the call site is one new caller away from
+ * silently breaking the starvation notice, which reads elapsed time off `updated_at` to say how
+ * long a composer has been occupied. `IS NOT` rather than `<>` because both columns are
+ * nullable and SQL's `<>` is not null-safe: `NULL <> NULL` is NULL, not false, so a
+ * `null`→`null` no-op would slip through the predicate and bump the timestamp anyway.
+ *
+ * Returns true only when a held row's verdict actually moved. A repeat of the same pair, a
+ * terminal row, and an unknown id are all `false` — callers wanting "does this row exist"
+ * should ask {@link getById}, not this.
  */
-export declare function setHeldReason(db: Database.Database, id: string, reason: MailboxReason | null, now?: number): boolean;
+export declare function setHeldVerdict(db: Database.Database, id: string, reason: MailboxReason | null, detail: MailboxGateDetail | null, now?: number): boolean;
 /**
  * Flag a still-held row as escalated — **visibility only, NEVER affects delivery**. The
  * drainer's escalation pass calls this when a row crosses the escalation age, then emits
@@ -141,6 +160,20 @@ export declare function setHeldReason(db: Database.Database, id: string, reason:
  * row is untouched. Returns true if it flipped.
  */
 export declare function markEscalated(db: Database.Database, id: string, now?: number): boolean;
+/**
+ * Flag an already-DELIVERED row as escalated (Issue #1584) — visibility only, and the
+ * counterpart to {@link markEscalated} for the one case that flags a row *after* it has left
+ * the held set: a delivery whose write completed but whose echo never confirmed.
+ *
+ * A separate function rather than a relaxed guard on {@link markEscalated}, because that one's
+ * held-only contract is what makes the drainer's escalation pass safe to call blindly. Here the
+ * ordering is the point: the row is marked `delivered` FIRST (that commit is what makes the
+ * write un-repeatable even across a crash), so by the time the verdict is known the held-only
+ * guard would silently no-op and the flag would be lost.
+ *
+ * Delivered-only and idempotent (the `escalated = 0` guard). Returns true if it flipped.
+ */
+export declare function markEscalatedDelivered(db: Database.Database, id: string, now?: number): boolean;
 /**
  * Supersede-key prefix for architect starvation notices (Spec 1313 round 3, change 3). A
  * notice row carries `${NOTICE_SUPERSEDE_PREFIX}<starving-agent>` so (a) one pending notice
@@ -163,6 +196,13 @@ export interface StarvingAgent {
     count: number;
     /** Representative why-held reason (held rows for one agent share the gate's verdict). */
     reason: MailboxReason | null;
+    /**
+     * Representative gate detail beside {@link reason} (Issue #1482) — the same MAX() aggregate,
+     * for the same reason: an agent's held rows all carry the verdict of the last delivery pass.
+     * It is what lets the owner starvation notice distinguish "a human is at the composer" from
+     * "the classifier cannot verify this composer", which have different remedies.
+     */
+    detail: MailboxGateDetail | null;
 }
 /**
  * Per-agent view of currently-STARVING mail (Spec 1313 round 3, change 3): agents with at

package/dist/agent-farm/db/mailbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mailbox.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/mailbox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mailbox.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/mailbox.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/db/mailbox.js

@@ -24,11 +24,11 @@ import { randomUUID } from 'node:crypto';
 const INSERT_SQL = `
   INSERT INTO mailbox (
     id, workspace_path, to_agent, terminal_id, from_agent, from_workspace,
-    body, formatted_message, no_enter, status, reason, supersede_key,
+    body, formatted_message, no_enter, status, reason, detail, supersede_key,
     escalated, not_before, created_at, updated_at, resolved_at
   ) VALUES (
     @id, @workspace_path, @to_agent, @terminal_id, @from_agent, @from_workspace,
-    @body, @formatted_message, @no_enter, @status, @reason, @supersede_key,
+    @body, @formatted_message, @no_enter, @status, @reason, @detail, @supersede_key,
     @escalated, @not_before, @created_at, @updated_at, @resolved_at
   )
 `;
@@ -45,6 +45,10 @@ function buildRow(input, now) {
         no_enter: input.noEnter ? 1 : 0,
         status: 'held',
         reason: input.reason ?? null,
+        // A brand-new row has no gate verdict yet: the only reasons available at enqueue are the
+        // non-gate ones (`no-live-pty` from holdAndRespond), which never carry a detail. The first
+        // delivery pass sets it (Issue #1482).
+        detail: null,
         supersede_key: input.supersedeKey ?? null,
         escalated: 0,
         not_before: input.notBefore ?? null,
@@ -163,21 +167,41 @@ export function heldSummaryForWorkspace(db, workspacePath, now = Date.now()) {
  */
 export function markDelivered(db, id, now = Date.now()) {
     const info = db
-        .prepare("UPDATE mailbox SET status = 'delivered', reason = NULL, updated_at = ?, resolved_at = ? WHERE id = ? AND status = 'held'")
+        .prepare("UPDATE mailbox SET status = 'delivered', reason = NULL, detail = NULL, updated_at = ?, resolved_at = ? WHERE id = ? AND status = 'held'")
         .run(now, now, id);
     return info.changes > 0;
 }
 /**
- * Refresh the why-held `reason` on a still-held row (informational — the value
- * `afx inbox` shows and the send response reports). Only touches `held` rows, so
- * it can never relabel or resurrect a terminal row. Returns true if a held row was
- * updated. The delivery pass calls this so a held row's reason tracks the current
- * gate verdict (e.g. `busy` → `no-live-pty` when the terminal dies).
+ * Refresh the why-held verdict — `reason` AND its gate `detail` — on a still-held row
+ * (informational: the values `afx inbox`, the send response, the escalation broadcast and the
+ * owner starvation notice report). Only touches `held` rows, so it can never relabel or
+ * resurrect a terminal row. Returns true if a held row was updated. The delivery pass calls
+ * this so a held row's verdict tracks the current gate verdict (e.g. `busy` → `no-live-pty`
+ * when the terminal dies).
+ *
+ * ONE statement, not two (Issue #1482): the pair is a single verdict, and writing it in two
+ * updates would leave a window — and a second `updated_at` bump — where a reader could see a
+ * new reason beside the previous reason's detail. Callers that hold for a NON-gate cause pass
+ * `detail: null` so a stale detail can never outlive the verdict that produced it.
+ *
+ * `updated_at` therefore keeps meaning "when this row's verdict last MOVED", and that is
+ * enforced HERE, by the `(reason IS NOT ? OR detail IS NOT ?)` predicate — not merely by the
+ * callers that happen to check first. The delivery pass does guard before calling (see
+ * `mailbox-delivery.ts`), but a guard living only at the call site is one new caller away from
+ * silently breaking the starvation notice, which reads elapsed time off `updated_at` to say how
+ * long a composer has been occupied. `IS NOT` rather than `<>` because both columns are
+ * nullable and SQL's `<>` is not null-safe: `NULL <> NULL` is NULL, not false, so a
+ * `null`→`null` no-op would slip through the predicate and bump the timestamp anyway.
+ *
+ * Returns true only when a held row's verdict actually moved. A repeat of the same pair, a
+ * terminal row, and an unknown id are all `false` — callers wanting "does this row exist"
+ * should ask {@link getById}, not this.
  */
-export function setHeldReason(db, id, reason, now = Date.now()) {
+export function setHeldVerdict(db, id, reason, detail, now = Date.now()) {
     const info = db
-        .prepare("UPDATE mailbox SET reason = ?, updated_at = ? WHERE id = ? AND status = 'held'")
-        .run(reason, now, id);
+        .prepare("UPDATE mailbox SET reason = ?, detail = ?, updated_at = ? " +
+        "WHERE id = ? AND status = 'held' AND (reason IS NOT ? OR detail IS NOT ?)")
+        .run(reason, detail, now, id, reason, detail);
     return info.changes > 0;
 }
 /**
@@ -193,6 +217,25 @@ export function markEscalated(db, id, now = Date.now()) {
         .run(now, id);
     return info.changes > 0;
 }
+/**
+ * Flag an already-DELIVERED row as escalated (Issue #1584) — visibility only, and the
+ * counterpart to {@link markEscalated} for the one case that flags a row *after* it has left
+ * the held set: a delivery whose write completed but whose echo never confirmed.
+ *
+ * A separate function rather than a relaxed guard on {@link markEscalated}, because that one's
+ * held-only contract is what makes the drainer's escalation pass safe to call blindly. Here the
+ * ordering is the point: the row is marked `delivered` FIRST (that commit is what makes the
+ * write un-repeatable even across a crash), so by the time the verdict is known the held-only
+ * guard would silently no-op and the flag would be lost.
+ *
+ * Delivered-only and idempotent (the `escalated = 0` guard). Returns true if it flipped.
+ */
+export function markEscalatedDelivered(db, id, now = Date.now()) {
+    const info = db
+        .prepare("UPDATE mailbox SET escalated = 1, updated_at = ? WHERE id = ? AND status = 'delivered' AND escalated = 0")
+        .run(now, id);
+    return info.changes > 0;
+}
 /**
  * Supersede-key prefix for architect starvation notices (Spec 1313 round 3, change 3). A
  * notice row carries `${NOTICE_SUPERSEDE_PREFIX}<starving-agent>` so (a) one pending notice
@@ -217,7 +260,8 @@ export function findStarvingAgents(db, now = Date.now()) {
         .prepare(`SELECT workspace_path AS workspacePath, to_agent AS toAgent,
               MIN(${ESCALATION_START_SQL}) AS stuckSince,
               COUNT(*) AS count,
-              MAX(reason) AS reason
+              MAX(reason) AS reason,
+              MAX(detail) AS detail
          FROM mailbox
         WHERE status = 'held'
           AND (not_before IS NULL OR not_before <= ?)

package/dist/agent-farm/db/mailbox.js.map

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

package/dist/agent-farm/db/migrations.d.ts

@@ -0,0 +1,57 @@
+/**
+ * global.db forward-only migrations (Issue #1476).
+ *
+ * The migration sequence used to live inline inside the private
+ * `ensureGlobalDatabase()` path in `db/index.ts`, so migration tests could only
+ * drive hand-maintained *replicas* of it. This module is the single source of
+ * truth both production init and the tests call:
+ *
+ *   - `ensureGlobalDatabase()` calls `runGlobalMigrations(db)` on an existing
+ *     database (fresh installs get the final shape from GLOBAL_SCHEMA and stamp
+ *     every marker up to `GLOBAL_CURRENT_VERSION` instead).
+ *   - `__tests__/spec-1313-migration.test.ts` builds a database at a historical
+ *     version and calls the very same function, so the SQL under test is the SQL
+ *     that ships.
+ *
+ * The runner takes an explicit `db` handle (matching `db/mailbox.ts` /
+ * `db/consolidate.ts`) — it never opens a connection, reads a singleton, or sets
+ * pragmas. Every step is idempotent and gated on its `_migrations` marker, so
+ * calling it repeatedly on the same handle is a no-op. Migrations are
+ * forward-only by project convention; there is no reverse SQL.
+ */
+import type Database from 'better-sqlite3';
+/** Current migration version — bump when adding new migrations. */
+export declare const GLOBAL_CURRENT_VERSION = 18;
+export interface GlobalMigrationOptions {
+    /**
+     * Sink for per-migration progress lines. Defaults to `console.log`, which is
+     * what the production open path wants; tests pass a collector (or a no-op) to
+     * keep output clean and to assert which steps actually ran.
+     */
+    log?: (message: string) => void;
+    /**
+     * Directory holding shellper sockets, whose files migration v8 renames.
+     * Defaults to `~/.codev/run` — the production location. Tests point it at a
+     * temp directory so driving the real runner never touches a developer's live
+     * sockets.
+     */
+    runDir?: string;
+}
+/**
+ * Run every outstanding global.db migration against `db`.
+ *
+ * Safe to call on any existing database that reached its recorded version through
+ * migrations: each step checks its own `_migrations` marker first, so applied steps
+ * are skipped and the call converges on the `GLOBAL_CURRENT_VERSION` shape.
+ *
+ * NOT for a fresh database. A GLOBAL_SCHEMA-shaped database with no markers would run
+ * v5 against the long-renamed `terminal_sessions.project_path` — which is why
+ * `ensureGlobalDatabase()` stamps every marker on the fresh path instead of running
+ * the chain. That shape is rejected at entry with a named error rather than an opaque
+ * mid-chain SQLite failure.
+ *
+ * @throws if the database carries the post-v9 `workspace_path` shape without the v9
+ * marker to match (a fresh schema that never walked the chain).
+ */
+export declare function runGlobalMigrations(db: Database.Database, options?: GlobalMigrationOptions): void;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/agent-farm/db/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAK3C,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,OAAO,GAAE,sBAA2B,GACnC,IAAI,CAufN"}