@sema-agent/core 7.55.0 → 7.56.0

package/dist/scenarios/full-body.js

@@ -2,7 +2,7 @@ import { webFetchToolSpec, createWebSearchTool } from "../tools/web.js";
 import { createTodoWriteTool } from "../tools/todo.js";
 import { createTaskListTools } from "../tools/task-list.js";
 import { createSubagentTool } from "../agents/subagent.js";
-import { CODE_SYSTEM_PROMPT } from "../prompts/default.js";
+import { namesRoleBase } from "../prompt-assembly/role-base.js";
 export function assembleCodeTools(cfg = {}) {
     const web = [webFetchToolSpec(cfg.webFetch ?? {})];
     if (cfg.webSearch)
@@ -19,13 +19,14 @@ export function assembleCodeTools(cfg = {}) {
     }
     const tools = [...web];
     if (cfg.subagent) {
+        const roleBase = namesRoleBase(cfg.subagent) ? {} : { promptRole: "code" };
         tools.push(createSubagentTool({
             ...cfg.subagent,
-            systemPrompt: cfg.subagent.systemPrompt ?? CODE_SYSTEM_PROMPT,
+            ...roleBase,
             inheritedTools: cfg.subagent.inheritedTools ?? [...web, ...scaffolds],
         }));
     }
     tools.push(...scaffolds);
     return tools;
 }
-export const CODE_ROLE = { systemPrompt: CODE_SYSTEM_PROMPT, thinking: "high" };
+export const CODE_ROLE = { promptRole: "code", thinking: "high" };

package/dist/shell/lex.js

