toolroll 0.9.58 → 0.9.60

package/dist/steer-mailbox.js

@@ -0,0 +1,207 @@
+/**
+ * The running build's steering mailbox (v120). A note an operator files
+ * while a build runs used to wait for the next attempt; now the builder's
+ * pulse writes it into one nonce-named folder in the worktree, as a numbered
+ * file the agent reads and acknowledges by moving it into `handled/` — the
+ * same small contract a person's own inbox keeps:
+ *
+ * - The durable record is the delivery. A note is mailed (written into the
+ *   folder) and read (moved by the agent); nothing else counts. A hook
+ *   reminding the agent, or a file the pulse wrote, proves nothing.
+ * - Numbers are never reused: the next one is past every name in the folder
+ *   and in `handled/`, and past every one this pulse has used.
+ * - Whatever is still unread when the attempt ends keeps today's road: the
+ *   note stays pending, the next attempt's brief quotes it, and a task that
+ *   ends first supersedes it.
+ *
+ * Every step is bookkeeping, and bookkeeping never fails a build: a folder
+ * the agent removed is made again, one it replaced with anything but a real
+ * directory is never written through, and an error waits for the next beat.
+ *
+ * Two boundaries, because the folder lives where the agent and anything it
+ * runs can write:
+ * - Every genuine note carries this attempt's key, which only the brief and
+ *   the notes themselves name. A file in the folder without it was not
+ *   written by the operator, and the brief tells the agent to act on none.
+ *   (The brief rides the agent's argv, so a process that reads argv could
+ *   learn it: this keeps ordinary repository code from posing as the
+ *   operator, not a determined local process.)
+ * - The pulse writes only while the folder still resolves to this worktree's
+ *   own folder, before and after each write, so swapping it for a link can
+ *   never make the plane write a note somewhere else.
+ */
+import { lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fence } from "./brief-fence.js";
+export const STEER_HANDLED = "handled";
+const NOTE_NAME = /^(\d+)\.json$/;
+export const steerNoteName = (number) => `${String(number).padStart(3, "0")}.json`;
+const isRealDirectory = (path) => {
+    try {
+        return lstatSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/** Make the folder and its handled/ inside the worktree; null when it cannot be made. */
+export function openSteerMailbox(worktree, folder, runId, taskRef, key) {
+    let realDir;
+    try {
+        realDir = join(realpathSync(worktree), folder);
+    }
+    catch {
+        return null;
+    }
+    const box = { runId, taskRef, folder, dir: join(worktree, folder), realDir, key, last: 0, waiting: new Map() };
+    return ensureFolder(box) ? box : null;
+}
+/** The folder is still this worktree's own, not a link to somewhere else. */
+const stillInside = (box) => {
+    try {
+        return realpathSync(box.dir) === box.realDir;
+    }
+    catch {
+        return false;
+    }
+};
+function ensureFolder(box) {
+    for (const path of [box.dir, join(box.dir, STEER_HANDLED)]) {
+        try {
+            mkdirSync(path, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                return false;
+        }
+        // Something the agent put in the folder's place is never written through.
+        if (!isRealDirectory(path))
+            return false;
+    }
+    return stillInside(box);
+}
+function highestNumber(box) {
+    let highest = box.last;
+    for (const path of [box.dir, join(box.dir, STEER_HANDLED)]) {
+        let names;
+        try {
+            names = readdirSync(path);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const number = NOTE_NAME.exec(name)?.[1];
+            if (number !== undefined)
+                highest = Math.max(highest, Number(number));
+        }
+    }
+    return highest;
+}
+/** Every waiting note the agent moved into handled/ is read, by this run. */
+function collectAcknowledgements(store, box, now) {
+    if (box.waiting.size === 0)
+        return;
+    const handled = join(box.dir, STEER_HANDLED);
+    if (!isRealDirectory(box.dir) || !isRealDirectory(handled))
+        return;
+    for (const [number, noteId] of [...box.waiting]) {
+        let moved;
+        try {
+            moved = lstatSync(join(handled, steerNoteName(number))).isFile();
+        }
+        catch {
+            moved = false;
+        }
+        if (!moved)
+            continue;
+        box.waiting.delete(number);
+        store.ackSteerNote(noteId, box.runId, now);
+    }
+}
+/** Remove a name this pulse wrote, only while the folder is still this worktree's own; a link goes, never its target. */
+function removeOwn(box, name) {
+    if (!stillInside(box))
+        return;
+    try {
+        unlinkSync(join(box.dir, name));
+    }
+    catch { /* never written, or the agent already took it */ }
+}
+/** Write each note this run has not seen yet: a temp name, then the number. */
+function mailNotes(store, box, now) {
+    const notes = store.mailableSteerNotes(box.taskRef, box.runId);
+    if (notes.length === 0 || !ensureFolder(box))
+        return;
+    for (const note of notes) {
+        if (!stillInside(box))
+            return;
+        const number = highestNumber(box) + 1;
+        const name = steerNoteName(number);
+        const temp = `.${name}.tmp`;
+        const body = { version: 1, number, key: box.key, filedAt: note.createdAt, note: fence(note.note) };
+        try {
+            writeFileSync(join(box.dir, temp), `${JSON.stringify(body, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+            renameSync(join(box.dir, temp), join(box.dir, name));
+        }
+        catch {
+            removeOwn(box, temp);
+            return;
+        }
+        // Checked again after the write: a folder swapped for a link mid-write
+        // leaves the note unrecorded, deletes nothing, and mails nothing more this beat.
+        if (!stillInside(box))
+            return;
+        box.last = number;
+        let recorded;
+        try {
+            recorded = store.markSteerMailed(note.id, box.runId, now);
+        }
+        catch {
+            recorded = false;
+        }
+        if (recorded) {
+            box.waiting.set(number, note.id);
+        }
+        else {
+            // The task ended or the note settled between the read and the write, or
+            // the mailing could not be recorded: an unrecorded file would only be
+            // mailed twice, so it goes, and the next beat tries again.
+            removeOwn(box, name);
+        }
+    }
+}
+/** One beat: record what the agent read, then mail what is new while the agent runs. */
+export function pulseSteerMailbox(store, box, now, agentRunning) {
+    collectAcknowledgements(store, box, now);
+    if (agentRunning)
+        mailNotes(store, box, now);
+}
+/** The attempt is over: one last read, then the folder goes. Unread notes stay pending for the next attempt. */
+export function closeSteerMailbox(store, box, now) {
+    try {
+        collectAcknowledgements(store, box, now);
+    }
+    catch { /* the notes stay pending */ }
+    try {
+        rmSync(box.dir, { recursive: true, force: true });
+    }
+    catch { /* the next attempt's sweep removes it */ }
+}
+const shellQuote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+/**
+ * Claude's doorbell: a synchronous PostToolUse hook that lists the folder and,
+ * while a note is unread, hands the agent one line of context between tool
+ * calls. It only says notes are waiting — it never quotes one, and its firing
+ * is never an acknowledgement. Rendered into the run's own --settings.
+ */
+export function claudeSteerHooks(dir, folder) {
+    const context = {
+        hookSpecificOutput: {
+            hookEventName: "PostToolUse",
+            additionalContext: `Operator steering waiting: %s unread note(s) in ${folder}/. Read them in number order now, act on each within the agreed scope, then move each into ${folder}/${STEER_HANDLED}/.`,
+        },
+    };
+    const command = `set -- ${shellQuote(dir)}/[0-9]*.json; [ -e "$1" ] || exit 0; printf ${shellQuote(`${JSON.stringify(context)}\n`)} "$#"`;
+    return { PostToolUse: [{ matcher: "*", hooks: [{ type: "command", command }] }] };
+}

package/dist/steer-status.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where a steering note stands, in the one set of words the task page, the
+ * CLI and the lead all use (v120). A note is read only when the agent proves
+ * it: the stream's receipt of a brief that quoted it, or the agent moving it
+ * to handled/ in a running build's steering folder. Everything else is
+ * either waiting for the agent that is running now, or for the next attempt.
+ */
+import type { SteerNote } from "./store.js";
+export type SteerStanding = "read" | "waiting" | "next-attempt" | "ended" | "unverified";
+/** `liveBuild`: the task has a build whose agent is running and reads its steering folder (Store.steeringLiveBuild). */
+export declare function steerStandingOf(note: SteerNote, liveBuild: boolean): SteerStanding;
+/** The words, and the moment the agent read it when it has: each surface renders that time its own way. */
+export declare function steerStandingParts(note: SteerNote, liveBuild: boolean): {
+    words: string;
+    readAt: string | null;
+};
+export declare function steerStandingWords(note: SteerNote, liveBuild: boolean, time: (iso: string) => string): string;
+/** Where a note filed now goes, said before or right after filing it. */
+export declare function steerDestinationWords(liveBuild: boolean): string;

package/dist/steer-status.js

@@ -0,0 +1,30 @@
+/** `liveBuild`: the task has a build whose agent is running and reads its steering folder (Store.steeringLiveBuild). */
+export function steerStandingOf(note, liveBuild) {
+    if (note.authorshipState !== "verified")
+        return "unverified";
+    if (note.supersededAt !== null)
+        return "ended";
+    if (note.deliveredAt !== null)
+        return "read";
+    return liveBuild ? "waiting" : "next-attempt";
+}
+/** The words, and the moment the agent read it when it has: each surface renders that time its own way. */
+export function steerStandingParts(note, liveBuild) {
+    switch (steerStandingOf(note, liveBuild)) {
+        case "read": return { words: "Read by the agent at", readAt: note.ackedAt ?? note.deliveredAt };
+        case "waiting": return { words: "Waiting for the agent to read it", readAt: null };
+        case "next-attempt": return { words: "Will reach the next attempt", readAt: null };
+        case "ended": return { words: "The task ended before the agent read it", readAt: null };
+        case "unverified": return { words: "Saved before notes required a sign-in; never sent", readAt: null };
+    }
+}
+export function steerStandingWords(note, liveBuild, time) {
+    const { words, readAt } = steerStandingParts(note, liveBuild);
+    return readAt === null ? words : `${words} ${time(readAt)}`;
+}
+/** Where a note filed now goes, said before or right after filing it. */
+export function steerDestinationWords(liveBuild) {
+    return liveBuild
+        ? "The running agent reads it when it next checks for notes."
+        : "The next attempt reads it before starting.";
+}

package/dist/store.d.ts

@@ -152,7 +152,7 @@ export type SealedLedgerEntry = LedgerEntry & {
         hash: string;
     } | null;
 };
-export declare const SCHEMA_VERSION = 118;
+export declare const SCHEMA_VERSION = 120;
 /** v118: the tables merged into `credential`, in the order they move (a person's API tokens keep their ids first). */
 export declare const V118_MERGED_TABLES: Readonly<Record<string, CredentialKind>>;
 /**
@@ -207,9 +207,22 @@ export declare const V115_DROPPED_TABLES: readonly string[];
  * teammates' to its subagents' (SQLite's RENAME, every row, id and link carried), renames their teammate column, and rewrites four internal kinds from 'teammate' to 'subagent' in place; the rehearsal checks
  * each renamed table's rows arrived under its new name. v118 (D7) is checked the same way: every row of api_token,
  * coordinator_credential and lead_credential moves into credential under its kind in one transaction that counts them
- * before the old tables drop, and the references that named them name credential in place, their rows untouched.
+ * before the old tables drop, and the references that named them name credential in place, their rows untouched. v119 only adds four columns
+ * (planning_generation on task_ref, run and plan_revision, defaulting to 0, and decision.superseded_reason, null);
+ * the rehearsal checks every saved row reads the declared default (HISTORY_RULES' added columns). v120 only adds
+ * three nullable task_steer columns (the running build's steering folder), checked the same way.
  */
 export declare const UPDATE_SAFE_MIGRATIONS: readonly number[];
+/** v119: the columns it adds, by table, with the value every row saved before it reads (toolroll-update's HISTORY_RULES). */
+export declare const V119_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
+/** v120: the columns it adds, by table, with the value every row saved before it reads. */
+export declare const V120_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export declare function updateSafeSchema(version: number | null): boolean;
 export type OAuthClientRow = {
@@ -330,6 +343,9 @@ export type TaskRef = {
     plan: "requested" | "drafted" | null;
     /** Planning failures, counted apart from build strikes by design. */
     planStrikes: number;
+    /** v119: which planning context is active. A rewritten scope advances it; plans, revisions and answers from an
+     * earlier generation stay as history, never as the next planner's context. */
+    planningGeneration: number;
     /** What comes back (v34): a branch to publish, or a report to read.
      * Set at filing and never rewritten — a scout's strikes are the task's. */
     deliverable: "branch" | "report";
@@ -1050,6 +1066,8 @@ export type Run = {
     taskRef: number;
     leaseId: string;
     runner: string;
+    /** v119: the task's planning generation when this run opened (0 for every run before it). */
+    planningGeneration: number;
     /** Explicit watch ownership for claimless review runs; null on cron/legacy reviews. */
     watchIncarnation?: string | null;
     /** v50: a ROOT reviewer's attempt ordinal for its source run (1..3);
@@ -1125,6 +1143,9 @@ export type RunPhase = (typeof RUN_PHASES)[number];
  * One operator steering note (arc 1, v22). Attached ≠ delivered: attachment
  * says which build the note rode toward; delivery settles only on the
  * stream's own receipt. Superseded = the task ended with it still pending.
+ * v120: a note filed while a build runs is mailed into that build's steering
+ * folder (mailed), and is read only when the agent moves it to handled/
+ * (acked, which also settles it delivered to that build).
  */
 export type SteerNote = {
     /** v24 (ruling 11): "verified" = credentialed authorship; anything else is history, never brief-bound. */
@@ -1139,6 +1160,9 @@ export type SteerNote = {
     attachedAt: string | null;
     deliveredAt: string | null;
     supersededAt: string | null;
+    mailedRun: number | null;
+    mailedAt: string | null;
+    ackedAt: string | null;
 };
 /** One phone enrollment for web push (arc 3, v23). A row per ACTIVATION —
  * retirement is history, never deletion. */
@@ -1194,7 +1218,12 @@ export type Decision = {
     answeredVia: "cli" | "web" | "telegram" | "slack" | "discord" | "teams" | null;
     choice: string | null;
     note: string | null;
+    /** v119: closed without an answer (state 'answered', no choice) because its task's scope changed or the task was
+     * cancelled. null is every real answer and every question still waiting. */
+    supersededReason: DecisionClosure | null;
 };
+/** Why a question closed without an answer (v119). */
+export type DecisionClosure = "scope-changed" | "cancelled";
 /** Evidence, by reference. `key` is relative to the evidence root, never absolute. */
 export type Artifact = {
     id: number;
@@ -3446,6 +3475,24 @@ export declare class Store {
         ok: false;
         reason: "live-claim";
     };
+    /**
+     * A rewritten scope starts planning again (v119), in one transaction: the task's planning generation advances, a
+     * requested or drafted plan becomes requested with no strikes, and what the old goal produced leaves the active
+     * planning context — its open questions close (typed 'scope-changed', never a fake answer, their holds and pages
+     * with them) and a revision still waiting for a person is rejected with its hold. The old runs, plans, revisions,
+     * answers and ledger rows all stay: generation-bound reads simply stop offering them to the next planner. Only a
+     * task already planning restarts; false (nothing changed) for any other.
+     */
+    restartPlanning(taskRef: number, now: Date): boolean;
+    /**
+     * Close a task's open and expired questions without answering them (v119): typed with why, no choice, their
+     * holds lifted and their pages resolved, so they leave every decision queue. Answered questions are never touched.
+     * `belowGeneration` limits it to questions asked in earlier planning generations. Caller holds the transaction.
+     */
+    private closeQuestionsLocked;
+    /** The number the next plan revision of a task takes: one past every revision it ever had, in any planning
+     * generation, so a restarted plan's revisions never collide with the history they follow. */
+    nextPlanRevisionNumber(taskRef: number): number;
     /** Move the planning state; null clears it. Caller owns the transaction story. */
     setPlanState(taskRef: number, state: "requested" | "drafted" | null): void;
     addPlanStrike(taskRef: number): number;
@@ -4475,7 +4522,8 @@ export declare class Store {
      * reads in the order the questions arrived. "unanswered" is open + expired:
      * expiry makes a decision louder, never gone.
      */
-    /** The newest planner run's plan document for a task, when one exists. */
+    /** The newest planner run's plan document for a task, when one exists in its current planning generation (v119:
+     * a plan drafted for a scope since rewritten is history, read by its artifact id). */
     latestPlanArtifact(taskRef: number): Artifact | null;
     /** The newest plan-contract INGESTION record on one of this task's
      * planner runs (contract handoff, task 1): what the draft proposed
@@ -4508,8 +4556,9 @@ export declare class Store {
         changedFields: readonly string[];
         status: PlanRevisionStatus;
     }, now: Date): number;
-    /** Every revision for a task, newest first — the immutable history a
-     * reader can show without a second table. */
+    /** Every revision for a task in its current planning generation, newest
+     * first — the immutable history a reader can show without a second table
+     * (v119: an earlier generation's rows stay, read by id). */
     listPlanRevisions(taskRef: number): PlanRevision[];
     /** The current plan revision: the newest row an operator (or an
      * auto-applied plan-only proposal) has actually put in force. Null for
@@ -4566,7 +4615,8 @@ export declare class Store {
     checkpointHistory(run: number): RunCheckpoint[];
     /** The newest scout run's report for a task (v34), when one exists. */
     latestReportArtifact(taskRef: number): Artifact | null;
-    /** Answered questions for one task, newest first — the planner's memory. */
+    /** Answered questions for one task, newest first — the planner's memory. Only real answers from its current
+     * planning generation (v119): a question closed unanswered, or asked about a scope since rewritten, is history. */
     answeredDecisionsFor(taskId: string, limit?: number): {
         question: string;
         choice: string | null;
@@ -4638,6 +4688,33 @@ export declare class Store {
      * first receipt wins, and a replay changes nothing.
      */
     settleSteerDelivered(runId: number, now: Date): number;
+    /**
+     * The task's build whose agent is running right now and reads its steering
+     * folder (v120): the current live lease's open builder run, in its
+     * agent-running phase, whose steering folder is open. Null otherwise — a
+     * note then waits for the next attempt. Display state, never evidence.
+     */
+    steeringLiveBuild(taskRef: number, now: Date): number | null;
+    /** This run made its steering folder (v120): its agent can read a note filed now. */
+    markSteerFolderOpened(runId: number, now: Date): void;
+    /** This run's steering folder is gone (v120): a note filed now reaches the next attempt. */
+    markSteerFolderClosed(runId: number, now: Date): void;
+    /**
+     * The notes a RUNNING build may still read (v120): verified, pending, not
+     * already quoted in this run's brief, and not already in its folder. The
+     * pulse mails exactly these, in filing order.
+     */
+    mailableSteerNotes(taskRef: number, runId: number): SteerNote[];
+    /** The pulse wrote this note into the run's steering folder. Mailing is not
+     * reading: delivery settles only on the agent's own acknowledgement. */
+    markSteerMailed(noteId: number, runId: number, now: Date): boolean;
+    /**
+     * The agent moved this note to handled/ (v120): it was read, by THIS run.
+     * Acknowledgement is the only road from mailed to delivered — a hook firing
+     * or a file written proves nothing. First acknowledgement wins; a note the
+     * task already ended, or mailed to another run since, is left alone.
+     */
+    ackSteerNote(noteId: number, runId: number, now: Date): boolean;
     /** A finished task's pending notes settle superseded — shown, typed, done. */
     supersedeSteerNotes(taskRef: number, now: Date): number;
     /** The answers a run was given, exactly as it was given them. */
@@ -4668,7 +4745,7 @@ export declare class Store {
         duplicate?: boolean;
     } | {
         ok: false;
-        reason: "unknown-decision" | "bad-option" | "already-answered" | "bad-note";
+        reason: "unknown-decision" | "bad-option" | "already-answered" | "closed" | "bad-note";
     };
     /**
      * The answer's body, for callers already holding the transaction — the
@@ -4689,7 +4766,7 @@ export declare class Store {
         duplicate?: boolean;
     } | {
         ok: false;
-        reason: "unknown-decision" | "bad-option" | "already-answered" | "bad-note";
+        reason: "unknown-decision" | "bad-option" | "already-answered" | "closed" | "bad-note";
     };
     saveArtifact(artifact: {
         run: number;