@sema-agent/core 7.55.0 → 7.57.0

package/dist/core/session-policy-store.js

@@ -4,13 +4,15 @@ import { NAMESPACED_NAME_SHAPES } from "./protocol-table.js";
 import { callerToolNameProblem } from "./caller-tool-name.js";
 import { compileAllowList, compiledEntryName, inertEntryPhrase, readRuleEntry, renderListEntry, rootFacingToolNames } from "./allow-entry.js";
 import { valueTypeLabel } from "./tool-name-list.js";
-import { noticeRuleText } from "./permission-rule-model.js";
+import { NAME_RULE_FACES, noticeRuleText } from "./permission-rule-model.js";
+import { parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
+import { splitNamespacedName } from "./tool-name-aliases.js";
 const SESSION_RULE_BUCKETS = { toolAllow: "allow", toolDeny: "deny", allowDirs: "dirs" };
 const BUCKETS = Object.keys(SESSION_RULE_BUCKETS);
 const ENTRY_FIELDS = BUCKETS.filter((f) => SESSION_RULE_BUCKETS[f] !== "dirs");
 const STORE_STAMPS = new Set(["rev", "gen", "grammar"]);
 const OPERATOR_PART = "operatorRules";
-export const SESSION_RULES_GRAMMAR = 4;
+export const SESSION_RULES_GRAMMAR = 6;
 export class SessionPolicyError extends Error {
     code;
     detail;
@@ -149,42 +151,142 @@ function canonicalRules(read) {
     }
     return out;
 }
-function earlierGrammarReads(grammar, field, entry, reading) {
-    if (grammar >= SESSION_RULES_GRAMMAR)
-        return false;
-    if (reading.kind === "inert" && reading.reason === "grammar")
-        return true;
-    if (grammar !== 0 || SESSION_RULE_BUCKETS[field] !== "allow")
-        return false;
-    return reading.kind === "row" ? compiledEntryName(reading.compiled) !== entry : reading.reason === "wildcard_all";
-}
-function readsAsNoRule(entry, field) {
-    const reading = readRuleEntry(entry, SESSION_RULE_BUCKETS[field]);
-    return reading.kind === "inert" && reading.reason === "grammar";
+const NAMES_NO_TOOL = "an entry naming no tool, so it refused nothing";
+const NO_RULE_THEN = (direction) => (direction === "allow" ? "no rule, so it admitted nothing" : "no rule, so the rules could not be read and refused every call");
+const NAME_PATTERN_NOW = "a pattern over the whole tool name, every tool it matches";
+function spellsWholeProtocol(name) {
+    const split = splitNamespacedName(name);
+    return split !== undefined && split.peer === "*" && (split.tool === undefined || split.tool === "*");
+}
+const GRAMMAR_REVISIONS = [
+    {
+        grammar: 1,
+        answer: ({ direction, entry, reading }) => {
+            const otherName = reading.kind === "row" ? compiledEntryName(reading.compiled) !== entry : reading.reason === "wildcard_all";
+            if (!otherName)
+                return undefined;
+            if (direction === "allow")
+                return { was: "a tool name compared as written, naming no tool", now: "the rule it spells", keep: { kind: "inert", reason: "earlier_grammar" }, reader: "named_no_tool" };
+            return reading.kind === "row" ? { was: "a tool name compared as written, naming no tool, so it refused nothing", now: "the rule it spells", reader: "grammar_revised" } : undefined;
+        },
+    },
+    {
+        grammar: 3,
+        answer: ({ direction, reading }) => direction === "deny" && reading.kind === "row" && reading.compiled.kind === "covering" && spellsWholeProtocol(reading.compiled.pattern)
+            ? { was: NAMES_NO_TOOL, now: "a deny of every tool of the protocol", reader: "grammar_revised" }
+            : undefined,
+    },
+    {
+        grammar: 4,
+        answer: ({ direction, reading }) => {
+            if (reading.kind !== "row")
+                return undefined;
+            const { compiled } = reading;
+            if (compiled.kind === "name" && NAME_RULE_FACES[compiled.rule.tool]?.values === "mounted") {
+                return { was: direction === "allow" ? "an entry with no rule form, so it admitted nothing" : "an entry with no rule form, so it refused nothing", now: "a rule on the agent type it names", reader: "grammar_revised" };
+            }
+            return compiled.kind === "command" && compiled.rule.match === "pattern" ? { was: NO_RULE_THEN(direction), now: "the Bash pattern rule it spells", reader: "grammar_revised" } : undefined;
+        },
+    },
+    {
+        grammar: 5,
+        answer: ({ row, direction, entry, reading, list }) => {
+            if (direction === "allow") {
+                if (row >= 1 && list.some(readsAsWildcard))
+                    return { was: "voided by the `*` its list holds", now: "one entry that grants nothing, the entries beside it read as written", keep: { kind: "inert", reason: "wildcard_all" } };
+                const parsed = reading.kind === "inert" ? ruleSpellingOf(entry) : undefined;
+                const name = parsed?.ruleContent === undefined ? parsed?.toolName : undefined;
+                if (name === undefined || name === "*" || !name.includes("*") || name.startsWith("*") || splitNamespacedName(name) !== undefined)
+                    return undefined;
+                return { was: `the exact tool name ${JSON.stringify(name)}`, now: "no rule (an allow reads a `*` only in a protocol name's tool segment)", keep: { kind: "row", compiled: { kind: "tool", name } }, reader: "grammar_revised" };
+            }
+            if (reading.kind !== "row" || reading.compiled.kind !== "covering")
+                return undefined;
+            const { pattern } = reading.compiled;
+            const split = splitNamespacedName(pattern);
+            if (!pattern.includes("*") || spellsWholeProtocol(pattern) || (split !== undefined && !split.peer.includes("*")))
+                return undefined;
+            const answer = { now: NAME_PATTERN_NOW, reader: "grammar_revised" };
+            if (pattern === "*")
+                return { ...answer, was: NAMES_NO_TOOL, keep: { kind: "inert", reason: "wildcard_all" } };
+            if (split !== undefined)
+                return { ...answer, was: NAMES_NO_TOOL, keep: { kind: "inert", reason: "namespace_wildcard" } };
+            if (pattern.startsWith("*"))
+                return { ...answer, was: NO_RULE_THEN(direction) };
+            return { ...answer, was: `the exact tool name ${JSON.stringify(pattern)}, so it refused only a tool of that name`, keep: { kind: "row", compiled: { kind: "tool", name: pattern } } };
+        },
+    },
+];
+function earlierGrammarReads(row, direction, entry, reading, list) {
+    if (row >= SESSION_RULES_GRAMMAR)
+        return { reading };
+    let first;
+    let last;
+    let kept;
+    for (const revision of GRAMMAR_REVISIONS) {
+        if (revision.grammar <= row)
+            continue;
+        const answer = revision.answer({ row, direction, entry, reading, list });
+        if (answer === undefined)
+            continue;
+        first ??= answer;
+        last = answer;
+        if (answer.keep !== undefined) {
+            kept = answer.keep;
+            break;
+        }
+    }
+    const read = kept ?? reading;
+    if (read.kind === "inert" && read.reason === "grammar")
+        return { reading: { kind: "inert", reason: "earlier_grammar" }, reader: "no_rule" };
+    if (first === undefined || last === undefined)
+        return { reading: read };
+    const reader = first.reader === "named_no_tool" ? first.reader : last.reader;
+    if (reader === undefined)
+        return { reading: read };
+    return { reading: read, reader, ...(reader === "grammar_revised" ? { revised: { was: first.was, now: last.now, stands: kept !== undefined } } : {}) };
 }
 const NO_RULE_REASONS = new Set(["grammar", "earlier_grammar"]);
 export function unreadableDenyEntries(rules, roster) {
     return compileSessionRuleBucket(rules, "toolDeny", roster).inert.filter((i) => NO_RULE_REASONS.has(i.reason));
 }
-function readsAsWildcard(entry) {
-    return compileAllowList([entry], "allow").inert.some((i) => i.reason === "wildcard_all");
-}
 const STAR_IS_NO_ALLOW_RULE = "it is no allow rule in any grammar and a write holding it is refused";
 function starWayOut(onlyStars, others, left) {
     return onlyStars
         ? `"*" is no allow rule in any grammar (a write holding it is refused); to drop it, write the session's rules afresh without it ${REWRITE_THROUGH}; ${left}`
         : `${others}, leaving "*" out — ${STAR_IS_NO_ALLOW_RULE}; ${left}`;
 }
-export function compileSessionRuleBucket(rules, field, roster) {
+function readsAsWildcard(entry) {
+    return typeof entry === "string" && entry === entry.trim() && parsePermissionRule(entry).toolName === "*";
+}
+function entryBucketDirection(field) {
     const direction = SESSION_RULE_BUCKETS[field];
+    if (direction === "allow" || direction === "deny")
+        return direction;
+    throw new SessionPolicyError("invalid_shape", `${JSON.stringify(field)} is no rule-entry bucket of the session rules — the entry buckets are ${ENTRY_FIELDS.join(" and ")}`);
+}
+function bucketReadings(rules, field, roster) {
+    const direction = entryBucketDirection(field);
     const entries = rules[field] ?? [];
-    const earlier = new Set(entries.filter((e) => earlierGrammarReads(rules.grammar, field, e, readRuleEntry(e, direction, roster))));
-    const whole = compileAllowList(entries, direction, roster);
-    const voided = direction === "allow" && whole.inert.some((i) => i.reason === "wildcard_all");
-    if (earlier.size === 0 || (voided && rules.grammar > 0))
-        return whole;
-    const list = compileAllowList(entries.filter((e) => !earlier.has(e)), direction, roster);
-    return { rows: list.rows, inert: [...list.inert, ...entries.filter((e) => earlier.has(e)).map((entry) => ({ entry, reason: "earlier_grammar" }))] };
+    return entries.map((entry) => ({ entry, ...earlierGrammarReads(rules.grammar, direction, entry, readRuleEntry(entry, direction, roster), entries) }));
+}
+export function compileSessionRuleBucket(rules, field, roster) {
+    const rows = [];
+    const inert = [];
+    const earlier = [];
+    for (const { entry, reading } of bucketReadings(rules, field, roster)) {
+        if (reading.kind === "row")
+            rows.push({ entry, compiled: reading.compiled });
+        else {
+            const { kind: _kind, ...why } = reading;
+            void _kind;
+            (why.reason === "earlier_grammar" ? earlier : inert).push({ entry, ...why });
+        }
+    }
+    return { rows, inert: [...inert, ...earlier] };
+}
+export function earlierGrammarEntries(rules, field) {
+    return bucketReadings(rules, field).flatMap((r) => (r.reader === undefined ? [] : [r.entry]));
 }
 const ADVISORY_ENTRIES_SHOWN = 5;
 function shownEntries(entries, render) {
@@ -193,14 +295,33 @@ function shownEntries(entries, render) {
 }
 const REWRITE_THROUGH = `through this engine (an operator write of a new value without the stored row's rev; the write stamps grammar ${SESSION_RULES_GRAMMAR})`;
 export function earlierGrammarAdvisory(sessionId, entries, field, grammar) {
-    const read = earlierGrammarReadings(entries, field);
+    const read = earlierGrammarReadings(entries, field, grammar);
     const noRule = read.filter((r) => r.reader === "no_rule").map((r) => r.entry);
     const namedNoTool = read.filter((r) => r.reader === "named_no_tool").map((r) => r.entry);
-    const sentences = [...(namedNoTool.length > 0 ? [namedNoToolInGrammar0(namedNoTool)] : []), ...(noRule.length > 0 ? [noRuleInThisGrammar(noRule, field, grammar)] : [])];
+    const revised = read.flatMap((r) => (r.revised === undefined ? [] : [{ entry: r.entry, ...r.revised }]));
+    const sentences = [
+        ...(namedNoTool.length > 0 ? [namedNoToolInGrammar0(namedNoTool)] : []),
+        ...(noRule.length > 0 ? [noRuleInThisGrammar(noRule, field, grammar)] : []),
+        ...(revised.length > 0 ? [revisedSinceGrammar(revised, field, grammar)] : []),
+    ];
     return `session permission rules of session ${JSON.stringify(sessionId)}: ${sentences.join(" ")}`;
 }
-function earlierGrammarReadings(entries, field) {
-    return entries.map((entry) => ({ entry, reader: readsAsNoRule(entry, field) ? "no_rule" : "named_no_tool" }));
+function earlierGrammarReadings(entries, field, grammar) {
+    const direction = entryBucketDirection(field);
+    return entries.map((entry) => {
+        const read = earlierGrammarReads(grammar, direction, entry, readRuleEntry(entry, direction), entries);
+        return { entry, reader: read.reader ?? "no_rule", ...(read.revised !== undefined ? { revised: read.revised } : {}) };
+    });
+}
+function revisedSinceGrammar(entries, field, grammar) {
+    const one = entries.length === 1;
+    const said = entries
+        .slice(0, ADVISORY_ENTRIES_SHOWN)
+        .map((e) => `${renderListEntry(e.entry)} meant ${e.was} there; this engine's rule grammar (${SESSION_RULES_GRAMMAR}) reads it as ${e.now}, and ${e.stands ? "the stored meaning stands" : "this grammar's reading applies"}`)
+        .join("; ");
+    const rest = entries.length > ADVISORY_ENTRIES_SHOWN ? `; and ${entries.length - ADVISORY_ENTRIES_SHOWN} more` : "";
+    return (`${field} ${one ? "holds an entry" : "holds entries"} stored in rule grammar ${grammar}${grammar === 0 ? " (before the rule grammar stamp)" : ""} whose meaning a later grammar revised — ${said}${rest}. ` +
+        `To give ${one ? "it" : "them"} this grammar's reading, write the session's rules afresh ${REWRITE_THROUGH}; left as stored, ${one ? "it reads" : "they read"} as said.`);
 }
 export function earlierGrammarNotice(input) {
     const { rulesSessionId, sessionId, entries, field, grammar } = input;
@@ -210,7 +331,7 @@ export function earlierGrammarNotice(input) {
         detail: {
             bucket: field,
             storedGrammar: grammar,
-            entries: earlierGrammarReadings(entries, field).map((r) => ({ entry: noticeRuleText(r.entry), reader: r.reader })),
+            entries: earlierGrammarReadings(entries, field, grammar).map((r) => ({ entry: noticeRuleText(r.entry), reader: r.reader })),
             rewrite: { by: "operator_write_without_rev", stampsGrammar: SESSION_RULES_GRAMMAR },
             rulesSessionId,
             sessionId,
@@ -245,8 +366,9 @@ function noRuleInThisGrammar(entries, field, grammar) {
 export function earlierGrammarRefusalClause(entries, grammar) {
     if (entries.length === 0)
         return "";
-    const noRule = entries.filter((e) => readsAsNoRule(e, "toolAllow")).length;
-    const namedNoTool = entries.filter((e) => !readsAsNoRule(e, "toolAllow"));
+    const read = earlierGrammarReadings(entries, "toolAllow", grammar);
+    const noRule = read.filter((r) => r.reader === "no_rule").length;
+    const namedNoTool = read.filter((r) => r.reader !== "no_rule").map((r) => r.entry);
     const stars = namedNoTool.filter(readsAsWildcard).length;
     const others = namedNoTool.length - stars;
     const named = [...(stars > 0 ? ['"*"'] : []), ...(others > 0 ? [`${others} parenthesized ${others === 1 ? "entry" : "entries"}`] : [])];
@@ -276,15 +398,13 @@ function effectiveEntries(rules, field, mountedToolNames) {
 function assertEntriesRead(rules, mountedToolNames) {
     const known = rootFacingToolNames(mountedToolNames);
     for (const field of ENTRY_FIELDS) {
-        for (const entry of rules[field] ?? []) {
-            const reading = readRuleEntry(entry, SESSION_RULE_BUCKETS[field], known);
-            const read = earlierGrammarReads(rules.grammar, field, entry, reading) ? { kind: "inert", reason: "earlier_grammar" } : reading;
+        for (const { entry, reading: read, reader } of bucketReadings(rules, field, known)) {
             if (read.kind === "row")
                 continue;
             const { kind: _kind, ...why } = read;
             void _kind;
             const way = why.reason === "earlier_grammar"
-                ? readsAsNoRule(entry, field)
+                ? reader === "no_rule"
                     ? ` These rules are written in grammar ${rules.grammar} (a stored row), and this engine's grammar (${SESSION_RULES_GRAMMAR}) reads this entry as no rule (grammar) — ` +
                         (field === "toolAllow" && readsAsWildcard(entry) ? `leave the entry out: it spells "*", and ${STAR_IS_NO_ALLOW_RULE}.` : "leave the entry out, or spell the tool's name as a rule spells one.")
                     : ` These rules are written in grammar ${rules.grammar} (a stored row from before the grammar stamp), in which this entry names no tool.` +

package/dist/core/session-store.d.ts

@@ -1,5 +1,5 @@
 import { type Session, type SessionHead, type SessionPlacementRecord, type SessionRepo } from "../internal/harness.js";
-import { type AcquiredSession, type PlacedSessionRow, type SessionPlacement, type SessionStore, type SessionStoreSummary } from "./session.js";
+import { type AcquiredSession, type PlacedSessionRow, type SessionListQuery, type SessionPlacement, type SessionStore, type SessionStoreSummary } from "./session.js";
 import type { StoreDurability } from "./checkpoint-store.js";
 import { SESSION_DEFAULT_TTL_DAYS } from "../config/defaults.js";
 export { SESSION_DEFAULT_TTL_DAYS };
@@ -149,9 +149,16 @@ export declare class TtlSessionStore implements SessionStore {
         requireExisting?: boolean;
         placement?: SessionPlacement;
     }): Promise<AcquiredSession>;
-    /** Whether a cached view is still the occupant the row holds: the row's head, read in one read, names the same occupant as the cached
-     *  session (`compareOccupants` — unknown is never the same). Over a repo with no head read there is nothing to read the row with, and
-     *  the view is served as it is. */
+    /** The one judgement of "does this cached view still stand for this row": `shown` is the view's session metadata and `row` the row as
+     *  a read of it answered (a listed row, or the repo's head; `undefined` = no row, or no read of one). A row naming the view's
+     *  occupant (`compareOccupants`) stands for it; a row naming another does not; and a row naming a different owner does not either —
+     *  the owner is recorded once, by the write that creates the row, so another owner's row is another row whatever it names. When
+     *  the evidence says neither (unknown) the answer is the repo's: over one with a head read the row can always be read again, so a
+     *  view without positive proof is dropped and the id resolved from the row; over one with no head read (it mints no occupant token)
+     *  the cached view is the only evidence of the occupant, and it stands. */
+    private viewStandsFor;
+    /** Whether a cached view is still the occupant the row holds ({@link viewStandsFor}, over the row's head read in one read). Over a repo
+     *  with no head read there is no row to read: the judge's answer for no row there is "stands", given without reading the view. */
     private cachedViewStands;
     /** The placement admission ({@link admitSessionPlacement}) for this store, judged on every resolution path. The
      *  partition declaration is a getter over this store's live field, so it is read where the admission judges the
@@ -161,16 +168,28 @@ export declare class TtlSessionStore implements SessionStore {
      *  `requireExisting`, in which case a genuinely-missing id fails loud instead — design/114 Phase3). */
     private openOrCreate;
     private createAndStore;
-    /** Refresh the idle timer for a session. */
-    touch(sessionId: string): void;
+    /** Refresh the idle timer for a session, and record the activity on its row through the repo ({@link SessionRepo.touch}, where the repo
+     *  has it) — the time {@link list} orders by. A fault recording it rejects. */
+    touch(sessionId: string): Promise<void>;
     /** Record the most recent task run on a cached session (the `/resume` `lastRunId`); also bumps the idle
      *  timer. Best-effort — a no-op if the session isn't cached here (the run will still be re-attachable via
      *  its checkpoint). */
     noteTaskRun(sessionId: string, taskId: string, runId?: string): void;
-    /** List the live cache as {@link SessionStoreSummary} projections, newest-first by `lastActiveAt` (so a
-     *  shell's `/resume` shows recent sessions + their last run first). The in-memory store lists only its
-     *  live cache, not evicted/durable history — a durable backend overrides this to list persisted sessions. */
-    list(): Promise<SessionStoreSummary[]>;
+    /**
+     * One page of the repo's sessions ({@link SessionStore.list}): the rows the repo lists — what a restart still finds, not this
+     * cache — each projected from the row and ordered by the activity the repo RECORDS for it (its writes, and the touches this store
+     * records through it): never by what this process saw, so a dropped cache, a restart or another replica pages the same order, and a
+     * cursor is never overtaken by a row whose time moved back. The cached view adds only what it alone holds — the run it recorded
+     * (`lastTaskId` / `lastTaskRunId`; after a restart, or once the view is evicted, a row lists without them) — and only while the view
+     * stands for the listed row ({@link viewStandsFor}, the judgement `acquire` serves the cached session by). Every row is read to order the page; the repo's listing cost is its own (the File repo: one header
+     * read per session).
+     */
+    list(query?: SessionListQuery): Promise<SessionStoreSummary[]>;
+    /** A listed row's projection: the row's own cells, and the cached view's run while the view stands for the row
+     *  ({@link viewStandsFor} — the row is read here, so a view of an occupant it names otherwise lends nothing). A row's activity is the
+     *  repo's recorded time for it, else its creation — the view's own time is never read, so a repo that records none lists by creation;
+     *  one whose times are both unreadable lists at 0 — at the end, never left out. */
+    private summaryOf;
     /**
      * design/110 (F3) — FORK a session: copy `sourceId`'s committed history into a NEW session and return its id
      * (or `null` when the source doesn't exist). Delegates to the backing repo's `fork`, so a durable repo persists the

package/dist/core/session-store.js

@@ -1,5 +1,5 @@
-import { InMemorySessionRepo, ParentChainGuard, SessionError, findUnansweredToolBatch, compareOccupants, uuidv7, } from "../internal/harness.js";
-import { isSessionConflict } from "./session.js";
+import { InMemorySessionRepo, ParentChainGuard, SessionError, findUnansweredToolBatch, compareOccupants, ownerCell, uuidv7, } from "../internal/harness.js";
+import { isSessionConflict, readSessionListQuery } from "./session.js";
 import { readMember } from "./thrown-value.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
 import { SESSION_DEFAULT_TTL_DAYS } from "../config/defaults.js";
@@ -97,11 +97,19 @@ export class TtlSessionStore {
         const meta = await session.getMetadata();
         return { session, sessionId: meta.id };
     }
+    viewStandsFor(shown, row) {
+        const verdict = compareOccupants(shown, row);
+        if (verdict !== "unknown")
+            return verdict === "same";
+        if (row !== undefined && (shown.owner ?? null) !== (row.owner ?? null))
+            return false;
+        return this.repoHead === undefined;
+    }
     async cachedViewStands(sessionId, cached) {
         if (this.repoHead === undefined)
             return true;
         const [shown, row] = await Promise.all([cached.session.getMetadata(), this.repoHead(sessionId)]);
-        return compareOccupants(shown, row) === "same";
+        return this.viewStandsFor(shown, row);
     }
     assertPlacementAdmission(sessionId, placement, opts) {
         const store = this;
@@ -142,11 +150,12 @@ export class TtlSessionStore {
         this.entries.set(meta.id, { session, lastActiveAt: Date.now(), createdAt: meta.createdAt, ...(meta.forkedFrom !== undefined ? { forkedFrom: meta.forkedFrom } : {}), ...(meta.placement !== undefined ? { placement: meta.placement } : {}) });
         return session;
     }
-    touch(sessionId) {
+    async touch(sessionId) {
         const e = this.entries.get(sessionId);
         if (e) {
             e.lastActiveAt = Date.now();
         }
+        await this.repo.touch?.(sessionId);
     }
     noteTaskRun(sessionId, taskId, runId) {
         const e = this.entries.get(sessionId);
@@ -159,18 +168,36 @@ export class TtlSessionStore {
             e.lastActiveAt = Date.now();
         }
     }
-    async list() {
-        return [...this.entries.entries()]
-            .filter(([, e]) => e.placement === undefined)
-            .map(([sessionId, e]) => ({
-            sessionId,
-            lastActiveAt: e.lastActiveAt,
-            ...(e.createdAt !== undefined && e.createdAt !== "" ? { createdAt: e.createdAt } : {}),
-            ...(e.lastTaskId !== undefined ? { lastTaskId: e.lastTaskId } : {}),
-            ...(e.lastTaskRunId !== undefined ? { lastTaskRunId: e.lastTaskRunId } : {}),
-            ...(e.forkedFrom !== undefined ? { forkedFrom: e.forkedFrom } : {}),
-        }))
-            .sort((a, b) => b.lastActiveAt - a.lastActiveAt);
+    async list(query) {
+        const q = readSessionListQuery(query);
+        const page = [];
+        for (const row of await this.repo.list()) {
+            if (row.placement !== undefined)
+                continue;
+            const owner = row.owner ?? null;
+            if (q.owner !== undefined && owner !== q.owner && !(q.includeUnowned && owner === null))
+                continue;
+            const summary = await this.summaryOf(row);
+            if (q.after !== undefined && newestFirst(q.after, summary) >= 0)
+                continue;
+            page.push(summary);
+        }
+        return page.sort(newestFirst).slice(0, q.limit);
+    }
+    async summaryOf(row) {
+        const cached = this.entries.get(row.id);
+        const view = cached !== undefined && this.viewStandsFor(await cached.session.getMetadata(), row) ? cached : undefined;
+        const recorded = row.lastActiveAt !== undefined && Number.isFinite(row.lastActiveAt) ? row.lastActiveAt : Date.parse(row.createdAt);
+        const lastActiveAt = Number.isFinite(recorded) ? recorded : 0;
+        const forkedFrom = row.forkedFrom ?? view?.forkedFrom;
+        return {
+            sessionId: row.id,
+            lastActiveAt,
+            ...(row.createdAt !== "" ? { createdAt: row.createdAt } : {}),
+            ...(view?.lastTaskId !== undefined ? { lastTaskId: view.lastTaskId } : {}),
+            ...(view?.lastTaskRunId !== undefined ? { lastTaskRunId: view.lastTaskRunId } : {}),
+            ...(forkedFrom !== undefined ? { forkedFrom } : {}),
+        };
     }
     async fork(sourceId, owner) {
         let source;
@@ -274,9 +301,9 @@ export class TtlSessionStore {
             await inflightRelease;
         if (await this.hasRow(sessionId))
             return;
-        if (owner !== null && typeof owner !== "string") {
-            throw new TypeError(`SessionStore.register: owner must be a string (owned) or null (anonymous), got ${owner === undefined ? "undefined" : typeof owner}`);
-        }
+        if (owner === undefined)
+            throw new TypeError("SessionStore.register: owner must be a principal name or null (anonymous), got undefined");
+        ownerCell(owner);
         try {
             await this.repo.create({ id: sessionId, owner });
         }
@@ -347,6 +374,11 @@ export async function settledForkOptions(source) {
     }
     return {};
 }
+function newestFirst(a, b) {
+    if (a.lastActiveAt !== b.lastActiveAt)
+        return b.lastActiveAt - a.lastActiveAt;
+    return a.sessionId < b.sessionId ? 1 : a.sessionId > b.sessionId ? -1 : 0;
+}
 function isNotFound(err) {
     return readMember(err, "code") === "not_found";
 }

package/dist/core/session.d.ts

@@ -2,7 +2,7 @@ export { StoredSession } from "../internal/harness.js";
 export type { Session } from "../internal/harness.js";
 export { InMemorySessionRepo, InMemorySessionStorage, uuidv7, validateEntriesForImport, StreamingImportValidator, } from "../internal/harness.js";
 export { BaseSessionStorage, leafIdAfterEntry, } from "../internal/harness.js";
-export type { SessionStorage, SessionRepo, SessionMetadata, SessionTreeEntry, } from "../internal/harness.js";
+export type { SessionStorage, SessionRepo, SessionRow, SessionMetadata, SessionTreeEntry, } from "../internal/harness.js";
 export { SessionError } from "../internal/harness.js";
 export type { SessionWriteOptions } from "../internal/harness.js";
 import type { Session } from "../internal/harness.js";
@@ -55,7 +55,7 @@ export interface AcquiredSession {
 }
 /**
  * A lightweight, read-only projection of one session for a `/resume` list (shell K-5 — re-attach without an
- * N+1 walk). Returned in bulk by {@link SessionStore.list}, newest-first by `lastActiveAt` by convention.
+ * N+1 walk). Returned in pages by {@link SessionStore.list}, newest-first by `(lastActiveAt, sessionId)`.
  * `lastTaskId` is the engine's term for what the service/wire surfaces as the session's **`lastRunId`** — the
  * most recent task run on this session, so a shell re-attaches in ONE hop.
  *
@@ -72,7 +72,10 @@ export interface SessionStoreSummary {
     /** When the session was created ({@link SessionMetadata.createdAt}, ISO string); absent when the backend's
      *  cache view doesn't carry it. */
     createdAt?: string;
-    /** Epoch ms the session was last acquired / touched / ran — the newest-first sort key for "recent sessions". */
+    /** Epoch ms of the session's newest activity the store RECORDS — its writes and its {@link SessionStore.touch}es (the Runner touches
+     *  a session as each run ends) — the newest-first sort key for "recent sessions". Recorded, never what one process saw: a restart,
+     *  another replica or a dropped cache reads the same time, and only a later activity moves it. An acquire that writes nothing is not
+     *  activity. */
     lastActiveAt: number;
     /** The most recent task run on this session (core's `taskId`; the service projects it as `lastRunId`).
      *  Absent until a task has run on the session (recorded via {@link SessionStore.noteTaskRun}). */
@@ -106,6 +109,54 @@ export interface SessionStoreSummary {
      *  predate the fork. The durable source of truth is the repo's persisted metadata. */
     forkedFrom?: string;
 }
+/** The page bounds of {@link SessionStore.list}: a query without `limit` reads `default` rows; an explicit `limit` is an integer in
+ *  1..`max`. */
+export declare const SESSION_LIST_LIMITS: Readonly<{
+    readonly default: 50;
+    readonly max: 1000;
+}>;
+/**
+ * What {@link SessionStore.list} is asked for. No query, or `{}`, is the unfiltered list — every owner's rows, unowned ones included —
+ * read from its first page, at most {@link SESSION_LIST_LIMITS}`.default` rows; a caller that wants every row pages with `after`.
+ * A store may define extension filters of its own (members beside these, e.g. a text search); a filter applies before the page is
+ * cut, so `after` and `limit` page the filtered list. A store refuses a member it does not read — an unread filter would list rows the
+ * caller asked to exclude.
+ */
+export interface SessionListQuery {
+    /** Only the rows this owner owns (exact match; a principal name, so a blank string is refused, never an owner of its own). Absent = no owner filter. */
+    owner?: string;
+    /** With `owner`: the unowned rows (owner `null`) too. A member of the owner filter only — given without `owner` it is refused, so a
+     *  query that lost its owner never widens into every owner's list. */
+    includeUnowned?: boolean;
+    /** The keyset cursor — the `lastActiveAt` and `sessionId` of the last row of the previous page: only rows after it in the list's
+     *  order are read (a smaller `lastActiveAt`, or the same one with a smaller `sessionId`). */
+    after?: {
+        lastActiveAt: number;
+        sessionId: string;
+    };
+    /** At most this many rows, an integer in 1..{@link SESSION_LIST_LIMITS}`.max`; absent = the default. Ask for one more than a page
+     *  shows to learn whether another page exists. */
+    limit?: number;
+}
+/** {@link readSessionListQuery}'s answer: the query's members as read, the defaults filled in. */
+export interface SessionListQueryReading {
+    readonly owner?: string;
+    readonly includeUnowned: boolean;
+    readonly after?: {
+        readonly lastActiveAt: number;
+        readonly sessionId: string;
+    };
+    readonly limit: number;
+    /** The values of the extension members the reading store declared and the query carries. */
+    readonly extensions: Readonly<Record<string, unknown>>;
+}
+/**
+ * The one reading of a {@link SessionListQuery}, for every store that implements {@link SessionStore.list}: `raw` read by the
+ * engine's receipt law (a plain object, each member read once), each member judged, the default limit filled in. `extensions` names
+ * the extension members the calling store reads (none for a store without extension filters); any other member is refused. A bad
+ * value is refused, never mapped to a default: `config.invalid_argument`.
+ */
+export declare function readSessionListQuery(raw: unknown, extensions?: readonly string[]): SessionListQueryReading;
 /**
  * The session lifecycle/caching layer the {@link Runner} depends on.
  *
@@ -114,8 +165,12 @@ export interface SessionStoreSummary {
  * a session from the persisted event log so any stateless runner instance can resume it.
  *
  * Implementations must be safe under concurrent `acquire` of the same id (return one session).
+ *
+ * `S` / `Q` are the store's list projection and query: a backend whose list carries more per row (or filters by more) extends
+ * {@link SessionStoreSummary} / {@link SessionListQuery} and implements `SessionStore<Its summary, Its query>` — still assignable
+ * wherever a `SessionStore` is taken.
  */
-export interface SessionStore {
+export interface SessionStore<S extends SessionStoreSummary = SessionStoreSummary, Q extends SessionListQuery = SessionListQuery> {
     /**
      * design/173 §2.3 — durability declaration (see
      * {@link import("./checkpoint-store.js").StoreDurability}): whether sessions this store accepts
@@ -142,7 +197,7 @@ export interface SessionStore {
      * Declaring this commits the store to the placement obligations:
      *  1. a placed session enjoys the declared durability (`acquire(id, {requireExisting:true})`
      *     reaches it after a restart when `"durable"`);
-     *  2. placed sessions do NOT appear on host enumeration faces (`list()` and every deployment
+     *  2. placed sessions do NOT appear on host enumeration faces (`list` and every deployment
      *     listing path — restart-stable);
      *  3. acquire semantics for sessions WITHOUT a placement are byte-unchanged;
      *  4. `release(placedId)` is a REAL deletion (durable history included) — the joint reap's
@@ -171,7 +226,8 @@ export interface SessionStore {
         requireExisting?: boolean;
         placement?: SessionPlacement;
     }): Promise<AcquiredSession>;
-    /** Mark a session recently active (resets idle TTL where applicable). May be async for durable stores. */
+    /** Mark a session recently active: resets the idle TTL where applicable, and is activity the {@link list} order records. May be
+     *  async for durable stores. */
     touch(sessionId: string): void | Promise<void>;
     /** Drop a session from the live set (e.g. a throwaway task). Durable history may be retained by the backend. */
     release(sessionId: string): Promise<void>;
@@ -215,12 +271,16 @@ export interface SessionStore {
      */
     noteTaskRun?(sessionId: string, taskId: string, runId?: string): void | Promise<void>;
     /**
-     * Enumerate known sessions as lightweight {@link SessionStoreSummary} projections (newest-first by
-     * `lastActiveAt`) so a shell's `/resume` lists sessions + their last run in ONE call. **Optional**: the
-     * in-memory `TtlSessionStore` lists its live cache; a durable backend lists persisted sessions. A store
-     * that cannot enumerate omits this (the shell then has no session-list affordance — honest degrade).
+     * One page of the store's sessions as lightweight {@link SessionStoreSummary} projections, so a shell's `/resume` lists sessions +
+     * their last run in ONE call: every session ROW the store holds — what a restart still finds, not only what this process has
+     * cached — that the query admits, newest-first by `(lastActiveAt, sessionId)` (both descending; equal times order by id), at most
+     * `limit` rows after the `after` cursor (see {@link SessionListQuery}; read it with {@link readSessionListQuery}, whose refusals are
+     * this face's). Placed sessions are never listed (placement obligation 2). Reading the list is not activity, and a row's time only
+     * moves forward, so paging with `after` never reads a row twice — a row written or touched between two pages moves ahead of the
+     * cursor, where later pages do not read it (a fresh first page shows it). **Optional**: a store that cannot enumerate omits this (the
+     * shell then has no session-list affordance — honest degrade).
      */
-    list?(): Promise<SessionStoreSummary[]>;
+    list?(query?: Q): Promise<S[]>;
     /**
      * Subagent transcript persistence — enumerate the PLACED partition (the input to the joint reap's
      * partition leg: sessions whose owning agent row is gone are the orphan shape it collects).
@@ -247,7 +307,8 @@ export interface SessionStore {
      * fork time (returns `null`). The fork is a new row whose owner cell is recorded in the write that creates it — a fork
      * COPIES the source's history, so the copy is never weaker than the original: with no `owner` argument, or an
      * EXPLICIT `null`, the fork records the SOURCE row's owner ("anonymous" on a copy of an OWNED source would admit
-     * every principal to that history — a downgrade this face exists to prevent); an owner string records that owner.
+     * every principal to that history — a downgrade this face exists to prevent); an owner string (a principal name — a blank
+     * string is refused, with no row left behind) records that owner.
      * MUST copy the COMMITTED leaf (an in-flight uncommitted turn of an active source is not included — a fork is a
      * snapshot at the fork point).
      */
@@ -260,7 +321,10 @@ export interface SessionStore {
      * The BY-ID read, for a reader that did not acquire the session (hosts, a deployment's authorizer). A store that has it hands out,
      * from `acquire`, only a session of the occupant it names — a cached view of an occupant the row no longer holds (the row deleted,
      * or deleted and created again, through another writer — on the File lane a writer in another process too) is not served — so its `incarnation` and the acquired session's metadata agree (the kit pins both); a run's own memory seat reads the session it ACQUIRED instead, never this lookup. The owner is a cell of the row: `null` = anonymous (admitted to every principal) — a row created
-     * with no owner, a placed row, or a row written before the cell existed; a string = owned. **Optional**: absent ⇒ no by-id read,
+     * with no owner (`acquire` names none), or a row written before the cell existed; a principal name = owned (a cell holding a blank string
+     * names nobody and is a read fault, never an owner). A placed row carries the owner its placing write recorded: the bundled stores'
+     * placing write names none (`acquire`'s options and {@link SessionPlacement} carry no principal), so their placed rows read `null`; a
+     * store's own placing write may record a principal (e.g. a delegation tree's owner), and a reader takes the row's owner as it reads. **Optional**: absent ⇒ no by-id read,
      * and a deployment's authorizer, which needs this and {@link register} together, takes its fail-closed arm.
      */
     headOf?(sessionId: string): Promise<SessionHead | undefined>;
@@ -268,9 +332,11 @@ export interface SessionStore {
      * The owner write of the ownership pair ({@link headOf} + this). On an id with NO row it creates the row — an ordinary row, no
      * placement — recording `owner` in the creating write, first-write-wins and atomic: of two concurrent first registers, both
      * callers' re-reads see the same winner (durable implementations need a real uniqueness guarantee, not read-then-write). On an id
-     * whose row EXISTS it does nothing, whatever it carries — an owned row, an anonymous row, or a row `acquire` created (which
-     * records `null`) stays as it is; there is no claiming of an existing row. A FIRST write whose `owner` is neither a string nor
-     * `null` is refused loudly and leaves no row; a later call stays a silent no-op whatever it carries. Deliberately makes NO
+     * whose row EXISTS it does nothing, whatever it carries — an owned row, an anonymous row, a row `acquire` created (which
+     * records `null`), or a placed row (the owner its placing write recorded) stays as it is: a row's owner is recorded by the write that
+     * creates it and `register` never changes it; there is no claiming of an existing row. A FIRST write whose `owner` is neither a principal
+     * name (a string with a visible character, no control or separator character, and no format character but a joiner) nor `null` is refused loudly and leaves no row; a later call stays a silent no-op
+     * whatever it carries. Deliberately makes NO
      * authorization decision — the caller re-reads {@link headOf} and judges there. The owner lives and dies with its row.
      */
     register?(sessionId: string, owner: string | null): Promise<void>;