@timqi/pier 0.1.14 → 0.2.0

package/dist/tasks/service.js

@@ -3,11 +3,12 @@
 // drain needs. Decisions belong to the files beside it.
 import { logger } from "../log.js";
 import { AgentTaskRunner } from "./agent.js";
-import { TaskCallbacks } from "./callbacks.js";
+import { DESIGN_FINAL, MILESTONE, runCwd, settleCallback, TaskCallbacks } from "./callbacks.js";
 import { TaskDefinitions, requiredString } from "./definitions.js";
 import { TaskExecution } from "./execution.js";
 import { TaskGroups } from "./groups.js";
 import { TaskMessenger } from "./messages.js";
+import { openItems, recordOpenItems } from "./open-items.js";
 import { TaskRunQueue } from "./runs.js";
 import { handleTask } from "./operations.js";
 import { isTerminal } from "./types.js";
@@ -36,17 +37,23 @@ export class TaskService {
     runs;
     execution;
     constructor(store, factory, router, hub, 
-    /** Structural: tasks/ must not import settings.ts. Absent in bare test rigs. */
+    /** Structural: tasks/ must not import settings.ts. */
     instance) {
         this.store = store;
         this.factory = factory;
         this.router = router;
         this.hub = hub;
         this.instance = instance;
+        const headOf = (id) => instance.continuous.chainOf(id)?.[0] ?? id;
+        const conversation = () => instance.continuous.members()[0]?.sessionId ?? null;
         const unreachable = (sessionId, what, why) => this.unreachable(sessionId, what, why);
-        this.messages = new TaskMessenger(store, router, hub, unreachable);
-        this.definitions = new TaskDefinitions(store, factory, router, hub, instance?.systemActions);
-        this.callbacks = new TaskCallbacks(store, router, (run) => this.changed(run), unreachable);
+        this.messages = new TaskMessenger(store, router, hub, unreachable, (runId) => {
+            const run = store.getRun(runId);
+            if (run)
+                this.status(run);
+        });
+        this.definitions = new TaskDefinitions(store, factory, router, hub, instance.systemActions);
+        this.callbacks = new TaskCallbacks(store, router, (run) => this.changed(run), unreachable, headOf, this.milestone, conversation);
         this.groups = new TaskGroups(store, router, {
             getRun: (id) => this.getRun(id),
             cancel: (id) => { this.cancel(id); },
@@ -58,7 +65,7 @@ export class TaskService {
                 groupId,
             }),
             startMember: (run) => this.runs.start(run),
-        }, (group) => this.hub.emitWorkspace({ type: "task-group-changed", groupId: group.id }), unreachable);
+        }, (group) => this.hub.emitWorkspace({ type: "task-group-changed", groupId: group.id }), unreachable, headOf, this.milestone);
         const agent = new AgentTaskRunner(factory, router, store, this.messages, (run) => this.changed(run));
         this.execution = new TaskExecution(store, this.definitions, this.callbacks, agent, {
             runChild: (taskId, parent) => this.run(taskId, parent.input, "task", parent.id, {
@@ -73,6 +80,64 @@ export class TaskService {
             changed: (run) => this.changed(run),
         });
         this.runs = new TaskRunQueue(store, this.callbacks, (run) => this.execution.start(run), (run) => this.changed(run));
+        router.onTurnEnd((sessionId, text) => {
+            // Only the head's turns write the list.
+            if (instance.continuous.members()[0]?.sessionId === sessionId) {
+                try {
+                    if (recordOpenItems(store, text, Date.now()))
+                        hub.emitWorkspace({ type: "open-items-changed" });
+                }
+                catch (err) {
+                    log.warn(`open items: the markers in ${sessionId}'s reply could not be written`, err);
+                }
+            }
+            if (!DESIGN_FINAL.test(text))
+                return;
+            // On Pi's dispatch stack, which must not unwind.
+            try {
+                this.designFinal(sessionId, text);
+            }
+            catch (err) {
+                log.error(`lead ${sessionId}: a Design final: outside any run could not be recorded; main was not told`, err);
+            }
+        });
+    }
+    /** A design lead finalized in its own session, a turn outside any run (the
+     *  user confirmed there): recorded as a finished run of the lead whose result
+     *  is that reply, so it reports to the lead's supervisor, and the session list and
+     *  `/status` see it, exactly as a run's `Design final:` does. */
+    designFinal(sessionId, text) {
+        // A run's own turn reports through the run.
+        if (this.store.leadPhaseOf(sessionId) !== "design" || this.store.findActiveRunForTarget(sessionId)?.state === "running")
+            return;
+        const last = this.store.latestRunForTarget(sessionId);
+        if (!last)
+            return;
+        const run = this.store.transact(() => {
+            const run = this.runs.prepare(last.context.definition, null, "agent", null, {
+                invokedBySessionId: last.invokedBySessionId,
+                sourceSessionId: last.invokedBySessionId,
+                targetSessionId: sessionId,
+                sessionMode: "reuse",
+                resumedFromRunId: last.id,
+                callbackSessionId: last.callbackSessionId,
+                callbackMode: last.callbackMode,
+                background: last.background,
+            });
+            const now = Date.now();
+            run.state = "succeeded";
+            run.startedAt = run.finishedAt = now;
+            run.result = { type: "agent", text, sessionId };
+            run.context.sessionId = sessionId;
+            settleCallback(run, this.store);
+            this.store.saveRun(run);
+            return run;
+        });
+        if (run.callbackSessionId === null)
+            log.warn(`lead ${sessionId}: Design final: recorded as run ${run.id}; the lead reports to no one`);
+        else
+            log.info(`lead ${sessionId}: Design final: outside any run, recorded as run ${run.id} for ${run.callbackSessionId}`);
+        this.runs.start(run);
     }
     start(tickMs = 1000) {
         if (this.timer)
@@ -145,7 +210,7 @@ export class TaskService {
     create(raw, creator = "http") {
         return this.definitions.create(raw, creator);
     }
-    /** `by` is how owning code says so; the routes and `pier task` have none (definitions.ts). */
+    /** `by` is how owning code says so; `pier task` has none (definitions.ts). */
     update(id, raw, by) {
         return this.definitions.update(id, raw, by);
     }
@@ -155,9 +220,9 @@ export class TaskService {
     archive(id, by) {
         return this.definitions.archive(id, by);
     }
-    listRuns(taskId, limit = 50, offset = 0) {
-        this.get(taskId);
-        return this.store.listRuns(taskId, Math.min(Math.max(limit, 1), 200), Math.max(offset, 0));
+    /** `pier task list`'s last run: the newest `limit` of a definition's runs. */
+    listRuns(taskId, limit = 1) {
+        return this.store.listRuns(taskId, limit);
     }
     getRun(id) {
         const run = this.store.getRun(id);
@@ -165,24 +230,6 @@ export class TaskService {
             throw new Error(`unknown task run: ${id}`);
         return run;
     }
-    getRunView(id) {
-        const run = this.getRun(id);
-        return { ...run,
-            groupCallbackState: run.groupId ? this.store.getGroup(run.groupId)?.callbackState ?? null : null };
-    }
-    listMessages(runId) {
-        this.getRun(runId);
-        return this.messages.list(runId);
-    }
-    queryRuns(query = {}) {
-        return this.store.queryRuns(query);
-    }
-    activityRuns(since) {
-        return this.store.activityRuns(since);
-    }
-    recentMessages(since) {
-        return this.messages.recent(since);
-    }
     /** Every run, not the last hour's: the card is a message in the transcript. */
     backgroundRuns(sessionId) {
         return this.store.listRunsForSession(sessionId, 200)
@@ -190,6 +237,28 @@ export class TaskService {
             .reverse()
             .map((run) => this.backgroundRun(run));
     }
+    /** What the session's queue shows beside Pi's own: follow-ups waiting for it to idle. */
+    parkedMessages(sessionId) {
+        return this.store.pendingFollowUpsTo(sessionId).map((message) => ({
+            messageId: message.id,
+            runName: this.store.getRun(message.runId)?.context.definition.name ?? message.runId,
+            text: message.content,
+        }));
+    }
+    /** The run ledger: runs any of `sessionIds` launched, in flight or finished since `since`, at most 200. */
+    ledger(sessionIds, since) {
+        return this.store.ledgerRuns(sessionIds, since).map(ledgerRun);
+    }
+    /** Design leads no run of which has reported `Design final:`, by their creating run: the user's to finalize. */
+    openDesigns() {
+        return [...this.store.leads().values()].flatMap((lead) => {
+            const run = lead.designOpen ? this.store.getRun(lead.runId) : undefined;
+            return run ? [ledgerRun(run)] : [];
+        });
+    }
+    openItems(now = Date.now()) {
+        return openItems(this, this.router, this.instance.continuous.members().map((m) => m.sessionId), this.openDesigns(), now);
+    }
     activeBackgroundRunCounts() {
         return this.store.countActiveBackgroundRunsBySession();
     }
@@ -262,15 +331,19 @@ export class TaskService {
         return this.messages.control(run, fromSessionId, mode, message);
     }
     resume(id, message, provenance = {}) {
+        const run = this.prepareResume(this.getRun(id), message, provenance);
+        this.runs.start(run);
+        return run;
+    }
+    prepareResume(prior, message, provenance) {
         this.refusePaused();
-        const prior = this.getRun(id);
         if (!isTerminal(prior.state))
             throw new Error("run must be terminal before resume");
         if (prior.context.definition.action.type !== "agent" || !prior.targetSessionId) {
             throw new Error("only persisted Agent runs can be resumed");
         }
         const prompt = requiredString(message, "message");
-        const run = this.runs.prepare(prior.context.definition, null, "agent", null, {
+        return this.runs.prepare(prior.context.definition, null, "agent", null, {
             ...provenance,
             sourceSessionId: provenance.invokedBySessionId ?? prior.invokedBySessionId,
             targetSessionId: prior.targetSessionId,
@@ -278,16 +351,46 @@ export class TaskService {
             resumedFromRunId: prior.id,
             resumePrompt: prompt,
         });
-        this.runs.start(run);
-        return run;
     }
+    /** A lead reports once per wave (docs/design/10-continuous-session.md
+     *  §Feature lead): the result that leaves nothing owed to it in flight
+     *  resumes its last run, whose own callback reaches its supervisor. */
+    milestone = (sessionId, text, settle) => {
+        if (this.store.roleOf(sessionId) !== "lead" || this.store.countOwedTo(sessionId) > 0)
+            return "plain";
+        const last = this.store.latestRunForTarget(sessionId);
+        if (!last || last.callbackSessionId === null)
+            return "plain";
+        // A running turn reports upstream when it ends; a drain leaves the result to the next boot.
+        if (!isTerminal(last.state) || this.paused)
+            return "wait";
+        try {
+            // One transaction: a crash between the resume and the marks would resume twice.
+            const run = this.store.transact(() => {
+                const run = this.prepareResume(last, `${MILESTONE}\n\n${text()}`, {
+                    invokedBySessionId: last.invokedBySessionId,
+                    callbackSessionId: last.callbackSessionId,
+                    callbackMode: last.callbackMode,
+                    background: last.background,
+                });
+                settle();
+                return run;
+            });
+            this.runs.start(run);
+            return "resumed";
+        }
+        catch (err) {
+            log.error(`lead ${sessionId}: the wave's last result could not resume run ${last.id}; delivering it as a plain callback`, err);
+            return "plain";
+        }
+    };
     /** What `pier task` asks, under the calling session's identity. */
     handle(raw, callerSessionId) {
-        return handleTask(this, this.definitions, this.store, raw, callerSessionId);
+        return handleTask(this, this.definitions, this.store, raw, callerSessionId, this.instance.continuous);
     }
     /** An agent picks from names that exist right now, never from memory. */
     async models() {
-        const menu = this.instance?.modelMenu() ?? [];
+        const menu = this.instance.modelMenu();
         if (menu.length)
             return { source: "menu", models: menu };
         return { source: "catalog", models: await this.factory.availableModels() };
@@ -355,12 +458,20 @@ export class TaskService {
             queuedAt: run.queuedAt,
             startedAt: run.startedAt,
             finishedAt: run.finishedAt,
+            // A finished run's pending messages only wait for the sweep to expire them.
+            queuedMessages: isTerminal(run.state) ? 0 : this.store.countPendingFollowUps(run.id),
         };
     }
     changed(run) {
         this.hub.emitWorkspace({ type: "task-run-changed", taskId: run.taskId, runId: run.id });
+        this.status(run);
+    }
+    status(run) {
         if (run.background && run.invokedBySessionId) {
             this.hub.emit(run.invokedBySessionId, { type: "task-status", run: this.backgroundRun(run) });
         }
     }
 }
+function ledgerRun(run) {
+    return { runId: run.id, name: run.context.definition.name, state: run.state, targetSessionId: run.targetSessionId, cwd: runCwd(run), queuedAt: run.queuedAt, finishedAt: run.finishedAt };
+}

package/dist/tasks/store.js

@@ -1,6 +1,7 @@
 // Every query this area makes against pier.db, and nothing else; the schema is
 // db.ts's migration list.
 import { pierDb, statements, transact } from "../db.js";
+import { createdRole } from "./types.js";
 const clamp = (limit, cap) => Math.min(Math.max(limit, 1), cap);
 /** Kept unmatched probes per watch: one page of history, which is all any
  *  surface lists of a probe that found nothing. */
@@ -42,11 +43,8 @@ export class TaskStore {
     listDueTasks(now) {
         return this.#many("SELECT json FROM tasks WHERE next_run_at IS NOT NULL AND next_run_at <= ?", now);
     }
-    listRuns(taskId, limit = 50, offset = 0) {
-        return this.#many(`
-      SELECT json FROM task_runs WHERE task_id = ?
-      ORDER BY queued_at DESC LIMIT ? OFFSET ?
-    `, taskId, limit, offset);
+    listRuns(taskId, limit = 50) {
+        return this.#many("SELECT json FROM task_runs WHERE task_id = ? ORDER BY queued_at DESC LIMIT ?", taskId, limit);
     }
     getRun(id) {
         return this.#one("SELECT json FROM task_runs WHERE id = ?", id);
@@ -79,57 +77,15 @@ export class TaskStore {
       )
     `).run(taskId, taskId, KEPT_PROBES);
     }
-    /** The id breaks timestamp ties so a page boundary never repeats or skips a
-     *  row. Built per call, not cached: the filter set makes it. */
-    queryRuns(query = {}) {
-        const where = [];
-        const params = [];
-        const add = (sql, value) => {
-            if (value !== undefined) {
-                where.push(sql);
-                params.push(value);
-            }
-        };
-        add("r.state = ?", query.state);
-        add("r.task_id = ?", query.taskId);
-        add("json_extract(r.json, '$.triggerSource') = ?", query.source);
-        add("r.queued_at >= ?", query.since);
-        add("r.queued_at <= ?", query.until);
-        // Keep this predicate identical to migration 17's partial index.
-        if (!query.showUnmatched)
-            where.push("NOT (r.state = 'succeeded' AND json_extract(r.json, '$.matched') IS 0)");
-        if (query.cursor) {
-            where.push("(r.queued_at, r.id) < (?, ?)");
-            params.push(query.cursor.queuedAt, query.cursor.id);
-        }
-        const limit = clamp(query.limit ?? 50, 200);
-        const rows = this.db.prepare(`
-      SELECT r.json, g.callback_state AS group_callback_state
-      FROM task_runs r LEFT JOIN task_groups g ON g.id = json_extract(r.json, '$.groupId')
-      ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
-      ORDER BY r.queued_at DESC, r.id DESC LIMIT ?
-    `).all(...params, limit + 1);
-        const runs = rows.slice(0, limit).map((row) => ({
-            ...JSON.parse(row.json), groupCallbackState: row.group_callback_state,
-        }));
-        const last = runs.at(-1);
-        return {
-            runs,
-            nextCursor: rows.length > limit && last ? { queuedAt: last.queuedAt, id: last.id } : null,
-        };
-    }
-    /** Activity never limits live work; only its optional history is bounded. */
-    activityRuns(since) {
-        const active = this.#many("SELECT json FROM task_runs WHERE state IN ('queued', 'running') ORDER BY queued_at DESC, id DESC");
-        if (since === undefined)
-            return active;
-        const recent = this.#many(`
+    /** Runs launched by any of `sessionIds`: in flight, or finished at or after `since`. */
+    ledgerRuns(sessionIds, since) {
+        return this.#many(`
       SELECT json FROM task_runs
-      WHERE state NOT IN ('queued', 'running') AND queued_at >= ?
+      WHERE json_extract(json, '$.invokedBySessionId') IN (SELECT value FROM json_each(?))
+        AND (state IN ('queued', 'running') OR json_extract(json, '$.finishedAt') >= ?)
         AND NOT (state = 'succeeded' AND json_extract(json, '$.matched') IS 0)
       ORDER BY queued_at DESC, id DESC LIMIT 200
-    `, since);
-        return [...active, ...recent].sort((a, b) => b.queuedAt - a.queuedAt || b.id.localeCompare(a.id));
+    `, JSON.stringify(sessionIds), since);
     }
     /** A `task` action's child runs; a cancel walks them. */
     listChildRuns(parentRunId) {
@@ -177,15 +133,96 @@ export class TaskStore {
         return new Map(rows.map((row) => [row.session_id, row.n]));
     }
     /** `fresh` is the one mode that makes a session rather than borrowing one;
-     *  these are the agent's conversations with itself, which the rail does not list. */
+     *  these are the agent's conversations with itself, which the session list does not
+     *  list. A feature lead's is the user's too, so it is not one of them. */
     taskOwnedSessionIds() {
         const rows = this.sql(`
       SELECT DISTINCT json_extract(json, '$.context.sessionId') AS id
       FROM task_runs
       WHERE json_extract(json, '$.sessionMode') = 'fresh' AND id IS NOT NULL
+        AND json_extract(json, '$.context.definition.action.launch.role') IS NOT 'lead'
     `).all();
         return new Set(rows.map((row) => row.id));
     }
+    /** The fresh run that made the session; a resume or a `--session`
+     *  continuation never does, so the session's role is this run's for its life. */
+    creatorOf(sessionId) {
+        return this.#one(`
+      SELECT json FROM task_runs
+      WHERE json_extract(json, '$.targetSessionId') = ? AND json_extract(json, '$.sessionMode') = 'fresh'
+      ORDER BY queued_at LIMIT 1
+    `, sessionId);
+    }
+    roleOf(sessionId) {
+        const run = this.creatorOf(sessionId);
+        return run && createdRole(run);
+    }
+    leadPhaseOf(sessionId) {
+        const run = this.creatorOf(sessionId);
+        if (!run || createdRole(run) !== "lead" || run.context.definition.action.type !== "agent")
+            return undefined;
+        return run.context.definition.action.launch?.design ? "design" : "build";
+    }
+    /** Every lead session with its phase (as `leadPhaseOf`), its creating run,
+     *  whether a run targeting it is queued or running, and — a design lead's —
+     *  whether no run of it has reported `Design final:` yet, which leaves the
+     *  design on the user; in one statement for the session list's listing. */
+    leads() {
+        const rows = this.sql(`
+      SELECT c.id, c.run_id, c.design, l.id IS NOT NULL AS live, f.id IS NOT NULL AS final FROM (
+        SELECT id AS run_id, json_extract(json, '$.targetSessionId') AS id,
+          json_extract(json, '$.context.definition.action.launch.role') AS role,
+          json_extract(json, '$.context.definition.action.launch.design') AS design,
+          ROW_NUMBER() OVER (PARTITION BY json_extract(json, '$.targetSessionId') ORDER BY queued_at) AS n
+        FROM task_runs
+        WHERE json_extract(json, '$.sessionMode') = 'fresh' AND json_extract(json, '$.targetSessionId') IS NOT NULL
+      ) c
+      LEFT JOIN (
+        SELECT DISTINCT json_extract(json, '$.targetSessionId') AS id FROM task_runs WHERE state IN ('queued', 'running')
+      ) l ON l.id = c.id
+      LEFT JOIN (
+        SELECT DISTINCT json_extract(json, '$.targetSessionId') AS id FROM task_runs
+        WHERE json_extract(json, '$.result.type') = 'agent'
+          AND instr(char(10) || json_extract(json, '$.result.text'), char(10) || 'Design final:') > 0
+      ) f ON f.id = c.id
+      WHERE c.n = 1 AND c.role = 'lead'
+    `).all();
+        return new Map(rows.map((r) => {
+            const phase = r.design === 1 ? "design" : "build";
+            return [r.id, { phase, runId: r.run_id, runLive: r.live === 1, designOpen: phase === "design" && r.final === 0 }];
+        }));
+    }
+    /** What a milestone resumes, and whose supervisor it reports to. */
+    latestRunForTarget(sessionId) {
+        return this.#one(`
+      SELECT json FROM task_runs WHERE json_extract(json, '$.targetSessionId') = ? ORDER BY queued_at DESC, id DESC LIMIT 1
+    `, sessionId);
+    }
+    /** Runs in flight whose result is owed to the session, their own or their
+     *  unfinished group's; a finished group's losers still cancelling owe nothing. */
+    countOwedTo(sessionId) {
+        const row = this.sql(`
+      SELECT COUNT(*) AS n FROM task_runs r
+      WHERE r.state IN ('queued', 'running') AND (
+        json_extract(r.json, '$.callbackSessionId') = ?
+        OR EXISTS (SELECT 1 FROM task_groups g WHERE g.id = json_extract(r.json, '$.groupId')
+          AND g.finished_at IS NULL AND json_extract(g.json, '$.callbackSessionId') = ?))
+    `).get(sessionId, sessionId);
+        return row.n;
+    }
+    /** Whether a result is still coming to the session: a run in flight owed
+     *  to it, or a finished run's or group's callback not yet delivered. */
+    awaitsResults(sessionId) {
+        if (this.countOwedTo(sessionId) > 0)
+            return true;
+        const row = this.sql(`
+      SELECT EXISTS (SELECT 1 FROM task_runs WHERE callback_state IN ('pending', 'failed')
+          AND json_extract(json, '$.callbackSessionId') = ?)
+        OR EXISTS (SELECT 1 FROM task_groups WHERE callback_state IN ('pending', 'failed')
+          AND json_extract(json, '$.callbackSessionId') = ?) AS owed
+    `).get(sessionId, sessionId);
+        return row.owed === 1;
+    }
     listRunsForSession(sessionId, limit = 50) {
         return this.#many(`
       SELECT json FROM task_runs
@@ -228,8 +265,21 @@ export class TaskStore {
     listMessages(runId) {
         return this.#many("SELECT json FROM task_messages WHERE run_id = ? ORDER BY created_at", runId);
     }
-    listRecentMessages(since) {
-        return this.#many("SELECT json FROM task_messages WHERE created_at >= ? ORDER BY created_at DESC LIMIT 200", since);
+    /** Follow-ups parked for the session until it idles: its queue shows them. */
+    pendingFollowUpsTo(sessionId) {
+        return this.#many(`
+      SELECT json FROM task_messages
+      WHERE state = 'pending' AND json_extract(json, '$.kind') = 'follow_up'
+        AND json_extract(json, '$.toSessionId') = ?
+      ORDER BY created_at
+    `, sessionId);
+    }
+    countPendingFollowUps(runId) {
+        const row = this.sql(`
+      SELECT COUNT(*) AS n FROM task_messages
+      WHERE run_id = ? AND state = 'pending' AND json_extract(json, '$.kind') = 'follow_up'
+    `).get(runId);
+        return row.n;
     }
     /** Each beside its run, so the sweep costs one query. A message whose run is
      *  gone comes back with `run: undefined`. */
@@ -274,4 +324,17 @@ export class TaskStore {
             return run;
         });
     }
+    /** The continuous conversation's open items, oldest first; `runIds` as main wrote them. */
+    openItems() {
+        return this.sql("SELECT problem, stage, run_ids FROM open_items ORDER BY updated_at, rowid").all()
+            .map((r) => ({ problem: r.problem, stage: r.stage, runIds: JSON.parse(r.run_ids) }));
+    }
+    /** Main's markers, in reply order, as one write; answers how many rows changed. */
+    markOpenItems(markers, now) {
+        return this.transact(() => markers.reduce((n, m) => n + Number(m.op === "open"
+            ? this.sql(`INSERT INTO open_items(problem, stage, run_ids, updated_at) VALUES (?, ?, ?, ?)
+          ON CONFLICT(problem) DO UPDATE SET stage = excluded.stage, run_ids = excluded.run_ids, updated_at = excluded.updated_at`)
+                .run(m.problem, m.stage, JSON.stringify(m.runIds), now).changes
+            : this.sql("DELETE FROM open_items WHERE problem = ?").run(m.problem).changes), 0));
+    }
 }

package/dist/tasks/types.js

@@ -14,3 +14,8 @@ export const isTerminal = (state) => state === "succeeded" ||
     state === "cancelled" ||
     state === "interrupted" ||
     state === "skipped";
+/** The role a fresh run's session is created with and keeps: a lead's, or a
+ *  worker's when a session launched it; a cron or watch run's has none. */
+export const createdRole = ({ context: { definition: { action } }, invokedBySessionId }) => action.type === "agent" && action.launch?.role === "lead" ? "lead" : invokedBySessionId !== null ? "worker" : undefined;
+/** The `state` of a run an item names that the ledger no longer holds; its `name` is the id. */
+export const NOT_IN_LEDGER = "not in the ledger";

package/dist/tools.js

@@ -22,8 +22,8 @@ export const MANAGED = [
             `post_install = ["rtk", "init", "-g", "--agent", "pi", "--auto-patch"]\n` +
             `pre_remove = ["rtk", "init", "--uninstall", "--agent", "pi", "--global", "--auto-patch"]`,
         summary: "Compresses long bash output before it reaches the model. Its install hook " +
-            "writes its own Pi extension (extensions/rtk.ts, listed under the local " +
-            "package) — refreshed on every update.",
+            "writes its own Pi extension (extensions/rtk.ts), and this switch is that " +
+            "extension's too — refreshed on every update.",
     },
     {
         name: "rg",

package/dist/web/auth.js

@@ -261,7 +261,7 @@ export function noteFailure(client) {
     else
         failures.set(client, { count: 1, resetAt: Date.now() + WINDOW_MS });
 }
-export const forgetFailures = (client) => void failures.delete(client);
+const forgetFailures = (client) => void failures.delete(client);
 /** Hosts, not schemes: TLS commonly terminates at the reverse proxy. */
 function originMatches(origin, host) {
     if (!origin)
@@ -341,7 +341,7 @@ export function openSession(c, store, client) {
         store.revoke(previous.id);
     setSessionCookie(c, store.open(client, c.req.header("user-agent") ?? ""));
 }
-export const PASSWORD_OFF = "Password sign-in is off while a passkey is registered.";
+const PASSWORD_OFF = "Password sign-in is off while a passkey is registered.";
 export function registerAuthRoutes(app, store, 
 /** While it answers true the password is refused and the form offers only
  *  the passkey; read per request, so removing the last passkey needs no restart. */

package/dist/web/config-sync.js

@@ -2,6 +2,9 @@
 // public route is registered before auth; every management action is after it.
 import { logger } from "../log.js";
 const log = logger("config-sync");
+/** The one answer every route that writes a synced field gives while the
+ *  subscription is on: the source owns it, and the Console says where. */
+export const managedRefusal = (c) => c.json({ error: "Managed by the configuration subscription — pause it under Agent → Configuration sync to edit here" }, 409);
 export function registerConfigShareRoute(app, sync) {
     app.get("/config-sync/:token", async (c) => {
         c.header("cache-control", "no-store");
@@ -18,13 +21,9 @@ export function registerConfigShareRoute(app, sync) {
             const published = await sync.published(token);
             if (!published)
                 return c.json({ error: "not found" }, 404);
-            c.header("etag", published.etag);
             c.header("x-content-type-options", "nosniff");
-            const tags = c.req.header("if-none-match")?.split(",").map((value) => value.trim().replace(/^W\//, ""));
-            if (tags?.includes(published.etag) || tags?.includes("*"))
-                return c.body(null, 304);
             c.header("content-type", "application/json; charset=utf-8");
-            return c.body(published.body);
+            return c.body(published);
         }
         catch {
             // Never let the app's path logger print a capability URL.

package/dist/web/config.js

@@ -1,9 +1,12 @@
 // The agent files a scope is configured by, through the ConfigStore. Not via
 // web/fs.ts: a scope is "global" or a cwd Pi already knows, never a browser path.
 import { isThinkingLevel } from "../core/types.js";
+import { SNAPSHOT_FILES } from "../agent/types.js";
 import { normalizeModelRef } from "../settings.js";
+import { managedRefusal } from "./config-sync.js";
 import { guarded } from "./route.js";
-export function registerConfigRoutes(app, { factory, config, onConfigWritten }) {
+export function registerConfigRoutes(app, { factory, config, onConfigWritten, subscribed = () => false }) {
+    const managed = (scope, name) => scope.kind === "global" && subscribed() && SNAPSHOT_FILES.includes(name);
     // Only cwds Pi already knows are accepted — never an arbitrary path.
     const parseScope = async (raw) => {
         if (!raw || raw === "global")
@@ -19,7 +22,7 @@ export function registerConfigRoutes(app, { factory, config, onConfigWritten })
         return c.json({
             // Where this scope's files live on disk — the UI labels "Global" with it.
             dir: scope.kind === "global" ? config.globalDir : scope.cwd,
-            files: await config.listFiles(scope),
+            files: (await config.listFiles(scope)).map((file) => ({ ...file, managed: managed(scope, file.name) })),
         });
     });
     guarded(app, "GET", "/api/config/files/:name", 400, async (c) => {
@@ -38,6 +41,8 @@ export function registerConfigRoutes(app, { factory, config, onConfigWritten })
             return c.json({ error: "content and expected content required" }, 400);
         }
         const name = c.req.param("name");
+        if (managed(scope, name))
+            return managedRefusal(c);
         await config.writeFile(scope, name, body.content, body.expected);
         onConfigWritten?.();
         return c.json({ ok: true, content: await config.readFile(scope, name) });
@@ -48,6 +53,8 @@ export function registerConfigRoutes(app, { factory, config, onConfigWritten })
         return c.json(await config.readDefaults());
     });
     guarded(app, "PUT", "/api/config/defaults", 400, async (c) => {
+        if (subscribed())
+            return managedRefusal(c);
         const defaults = parseDefaults(await c.req.json().catch(() => null));
         if (!defaults) {
             return c.json({ error: "defaultModel must be {provider, id} or null; defaultThinkingLevel a reasoning level or null" }, 400);

package/dist/web/explorer.js

@@ -1,4 +1,4 @@
-// What git knows about a project directory, for the Files view. Every route
+// What git knows about a project directory, for the Files dialog. Every route
 // runs git and nothing else; reading files is web/fs.ts.
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -11,7 +11,7 @@ const REF_RE = /^[^-\s][^\s]*$/;
 /** Output capped: a diff is display data, not an archive. */
 const git = async (root, ...args) => (await run("git", ["-C", root, ...args], { maxBuffer: MAX_DIFF_BYTES })).stdout;
 export function registerExplorerRoutes(app) {
-    // Not a repo → { branch: null }: the Files view draws no compare, no filter.
+    // Not a repo → { branch: null }: the Files dialog draws no compare, no filter.
     guarded(app, "GET", "/api/explorer/git", 404, async (c) => {
         c.header("cache-control", "no-store");
         const root = await scoped(c.req.query("root"));