@@ -1169,6 +1169,7 @@ function scan(source, connectorsAreText, segments, level, list) {
     let assignmentSeen = false;
     let subscriptsClosed = false;
     let commandWord;
+    let arithParens = 0;
     let w = new WordBuilder();
     const next = (j) => past(source, j + 1);
     const quotedBy = () => (inSingle || inDouble ? regionBy : undefined);
@@ -1503,7 +1504,7 @@ function scan(source, connectorsAreText, segments, level, list) {
             take(ch, i);
             continue;
         }
-        if (ch === "#" && !w.started) {
+        if (ch === "#" && !w.started && arithParens === 0) {
             const nl = source.indexOf("\n", i);
             i = nl < 0 ? source.length : nl - 1;
             continue;
@@ -1531,6 +1532,14 @@ function scan(source, connectorsAreText, segments, level, list) {
             const r = endWord() ?? operandOwed(i);
             if (r !== undefined)
                 return r;
+            if (ch === "(") {
+                if (arithParens > 0)
+                    arithParens++;
+                else if (split && source[next(i)] === "(")
+                    arithParens = 1;
+            }
+            else if (arithParens > 0)
+                arithParens--;
             current().tokens.push({ kind: "group", op: ch });
             resetPosition();
             continue;

package/dist/stores/file/adoption/adopt.js

@@ -8,6 +8,7 @@ import { SessionPolicyError } from "../../../core/session-policy-store.js";
 import { thrownText } from "../../../core/thrown-value.js";
 import { AdoptionError, NOT_MIGRATED_BY_DESIGN, readRootAdoptionFile, writeRootAdoptionFile, } from "./marker.js";
 import { readRuleOwner, ruleOwnerText, sameRuleOwner } from "../../../core/rule-owner.js";
+import { principalNameOf } from "../../../core/principal-name.js";
 const CONFIG_ACCOUNT_FILE = "adoption-configs.json";
 function baselineConfigs(toPrincipal) {
     return [
@@ -333,12 +334,12 @@ function answerFromExisting(root, existing, from, toPrincipal) {
     return undefined;
 }
 export async function adoptLocalDataRoot(opts) {
-    if (typeof opts.toPrincipal !== "string" || opts.toPrincipal === "") {
-        throw new AdoptionError("adoption_bad_request", "adoptLocalDataRoot requires the adopting principal — adoption is the act of giving this data root an identity");
+    if (principalNameOf(opts.toPrincipal) === undefined) {
+        throw new AdoptionError("adoption_bad_request", "adoptLocalDataRoot requires the adopting principal, a principal name — adoption is the act of giving this data root an identity");
     }
     const from = readRuleOwner(opts.from);
     if (from === undefined) {
-        throw new AdoptionError("adoption_bad_request", "the adoption source must be the local-owner kind or a principal with a non-blank name — local-single-user identity is the local-owner kind, never a blank string");
+        throw new AdoptionError("adoption_bad_request", "the adoption source must be the local-owner kind or a principal owner whose principal is a principal name — local-single-user identity is the local-owner kind, never a blank string");
     }
     if (from.kind === "principal" && from.principal === opts.toPrincipal) {
         throw new AdoptionError("adoption_bad_request", `the data root already belongs to "${opts.toPrincipal}" — there is nothing to adopt`);

package/dist/stores/file/adoption/marker.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { readRuleOwner, sameRuleOwner } from "../../../core/rule-owner.js";
+import { principalNameOf } from "../../../core/principal-name.js";
 import { atomicWriteFile, ensureDir } from "../fs-atomic.js";
 export class AdoptionError extends Error {
     code;
@@ -39,7 +40,7 @@ function isRootAdoptionFileShape(v) {
             typeof m !== "object" ||
             typeof m.adoptionId !== "string" ||
             readRuleOwner(m.from) === undefined ||
-            typeof m.toPrincipal !== "string" ||
+            principalNameOf(m.toPrincipal) === undefined ||
             typeof m.phase !== "number" ||
             ![2, 3, 4, 5].includes(m.phase)) {
             return false;
@@ -88,7 +89,7 @@ function isRootAdoptionFileShape(v) {
         if (a === null ||
             typeof a !== "object" ||
             from === undefined ||
-            typeof a.toPrincipal !== "string" ||
+            principalNameOf(a.toPrincipal) === undefined ||
             typeof a.atMs !== "number" ||
             a.immutableReport === null ||
             typeof a.immutableReport !== "object") {

package/dist/stores/file/checkpoint-store.d.ts

@@ -1,6 +1,8 @@
 import { type ExecutionOutcomeRecordWord } from "../../core/checkpoint-execution-record.js";
+import { type HolderJudge } from "../../core/checkpoint-generation.js";
 import { type Checkpoint, type PendingSteerInput, type CheckpointFaultMode, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "../../core/checkpoint-store.js";
 import type { GateOutcome } from "../../core/gate-outcome.js";
+import { type CheckpointDeleteGuard, type CheckpointOverdueCursor, type CheckpointOverdueQuery, type CheckpointPage, type CheckpointRowRead, type CheckpointSessionCursor, type CheckpointSessionQuery } from "../../core/checkpoint-queries.js";
 import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 export interface FileCheckpointStoreOptions {
     /** This store's half of {@link import("./shared-ledger.js").LedgerPaths.onCorruptRead}. */
@@ -11,6 +13,13 @@ export interface FileCheckpointStoreOptions {
     fsync?: boolean;
     /** Compact the ledger into a snapshot once it exceeds this many events (then truncate). Default 1000. */
     compactEvery?: number;
+    /** The session head read (a session store's `headOf`) {@link FileCheckpointStore.deleteSessionCheckpoints} judges its guard by;
+     *  without it the store has no `deleteSessionCheckpoints` member. */
+    sessionHeadOf?: (sessionId: string) => Promise<{
+        readonly owner: string | null;
+    } | undefined>;
+    /** The judge of a resolve's claim holder ({@link HolderJudge}); with it the store declares `fence = { holder: true }`. */
+    holderIsCurrent?: HolderJudge;
 }
 export declare class FileCheckpointStore implements CheckpointStore {
     /** design/173 §2.3 — honest declaration on the restart-survival axis the vocabulary claims: rows
@@ -34,6 +43,11 @@ export declare class FileCheckpointStore implements CheckpointStore {
     readonly execution: {
         readonly outcome: true;
     };
+    /** Declared exactly when the store was built with a `holderIsCurrent` judge. */
+    readonly fence?: {
+        readonly holder: true;
+    };
+    private readonly holderIsCurrent;
     private readonly fsyncEnabled;
     private readonly compactEvery;
     /** RB-134: the directory's ONE authority (map + token mutex + append log), joined not rebuilt. */
@@ -45,6 +59,8 @@ export declare class FileCheckpointStore implements CheckpointStore {
     /** The guarded {@link FileCheckpointStoreOptions.onCorruptRead} seat (the ledger's replay and this store's projection share it). */
     private readonly discloseCorrupt;
     private readonly ledgerPath;
+    /** Present exactly when the store was built with a session head read (`FileCheckpointStoreOptions.sessionHeadOf`). */
+    readonly deleteSessionCheckpoints?: (sessionId: string, guard: CheckpointDeleteGuard) => Promise<number>;
     constructor(root: string, opts?: FileCheckpointStoreOptions);
     /** Serialize an op behind any in-flight op on the same token (the in-process per-token async mutex). */
     private withLock;
@@ -69,6 +85,11 @@ export declare class FileCheckpointStore implements CheckpointStore {
     reap(scope: string, cutoff: number): Promise<number>;
     listByScope(scope: string): Promise<CheckpointSummary[]>;
     listScopes(): Promise<string[]>;
+    /** The listing faces' disclosure: a row read past a damage is reported through the corrupt-read seat, named by its non-secret
+     *  identity (never its token). */
+    private listingDisclose;
+    listOverdue(query: CheckpointOverdueQuery): Promise<CheckpointPage<CheckpointSummary, CheckpointOverdueCursor>>;
+    listBySession(query: CheckpointSessionQuery): Promise<CheckpointPage<CheckpointRowRead, CheckpointSessionCursor>>;
     /** Force a compaction now (test/inspection). The snapshot rewrite + RB-167 closeForSwap swap that
      *  makes `replay` read the full state from the snapshot alone is the base's {@link LedgerCore.compact}. */
     compactNow(): void;

package/dist/stores/file/checkpoint-store.js

@@ -1,7 +1,9 @@
 import { join } from "node:path";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { checkpointExecutionRecorded, executionRecordDisposition, ExecutionOutcomeConflictError, } from "../../core/checkpoint-execution-record.js";
-import { appendPendingSteer, CheckpointError, checkpointOccMatches, checkpointRowMatches, encodeAtFidelity, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
+import { checkpointHolderMatches, checkpointOccMatches, checkpointRevOf } from "../../core/checkpoint-generation.js";
+import { appendPendingSteer, CheckpointError, checkpointRowMatches, encodeAtFidelity, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
+import { checkpointDeadlinePassed, deleteSessionRowsAtStart, readCheckpointOverdueQuery, readCheckpointSessionQuery, selectOverduePage, selectSessionPage, } from "../../core/checkpoint-queries.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
 const CHECKPOINT_LEDGER_EVENT_REGISTRY = {
@@ -10,6 +12,7 @@ const CHECKPOINT_LEDGER_EVENT_REGISTRY = {
     reopen: true,
     execution: true,
     expire: true,
+    delete: true,
     steer_append: true,
 };
 const KNOWN_CHECKPOINT_LEDGER_EVENTS = new Set(Object.keys(CHECKPOINT_LEDGER_EVENT_REGISTRY));
@@ -45,6 +48,9 @@ function applyCheckpointEvent(cps, ev) {
         case "expire":
             cp.status = "expired";
             break;
+        case "delete":
+            cps.delete(ev.token);
+            break;
         case "steer_append": {
             const queue = cp.state.pendingSteerQueue ?? [];
             if (!queue.some((e) => e.inputId === ev.entry.inputId))
@@ -84,6 +90,7 @@ export class FileCheckpointStore {
     fidelity = "json";
     redecision = { reopen: true };
     execution = { outcome: true };
+    holderIsCurrent;
     fsyncEnabled;
     compactEvery;
     ledger;
@@ -97,6 +104,9 @@ export class FileCheckpointStore {
     constructor(root, opts = {}) {
         assertAdoptionBootGate(root, "FileCheckpointStore");
         this.fsyncEnabled = opts.fsync !== false;
+        this.holderIsCurrent = opts.holderIsCurrent;
+        if (opts.holderIsCurrent !== undefined)
+            this.fence = Object.freeze({ holder: true });
         this.compactEvery = opts.compactEvery ?? 1000;
         this.discloseCorrupt = guardCorruptSink(opts.onCorruptRead);
         const dir = join(root, "checkpoints");
@@ -108,6 +118,15 @@ export class FileCheckpointStore {
             ledgerPath: this.ledgerPath,
             snapshotPath: join(dir, "checkpoints.snapshot.jsonl"),
         });
+        const headOf = opts.sessionHeadOf;
+        if (headOf !== undefined) {
+            this.deleteSessionCheckpoints = (sessionId, guard) => deleteSessionRowsAtStart(this.cps, sessionId, guard, headOf, (token, row) => this.withLock(token, () => {
+                if (this.cps.get(token) !== row)
+                    return false;
+                this.commit({ t: "delete", token }, true);
+                return true;
+            }));
+        }
     }
     withLock(token, fn) {
         return this.ledger.withLock(token, fn);
@@ -144,8 +163,11 @@ export class FileCheckpointStore {
             if (!checkpointOccMatches(cp, expect)) {
                 return false;
             }
+            if (!checkpointHolderMatches(expect, this.holderIsCurrent)) {
+                return false;
+            }
             const winner = winnerFromOutcome(outcome);
-            const rev = (cp.rev ?? 0) + 1;
+            const rev = checkpointRevOf(cp) + 1;
             this.commit({ t: "resolve", token, rev, resolvedOutcome: winner }, true);
             if (this.fault === "resolve-after-commit") {
                 this.fault = null;
@@ -172,7 +194,7 @@ export class FileCheckpointStore {
             if (!checkpointRowMatches(cp, scope, "resolved") || checkpointExecutionRecorded(cp)) {
                 return false;
             }
-            const rev = (cp.rev ?? 0) + 1;
+            const rev = checkpointRevOf(cp) + 1;
             this.commit({ t: "reopen", token, rev, reason }, true);
             return true;
         });
@@ -204,7 +226,7 @@ export class FileCheckpointStore {
     }
     async reap(scope, cutoff) {
         let n = 0;
-        const deadlinePassed = (deadline) => deadline !== undefined && (Number.isFinite(deadline) ? deadline <= cutoff : true);
+        const deadlinePassed = (deadline) => checkpointDeadlinePassed(deadline, cutoff);
         const candidates = [...this.cps.values()].filter((cp) => cp.scope === scope && cp.status === "pending" && deadlinePassed(cp.deadline));
         for (const cp of candidates) {
             const won = await this.withLock(cp.token, () => {
@@ -222,8 +244,7 @@ export class FileCheckpointStore {
         return n;
     }
     async listByScope(scope) {
-        const sink = this.discloseCorrupt;
-        const disclose = sink === undefined ? undefined : (sentence) => sink({ kind: "file", path: this.ledgerPath, reason: sentence });
+        const disclose = this.listingDisclose();
         const out = [];
         for (const cp of this.cps.values()) {
             if (cp.scope === scope && cp.status === "pending")
@@ -238,6 +259,17 @@ export class FileCheckpointStore {
                 out.add(cp.scope);
         return [...out];
     }
+    listingDisclose() {
+        const sink = this.discloseCorrupt;
+        return sink === undefined ? undefined : (sentence) => sink({ kind: "file", path: this.ledgerPath, reason: sentence });
+    }
+    async listOverdue(query) {
+        const disclose = this.listingDisclose();
+        return selectOverduePage(this.cps.entries(), readCheckpointOverdueQuery(query), (cp) => summarizeCheckpoint(cp, disclose), disclose);
+    }
+    async listBySession(query) {
+        return selectSessionPage(this.cps.entries(), readCheckpointSessionQuery(query), (cp) => structuredClone(cp), this.listingDisclose());
+    }
     compactNow() {
         this.ledger.compact();
     }

package/dist/stores/file/file-history-store.js

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { appendFileSync, closeSync, existsSync, fsyncSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { thrownText } from "../../core/thrown-value.js";
-import { applyFileRestoreViaEnv, boundaryPublishVerdict, worldStillMatchesMint, captureFileBackupViaEnv, modeProvenDifferent, previewFileDelta, describeTrackKey, fileHistoryExportDigest, caughtFault, DAMAGED_RECORD, resolveTrackKey, trackKeyOf, validateFileHistoryExport, } from "../../core/file-history-store.js";
+import { applyFileRestoreViaEnv, boundaryPublishVerdict, worldStillMatchesMint, annulProofFailure, captureFileBackupViaEnv, modeProvenDifferent, previewFileDelta, describeTrackKey, fileHistoryExportDigest, caughtFault, DAMAGED_RECORD, resolveTrackKey, trackKeyOf, validateFileHistoryExport, } from "../../core/file-history-store.js";
 import { fileHistoryBoundariesToKeep, resolveFileHistoryRetention } from "../../core/file-history-retention.js";
 import { atomicWriteFile, ensureDir, sanitizePathComponent, sanitizeScope, writeThenLink } from "./fs-atomic.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
@@ -481,9 +481,8 @@ export class FileFileHistoryStore {
                 return { ok: false, error: { code: "conflict", message: `first-touch record for ${absPath} has since been served to another edit of the same path — it is that edit's baseline now, not a retractable mint` } };
             }
             const proof = verify === undefined ? undefined : await worldStillMatchesMint(verify.env, absPath, root, rec.baseAvailable, rec.versions[0]?.blobHash ?? null, verify.signal);
-            if (proof !== undefined && !proof.unchanged) {
-                return { ok: false, error: { code: "conflict", message: `first-touch record for ${absPath} is NOT retractable: ${proof.reason} — the write this retraction compensates for may have changed the file` } };
-            }
+            if (proof !== undefined && proof.verdict !== "unchanged")
+                return annulProofFailure(proof, absPath);
             const fresh = this.readTrackedState(scope);
             if (fresh.corrupt)
                 return { ok: false, error: { code: "track_failed", message: `file history for scope "${scope}" became unreadable — the record was left in place`, ...fresh.fault } };
@@ -723,7 +722,7 @@ export class FileFileHistoryStore {
                 let targetVersion = boundary.get(key);
                 if (targetVersion === undefined) {
                     if (!rec.baseAvailable) {
-                        ledger.refused.push({ path: key, reason: "base_unavailable" });
+                        ledger.refused.push({ path: key, reason: "base_unavailable", class: "base_unavailable" });
                         continue;
                     }
                     targetVersion = 1;
@@ -735,7 +734,7 @@ export class FileFileHistoryStore {
                 }
                 const resolved = resolveTrackKey(root, key, descriptorOf(rec));
                 if (!resolved.ok) {
-                    ledger.refused.push({ path: key, reason: resolved.reason });
+                    ledger.refused.push({ path: key, reason: resolved.reason, class: resolved.class });
                     continue;
                 }
                 let target;
@@ -777,7 +776,7 @@ export class FileFileHistoryStore {
                 else if (applied.outcome === "identical")
                     ledger.identicalSkipped.push(key);
                 else if (applied.outcome === "refused")
-                    ledger.refused.push({ path: key, reason: applied.reason });
+                    ledger.refused.push({ path: key, reason: applied.reason, class: applied.class });
                 else
                     ledger.failed.push({ path: key, reason: applied.reason });
                 if ((applied.outcome === "applied" || applied.outcome === "identical") && applied.modeNotPreserved === true)

package/dist/stores/file/index.js

@@ -62,7 +62,8 @@ export class FileStorageBackend {
             this.fileSessions = repo;
             this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable", placements: { subagent: { durability: "durable" } } });
             this.sessionStore = this.ttl;
-            this.fileCheckpoints = new FileCheckpointStore(this.root, { ...opts.checkpoint, ...corruptRead });
+            const sessionHeadOf = this.ttl.headOf;
+            this.fileCheckpoints = new FileCheckpointStore(this.root, { ...opts.checkpoint, ...corruptRead, ...(sessionHeadOf !== undefined ? { sessionHeadOf } : {}) });
             built.push(() => this.fileCheckpoints.close());
             this.checkpointStore = this.fileCheckpoints;
             this.fileMemory = new FileMemoryStore(this.root, opts.embedder ? { embedder: opts.embedder } : {});

package/dist/stores/file/permission-rule-adopt.js

@@ -2,18 +2,19 @@ import { existsSync, renameSync } from "node:fs";
 import { join } from "node:path";
 import { writerOf } from "../../core/permission-rule-store.js";
 import { readRuleOwner, ruleOwnerText, sameRuleOwner } from "../../core/rule-owner.js";
+import { principalNameOf } from "../../core/principal-name.js";
 import { createPermissionRuleStoreProvider } from "../../core/permission-rule-provider.js";
 import { syncPermissionRules } from "../../core/permission-rule-sync.js";
 import { thrownText } from "../../core/thrown-value.js";
 import { FileStoreLockError } from "./fs-atomic.js";
 import { FileDurableRulePartitionProvider, LOCAL_OWNER_FILE, principalRuleFileName, readRuleAdoptionFile, writeRuleAdoptionFile, } from "./permission-rule-store.js";
 export async function adoptFilePermissionRuleStore(opts) {
-    if (typeof opts.toPrincipal !== "string" || opts.toPrincipal === "") {
-        throw new Error("adoptFilePermissionRuleStore requires the adopting principal — adoption is the act of giving this bucket an identity");
+    if (principalNameOf(opts.toPrincipal) === undefined) {
+        throw new Error("adoptFilePermissionRuleStore requires the adopting principal, a principal name — adoption is the act of giving this bucket an identity");
     }
     const from = readRuleOwner(opts.from);
     if (from === undefined) {
-        throw new Error("adoptFilePermissionRuleStore requires a source owner — a principal with a non-blank name, or the local owner");
+        throw new Error("adoptFilePermissionRuleStore requires a source owner — a principal owner whose principal is a principal name, or the local owner");
     }
     if (from.kind === "principal" && from.principal === opts.toPrincipal) {
         throw new Error(`the bucket already belongs to "${opts.toPrincipal}" — there is nothing to adopt`);

package/dist/stores/file/permission-rule-store.js

@@ -4,6 +4,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { isRuleBehavior } from "../../core/permission-rule-model.js";
 import { posixModeBitsMeaningful } from "../../core/posix-mode-face.js";
 import { readRuleOwner } from "../../core/rule-owner.js";
+import { principalNameOf, readPrincipal } from "../../core/principal-name.js";
 import { PERMISSION_RULES_LATER_GRAMMAR_CODE, PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, unknownRuleWriteDeltaError, } from "../../core/permission-rule-store.js";
 import { sameOrgPolicyContent } from "../../core/permission-rule-org.js";
 import { SESSION_RULES_GRAMMAR, readRuleGrammarStamp } from "../../core/session-policy-store.js";
@@ -66,7 +67,7 @@ function isRuleAdoptionFileShape(v) {
     const rec = (hasMarker ? v.marker : v.adopted);
     if (rec === null || typeof rec !== "object")
         return false;
-    if (readRuleOwner(rec.from) === undefined || typeof rec.toPrincipal !== "string" || rec.toPrincipal === "")
+    if (readRuleOwner(rec.from) === undefined || principalNameOf(rec.toPrincipal) === undefined)
         return false;
     return hasMarker ? rec.phase === 2 || rec.phase === 3 || rec.phase === 4 || rec.phase === 5 : typeof rec.atMs === "number" && Number.isFinite(rec.atMs);
 }
@@ -452,17 +453,22 @@ export class FileDurableRulePartitionProvider {
         this.lock = lock;
     };
     forPrincipal(principal) {
-        if (typeof principal !== "string" || principal === "") {
+        const reading = readPrincipal(principal);
+        if (reading.kind === "invalid") {
+            throw new Error(`the principal given is not a principal name (got ${reading.fault}) — refusing to resolve a bucket for it; a provided value that names nobody is not "no principal"`);
+        }
+        if (reading.kind === "absent") {
             return { list: async () => ({ ...EMPTY_READ }), durability: "process-local" };
         }
+        const name = reading.name;
         const adoption = this.adoptionMarker();
         if (adoption !== undefined) {
             const rec = "adopted" in adoption ? adoption.adopted : adoption.marker;
-            if (rec.from.kind === "principal" && rec.from.principal === principal) {
-                return this.readOnlySourceView(principalRuleFileName(principal), principalRuleFileName(rec.toPrincipal), "adopted" in adoption || adoption.marker.phase >= 4);
+            if (rec.from.kind === "principal" && rec.from.principal === name) {
+                return this.readOnlySourceView(principalRuleFileName(name), principalRuleFileName(rec.toPrincipal), "adopted" in adoption || adoption.marker.phase >= 4);
             }
         }
-        return new FileDurableRulePartition(this.dir, join(this.dir, principalRuleFileName(principal)), this.acquireWriteLock, this.onError, this.vetting);
+        return new FileDurableRulePartition(this.dir, join(this.dir, principalRuleFileName(name)), this.acquireWriteLock, this.onError, this.vetting);
     }
     readOnlySourceView(sourceName, targetName, flipped) {
         const pick = flipped ? targetName : existsSync(join(this.dir, sourceName)) ? sourceName : targetName;

package/dist/stores/file/session-store.d.ts

@@ -1,4 +1,4 @@
-import type { Session, SessionCreateOptions, SessionForkOptions, SessionHead, SessionMetadata, SessionPlacementRecord, SessionRepo, SessionTreeEntry } from "../../internal/harness.js";
+import type { Session, SessionCreateOptions, SessionForkOptions, SessionHead, SessionMetadata, SessionPlacementRecord, SessionRepo, SessionRow, SessionTreeEntry } from "../../internal/harness.js";
 import type { PlacedSessionRow } from "../../core/session.js";
 import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 export interface FileSessionRepoOptions {
@@ -8,8 +8,9 @@ export interface FileSessionRepoOptions {
      * "corrupt read as missing" are one failure grammar, so they get one seat name.
      *
      * Fires for: an unreadable sessions DIRECTORY (the listing degrades to "no sessions"), a session log
-     * that could not be replayed during a listing (skipped from the result), and each corrupt interior JSONL
-     * record dropped on replay plus that replay's tally (turns missing from an otherwise healthy session).
+     * whose header could not be read during a listing (skipped from the result — a listing reads headers,
+     * it never replays a log), and each corrupt interior JSONL record dropped on replay plus that replay's
+     * tally (turns missing from an otherwise healthy session).
      *
      * Never fires on plain ENOENT / `not_found` — that is honest absence, and the torn TAIL stays silent
      * too (dying mid-write is the append log's documented crash-recovery shape, not corruption).
@@ -59,6 +60,15 @@ export declare class FileSessionRepo implements SessionRepo {
      * head does not see. A leaf entry naming an id the log does not hold is not checked here (a replay refuses that log on open).
      */
     headOf(sessionId: string): Promise<SessionHead | undefined>;
+    /**
+     * The row's {@link SessionRow} — its header cells and the newest write it holds, the log's modification time (every write to a row
+     * is an append to its log; the placed listing's age reads the same time) — in one read of the header, never a replay of the log.
+     * `undefined` = no row; a row whose header cannot be read rejects (`corrupt_session`).
+     */
+    private rowOf;
+    /** The one descriptor a by-id read of the row takes: its size and modification time and its header, from one inode (a file replaced
+     *  or removed while this reads is still the inode this descriptor opened); `undefined` = no file. */
+    private atRow;
     private storage;
     /**
      * RB-437 — release every shared authority this repo joined (LAST holder ⇒ evict + close the append fd).
@@ -75,12 +85,25 @@ export declare class FileSessionRepo implements SessionRepo {
     dispose(): Promise<void>;
     create(options?: SessionCreateOptions): Promise<Session>;
     open(metadata: SessionMetadata): Promise<Session>;
-    list(): Promise<SessionMetadata[]>;
+    /** Record activity on the row now: its log's modification time — the one time a listing reads, which every append moves too — is
+     *  set to now, the log's bytes untouched. A missing file is nothing to record; any other fault rejects. */
+    touch(sessionId: string): Promise<void>;
+    /** Every ordinary row with the newest write its log holds ({@link rowOf}): one header read per session file, no replay — what a
+     *  listing costs grows with the number of sessions, never with their history. Placed rows are the placed listing's. */
+    list(): Promise<SessionRow[]>;
+    /**
+     * Every row of the sessions directory, each read by {@link rowOf}. The listing degrades to "no sessions" so a
+     * browse face never throws — but "I could not read the directory" and "there are none" are different facts, and only the sink can
+     * tell them apart (ENOENT is honest absence: the constructor creates the directory, so it was removed underneath us). A session
+     * whose header cannot be read is skipped and disclosed — it exists and is missing from the listing — while a file that vanished
+     * between the directory read and its own is honest absence.
+     */
+    private rows;
     /**
      * Subagent transcript persistence — the PLACED partition's own enumeration (the joint reap's
      * partition-leg input; `TtlSessionStore` re-exposes it verbatim). Age (`olderThanMs`) is judged on
-     * the session FILE's mtime — the transcript's last append — falling back to `placedAt` when the
-     * stat fails (mtime is also the CC orphan-adoption window's basis, so the two age reads agree).
+     * the session FILE's mtime — the transcript's last append, the time the host listing reads too
+     * (mtime is also the CC orphan-adoption window's basis, so the age reads agree).
      * Rows missing either `(scope, handle)` join half return the honest `tupleIncomplete` variant
      * (consumers fail closed on it — never age-reaped, see the SessionStore contract).
      */

package/dist/stores/file/session-store.js

@@ -1,4 +1,4 @@
-import { closeSync, existsSync, fstatSync, openSync, readdirSync, rmSync, statSync } from "node:fs";
+import { closeSync, existsSync, fstatSync, openSync, readdirSync, rmSync, utimesSync } from "node:fs";
 import { join } from "node:path";
 import { BaseSessionStorage, StoredSession, SessionError, assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, leafIdAfterEntry, ownerCell, readIncarnationCell, readOwnerCell, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
 import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, firstJsonlRecord, lastJsonlRecord, readJsonlRecords, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
@@ -125,6 +125,15 @@ export class FileSessionRepo {
         };
     }
     async headOf(sessionId) {
+        return this.atRow(sessionId, (fd, size, meta) => {
+            const last = lastJsonlRecord(fd, size, (r) => r.kind === "entry", SESSION_LINE_JUDGE);
+            return { owner: meta.owner ?? null, incarnation: meta.incarnation, leafId: last === undefined ? null : leafIdAfterEntry(last.entry) };
+        });
+    }
+    rowOf(sessionId) {
+        return this.atRow(sessionId, (_fd, _size, meta, mtimeMs) => ({ ...meta, lastActiveAt: Math.trunc(mtimeMs) }));
+    }
+    atRow(sessionId, read) {
         const path = this.pathFor(sessionId);
         let fd;
         try {
@@ -136,10 +145,8 @@ export class FileSessionRepo {
             throw err;
         }
         try {
-            const size = fstatSync(fd).size;
-            const meta = this.headerOf(sessionId, path, firstJsonlRecord(fd, size, SESSION_LINE_JUDGE));
-            const last = lastJsonlRecord(fd, size, (r) => r.kind === "entry", SESSION_LINE_JUDGE);
-            return { owner: meta.owner ?? null, incarnation: meta.incarnation, leafId: last === undefined ? null : leafIdAfterEntry(last.entry) };
+            const { size, mtimeMs } = fstatSync(fd);
+            return read(fd, size, this.headerOf(sessionId, path, firstJsonlRecord(fd, size, SESSION_LINE_JUDGE)), mtimeMs);
         }
         finally {
             closeSync(fd);
@@ -201,80 +208,65 @@ export class FileSessionRepo {
         const { meta, entries } = this.read(metadata.id);
         return new StoredSession(this.storage(meta, entries));
     }
-    async list() {
-        let names;
+    async touch(sessionId) {
+        const now = new Date();
         try {
-            names = readdirSync(this.dir);
+            utimesSync(this.pathFor(sessionId), now, now);
         }
         catch (err) {
-            if (err.code !== "ENOENT") {
-                this.disclose(this.dir, `session directory unreadable (${err.code ?? "unknown"}) — listed as empty`);
-            }
-            return [];
-        }
-        const out = [];
-        for (const name of names) {
-            if (!name.endsWith(SUFFIX))
-                continue;
-            const id = name.slice(0, -SUFFIX.length);
-            try {
-                const { createdAt, forkedFrom, placement } = this.read(id).meta;
-                if (placement !== undefined)
-                    continue;
-                out.push({ id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}) });
-            }
-            catch (err) {
-                if (!(err instanceof SessionError && err.code === "not_found")) {
-                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the listing`, id);
-                }
-            }
+            if (err.code === "ENOENT")
+                return;
+            throw new SessionError("storage", `session ${sessionId}'s activity could not be recorded: ${thrownText(err)}`, err instanceof Error ? err : undefined);
         }
-        return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
     }
-    async listPlaced(kind, opts) {
+    async list() {
+        return this.rows("the listing")
+            .filter((row) => row.placement === undefined)
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    rows(listing) {
         let names;
         try {
             names = readdirSync(this.dir);
         }
         catch (err) {
             if (err.code !== "ENOENT") {
-                this.disclose(this.dir, `session directory unreadable (${err.code ?? "unknown"}) — placed listing degraded to empty`);
+                this.disclose(this.dir, `session directory unreadable (${err.code ?? "unknown"}) — ${listing} degraded to empty`);
             }
             return [];
         }
-        const now = Date.now();
         const out = [];
         for (const name of names) {
             if (!name.endsWith(SUFFIX))
                 continue;
             const id = name.slice(0, -SUFFIX.length);
-            let placement;
+            let row;
             try {
-                placement = this.read(id).meta.placement;
+                row = this.rowOf(id);
             }
             catch (err) {
-                if (!(err instanceof SessionError && err.code === "not_found")) {
-                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the placed listing`, id);
-                }
+                this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from ${listing}`, id);
                 continue;
             }
+            if (row !== undefined)
+                out.push(row);
+        }
+        return out;
+    }
+    async listPlaced(kind, opts) {
+        const now = Date.now();
+        const out = [];
+        for (const row of this.rows("the placed listing")) {
+            const placement = row.placement;
             if (placement === undefined || placement.kind !== kind)
                 continue;
             if (opts?.scope !== undefined && placement.scope !== opts.scope)
                 continue;
-            if (opts?.olderThanMs !== undefined) {
-                let ageAnchor = placement.placedAt;
-                try {
-                    ageAnchor = statSync(this.pathFor(id)).mtimeMs;
-                }
-                catch {
-                }
-                if (now - ageAnchor <= opts.olderThanMs)
-                    continue;
-            }
+            if (opts?.olderThanMs !== undefined && now - row.lastActiveAt <= opts.olderThanMs)
+                continue;
             out.push(placement.scope !== undefined && placement.handle !== undefined
-                ? { sessionId: id, placedAt: placement.placedAt, scope: placement.scope, handle: placement.handle }
-                : { sessionId: id, placedAt: placement.placedAt, tupleIncomplete: true });
+                ? { sessionId: row.id, placedAt: placement.placedAt, scope: placement.scope, handle: placement.handle }
+                : { sessionId: row.id, placedAt: placement.placedAt, tupleIncomplete: true });
         }
         return out;
     }