@timurproko/a1 0.2.7-dev.754 → 0.2.7-dev.767

package/dist/foundation/resident-tabs/prompt-journal.js

@@ -0,0 +1,214 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, open, readFile, rename, stat, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+const MAX_JOURNAL_BYTES = 8 * 1024 * 1024;
+const MAX_RECORD_BYTES = 2 * 1024 * 1024;
+export class PromptJournal {
+    path;
+    #faults;
+    #maximumBytes;
+    #operation = Promise.resolve();
+    #retired = new Set();
+    constructor(path, options = {}) {
+        this.path = path;
+        this.#faults = options.faults ?? new ResidentTabFaultInjection();
+        this.#maximumBytes = options.maximumBytes ?? MAX_JOURNAL_BYTES;
+    }
+    async initialize() {
+        await secureDirectory(dirname(this.path));
+        const handle = await open(this.path, "a", 0o600);
+        await handle.close();
+        if (process.platform !== "win32")
+            await chmod(this.path, 0o600);
+        for (const record of await this.read())
+            if (record.type === "retired")
+                this.#retired.add(record.id);
+    }
+    async submit(submission) {
+        const record = {
+            type: "submitted",
+            id: randomUUID(),
+            ...submission,
+            ...(submission.images === undefined ? {} : { images: submission.images }),
+            at: new Date().toISOString(),
+        };
+        await this.#append(record, "journal-before-append", "journal-after-append", "journal-after-sync");
+        return record;
+    }
+    async adopt(record) {
+        if ((await this.read()).some(existing => existing.type === "submitted" && existing.id === record.id))
+            return false;
+        await this.#append(record, "journal-before-append", "journal-after-append", "journal-after-sync");
+        return true;
+    }
+    async correlate(id, entryId) {
+        await this.#append({ type: "correlated", id, entryId }, "journal-before-correlation", "journal-after-correlation");
+    }
+    async settle(id, entryId) {
+        await this.#append({ type: "settled", id, entryId }, "journal-before-settled-record", "journal-after-settled-record");
+    }
+    async retire(id) {
+        if (this.#retired.has(id))
+            return;
+        await this.#append({ type: "retired", id }, "journal-during-retirement");
+        this.#retired.add(id);
+    }
+    async read() {
+        let text;
+        try {
+            text = await readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        const records = [];
+        const lines = text.split("\n");
+        for (let index = 0; index < lines.length; index += 1) {
+            const line = lines[index];
+            if (!line)
+                continue;
+            try {
+                const value = JSON.parse(line);
+                records.push(decodeRecord(value));
+            }
+            catch (error) {
+                if (index === lines.length - 1 && !text.endsWith("\n"))
+                    break;
+                throw error;
+            }
+        }
+        return records;
+    }
+    async pending(sessionEntries = []) {
+        const states = new Map();
+        const settled = new Set();
+        const retired = new Set();
+        for (const record of await this.read()) {
+            if (record.type === "submitted")
+                states.set(record.id, { submitted: record });
+            else if (record.type === "correlated") {
+                const state = states.get(record.id);
+                if (state !== undefined)
+                    states.set(record.id, { ...state, correlatedEntryId: record.entryId });
+            }
+            else if (record.type === "settled")
+                settled.add(record.id);
+            else
+                retired.add(record.id);
+        }
+        const byId = new Map(sessionEntries.map(entry => [entry.entryId, entry]));
+        const pending = [];
+        const claimedEntries = new Set();
+        for (const [id, state] of states) {
+            if (retired.has(id) || settled.has(id)) {
+                await this.retire(id);
+                continue;
+            }
+            const correlated = state.correlatedEntryId === undefined ? undefined : byId.get(state.correlatedEntryId);
+            const textMatch = correlated ?? sessionEntries.find(entry => entry.text === state.submitted.text && !claimedEntries.has(entry.entryId));
+            if (textMatch !== undefined)
+                claimedEntries.add(textMatch.entryId);
+            if (textMatch?.settled === true)
+                await this.retire(id);
+            else
+                pending.push(state);
+        }
+        return pending;
+    }
+    async compactIfRetired() {
+        if ((await this.pending()).length !== 0)
+            return false;
+        await this.#serialize(async () => {
+            this.#faults.at("journal-during-compaction");
+            const temporary = `${this.path}.tmp-${process.pid}-${randomUUID()}`;
+            const handle = await open(temporary, "wx", 0o600);
+            try {
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await rename(temporary, this.path);
+            await syncDirectory(dirname(this.path));
+        });
+        return true;
+    }
+    async #append(record, ...points) {
+        const line = `${JSON.stringify(record)}\n`;
+        const bytes = Buffer.byteLength(line);
+        if (bytes > MAX_RECORD_BYTES)
+            throw new Error("resident prompt journal record exceeds its size limit");
+        await this.#serialize(async () => {
+            for (const point of points.slice(0, 1))
+                this.#faults.at(point);
+            const current = await stat(this.path).then(value => value.size, error => error.code === "ENOENT" ? 0 : Promise.reject(error));
+            if (current + bytes > this.#maximumBytes)
+                throw new Error("resident prompt journal is full");
+            const handle = await open(this.path, "a", 0o600);
+            try {
+                await handle.write(line, undefined, "utf8");
+                if (points[1] !== undefined)
+                    this.#faults.at(points[1]);
+                await handle.sync();
+                if (points[2] !== undefined)
+                    this.#faults.at(points[2]);
+            }
+            finally {
+                await handle.close();
+            }
+        });
+    }
+    async #serialize(operation) {
+        const next = this.#operation.then(operation, operation);
+        this.#operation = next.catch(() => undefined);
+        await next;
+    }
+}
+export function classifyMissingSession(record, sessionExists) {
+    if (sessionExists)
+        return "available";
+    return record.fileExisted ? "missing-transcript" : "first-turn";
+}
+function decodeRecord(value) {
+    if (typeof value !== "object" || value === null)
+        throw new Error("invalid resident prompt journal record");
+    const record = value;
+    if (typeof record.id !== "string" || record.id.length === 0)
+        throw new Error("invalid resident prompt journal id");
+    if (record.type === "submitted") {
+        if (typeof record.sessionId !== "string" || !(typeof record.sessionFile === "string" || record.sessionFile === null)
+            || typeof record.incarnation !== "number" || typeof record.fileExisted !== "boolean"
+            || !["prompt", "steer", "follow-up"].includes(String(record.kind)) || typeof record.text !== "string" || typeof record.at !== "string") {
+            throw new Error("invalid submitted prompt journal record");
+        }
+        return record;
+    }
+    if ((record.type === "correlated" || record.type === "settled") && typeof record.entryId === "string")
+        return record;
+    if (record.type === "retired")
+        return record;
+    throw new Error("invalid resident prompt journal record type");
+}
+async function secureDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32")
+        await chmod(path, 0o700);
+}
+async function syncDirectory(path) {
+    if (process.platform === "win32")
+        return;
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function removeJournalTemporary(path) {
+    await unlink(path).catch(error => { if (error.code !== "ENOENT")
+        throw error; });
+}

package/dist/foundation/resident-tabs/protocol.d.ts

@@ -0,0 +1,12 @@
+export interface ResidentEnvelope<T = Readonly<Record<string, unknown>>> {
+    readonly type: string;
+    readonly requestId?: number;
+    readonly body: T;
+}
+/** Generation-1 MessagePack named-map codec. It intentionally supports only bridge-safe values. */
+export declare function encodeResidentFrame(value: ResidentEnvelope): Buffer;
+export declare function decodeResidentPayload(payload: Uint8Array): ResidentEnvelope;
+export declare class ResidentFrameDecoder {
+    #private;
+    push(chunk: Uint8Array): readonly ResidentEnvelope[];
+}

package/dist/foundation/resident-tabs/protocol.js

@@ -0,0 +1,195 @@
+const MAX_FRAME_BYTES = 2 * 1024 * 1024;
+const MAX_DEPTH = 64;
+/** Generation-1 MessagePack named-map codec. It intentionally supports only bridge-safe values. */
+export function encodeResidentFrame(value) {
+    const payload = Buffer.from(encodeValue(value, 0));
+    if (payload.length > MAX_FRAME_BYTES)
+        throw new Error("resident frame exceeds 2 MiB");
+    const frame = Buffer.allocUnsafe(payload.length + 4);
+    frame.writeUInt32LE(payload.length, 0);
+    payload.copy(frame, 4);
+    return frame;
+}
+export function decodeResidentPayload(payload) {
+    if (payload.byteLength > MAX_FRAME_BYTES)
+        throw new Error("resident frame exceeds 2 MiB");
+    const state = { bytes: payload, offset: 0 };
+    const value = decodeValue(state, 0);
+    if (state.offset !== payload.byteLength || !isRecord(value) || typeof value.type !== "string" || !isRecord(value.body)) {
+        throw new Error("invalid resident envelope");
+    }
+    return value;
+}
+export class ResidentFrameDecoder {
+    #buffer = Buffer.alloc(0);
+    push(chunk) {
+        this.#buffer = Buffer.concat([this.#buffer, chunk]);
+        const messages = [];
+        while (this.#buffer.length >= 4) {
+            const length = this.#buffer.readUInt32LE(0);
+            if (length > MAX_FRAME_BYTES)
+                throw new Error("resident frame exceeds 2 MiB");
+            if (this.#buffer.length < length + 4)
+                break;
+            messages.push(decodeResidentPayload(this.#buffer.subarray(4, length + 4)));
+            this.#buffer = this.#buffer.subarray(length + 4);
+        }
+        return messages;
+    }
+}
+function encodeValue(value, depth) {
+    if (depth > MAX_DEPTH)
+        throw new Error("resident value exceeds nesting limit");
+    if (value === null)
+        return [0xc0];
+    if (value === false)
+        return [0xc2];
+    if (value === true)
+        return [0xc3];
+    if (typeof value === "number" && Number.isSafeInteger(value))
+        return encodeInteger(value);
+    if (typeof value === "string") {
+        const bytes = [...Buffer.from(value, "utf8")];
+        if (bytes.length < 32)
+            return [0xa0 | bytes.length, ...bytes];
+        if (bytes.length <= 0xff)
+            return [0xd9, bytes.length, ...bytes];
+        if (bytes.length <= 0xffff)
+            return [0xda, bytes.length >>> 8, bytes.length & 0xff, ...bytes];
+        return [0xdb, ...u32(bytes.length), ...bytes];
+    }
+    if (value instanceof Uint8Array) {
+        const bytes = [...value];
+        if (bytes.length <= 0xff)
+            return [0xc4, bytes.length, ...bytes];
+        if (bytes.length <= 0xffff)
+            return [0xc5, bytes.length >>> 8, bytes.length & 0xff, ...bytes];
+        return [0xc6, ...u32(bytes.length), ...bytes];
+    }
+    if (Array.isArray(value)) {
+        const head = value.length < 16 ? [0x90 | value.length] : value.length <= 0xffff ? [0xdc, value.length >>> 8, value.length & 0xff] : [0xdd, ...u32(value.length)];
+        return [...head, ...value.flatMap(entry => encodeValue(entry, depth + 1))];
+    }
+    if (isRecord(value)) {
+        const entries = Object.entries(value).filter(([, child]) => child !== undefined);
+        const head = entries.length < 16 ? [0x80 | entries.length] : entries.length <= 0xffff ? [0xde, entries.length >>> 8, entries.length & 0xff] : [0xdf, ...u32(entries.length)];
+        return [...head, ...entries.flatMap(([key, child]) => [...encodeValue(key, depth + 1), ...encodeValue(child, depth + 1)])];
+    }
+    throw new Error(`unsupported resident value: ${typeof value}`);
+}
+function encodeInteger(value) {
+    if (value >= 0 && value <= 0x7f)
+        return [value];
+    if (value < 0 && value >= -32)
+        return [0x100 + value];
+    if (value >= 0 && value <= 0xff)
+        return [0xcc, value];
+    if (value >= 0 && value <= 0xffff)
+        return [0xcd, value >>> 8, value & 0xff];
+    if (value >= -0x80 && value < 0)
+        return [0xd0, value & 0xff];
+    if (value >= -0x8000 && value < 0)
+        return [0xd1, (value >>> 8) & 0xff, value & 0xff];
+    if (value >= 0 && value <= 0xffffffff)
+        return [0xce, ...u32(value)];
+    return [0xd3, ...i64(value)];
+}
+function decodeValue(state, depth) {
+    if (depth > MAX_DEPTH)
+        throw new Error("resident value exceeds nesting limit");
+    const marker = byte(state);
+    if (marker <= 0x7f)
+        return marker;
+    if (marker >= 0xe0)
+        return marker - 0x100;
+    if ((marker & 0xe0) === 0xa0)
+        return string(state, marker & 0x1f);
+    if ((marker & 0xf0) === 0x90)
+        return array(state, marker & 0x0f, depth);
+    if ((marker & 0xf0) === 0x80)
+        return map(state, marker & 0x0f, depth);
+    switch (marker) {
+        case 0xc0: return null;
+        case 0xc2: return false;
+        case 0xc3: return true;
+        case 0xc4: return binary(state, uint(state, 1));
+        case 0xc5: return binary(state, uint(state, 2));
+        case 0xc6: return binary(state, uint(state, 4));
+        case 0xcc: return uint(state, 1);
+        case 0xcd: return uint(state, 2);
+        case 0xce: return uint(state, 4);
+        case 0xcf: return safeInteger(state, false);
+        case 0xd0: return signed(state, 1);
+        case 0xd1: return signed(state, 2);
+        case 0xd2: return signed(state, 4);
+        case 0xd3: return safeInteger(state, true);
+        case 0xd9: return string(state, uint(state, 1));
+        case 0xda: return string(state, uint(state, 2));
+        case 0xdb: return string(state, uint(state, 4));
+        case 0xdc: return array(state, uint(state, 2), depth);
+        case 0xdd: return array(state, uint(state, 4), depth);
+        case 0xde: return map(state, uint(state, 2), depth);
+        case 0xdf: return map(state, uint(state, 4), depth);
+        default: throw new Error(`unsupported resident MessagePack marker 0x${marker.toString(16)}`);
+    }
+}
+function byte(state) {
+    const value = state.bytes[state.offset++];
+    if (value === undefined)
+        throw new Error("incomplete resident value");
+    return value;
+}
+function uint(state, width) {
+    let value = 0;
+    for (let index = 0; index < width; index++)
+        value = value * 256 + byte(state);
+    return value;
+}
+function signed(state, width) {
+    const value = uint(state, width);
+    return value >= 2 ** (width * 8 - 1) ? value - 2 ** (width * 8) : value;
+}
+function safeInteger(state, signedValue) {
+    const high = uint(state, 4);
+    const low = uint(state, 4);
+    const value = high * 0x1_0000_0000 + low;
+    const resolved = signedValue && high >= 0x80000000 ? value - 0x1_0000_0000_0000_0000 : value;
+    if (!Number.isSafeInteger(resolved))
+        throw new Error("resident integer exceeds JavaScript safe range");
+    return resolved;
+}
+function string(state, length) {
+    return Buffer.from(binary(state, length)).toString("utf8");
+}
+function binary(state, length) {
+    const end = state.offset + length;
+    if (end > state.bytes.byteLength)
+        throw new Error("incomplete resident value");
+    const value = state.bytes.slice(state.offset, end);
+    state.offset = end;
+    return value;
+}
+function array(state, length, depth) {
+    if (length > 65_536)
+        throw new Error("resident collection exceeds limit");
+    return Array.from({ length }, () => decodeValue(state, depth + 1));
+}
+function map(state, length, depth) {
+    if (length > 65_536)
+        throw new Error("resident collection exceeds limit");
+    const value = {};
+    for (let index = 0; index < length; index++) {
+        const key = decodeValue(state, depth + 1);
+        if (typeof key !== "string" || Object.hasOwn(value, key))
+            throw new Error("invalid resident map key");
+        value[key] = decodeValue(state, depth + 1);
+    }
+    return value;
+}
+function u32(value) { return [(value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff]; }
+function i64(value) {
+    const integer = BigInt(value);
+    const encoded = integer < 0 ? (1n << 64n) + integer : integer;
+    return Array.from({ length: 8 }, (_, index) => Number((encoded >> BigInt((7 - index) * 8)) & 0xffn));
+}
+function isRecord(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }

package/dist/foundation/resident-tabs/recovery.d.ts

@@ -0,0 +1,26 @@
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+import { type PromptSubmission, type SessionJournalEntry, type SubmittedPromptRecord } from "./prompt-journal.js";
+export interface ResidentTabRecoveredInput {
+    readonly prompts: readonly SubmittedPromptRecord[];
+    readonly draft: string | null;
+}
+export interface ResidentTabAdmission extends Omit<PromptSubmission, "fileExisted" | "incarnation"> {
+    readonly incarnation: number;
+}
+export declare class ResidentTabRecovery {
+    #private;
+    constructor(dataDir: string, options?: {
+        readonly faults?: ResidentTabFaultInjection;
+        readonly onDegraded?: (degraded: boolean) => void;
+    });
+    get recovered(): ResidentTabRecoveredInput;
+    initialize(currentSessionFile?: string | null, currentSessionId?: string | null): Promise<ResidentTabRecoveredInput>;
+    admit(input: ResidentTabAdmission, timeoutMs?: number): Promise<SubmittedPromptRecord>;
+    dispatched(): void;
+    correlated(submissionId: string, entryId: string): Promise<void>;
+    checkpoint(text: string): void;
+    settled(sessionFile: string | null): Promise<void>;
+    gracefulStop(sessionFile: string | null): Promise<void>;
+}
+/** Reconcile only durable user/assistant ancestry; a torn final JSONL record is not authority. */
+export declare function readSessionJournal(path: string): Promise<readonly SessionJournalEntry[]>;

package/dist/foundation/resident-tabs/recovery.js

@@ -0,0 +1,205 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { DraftCheckpointer } from "./draft-checkpoint.js";
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+import { PromptJournal } from "./prompt-journal.js";
+import { SettledTurnSynchronizer, synchronizeSessionFile } from "./session-sync.js";
+export class ResidentTabRecovery {
+    #journal;
+    #draft;
+    #synchronizer;
+    #faults;
+    #onDegraded;
+    #active = [];
+    #recovered = { prompts: [], draft: null };
+    constructor(dataDir, options = {}) {
+        const faults = options.faults ?? new ResidentTabFaultInjection();
+        this.#faults = faults;
+        this.#onDegraded = options.onDegraded ?? (() => { });
+        this.#journal = new PromptJournal(join(dataDir, "journal.jsonl"), { faults });
+        this.#draft = new DraftCheckpointer(join(dataDir, "draft.json"), { faults, onDegraded: this.#onDegraded });
+        this.#synchronizer = new SettledTurnSynchronizer(this.#journal, faults);
+    }
+    get recovered() { return this.#recovered; }
+    async initialize(currentSessionFile = null, currentSessionId = null) {
+        await this.#journal.initialize();
+        await adoptHistoricalJournals(dirname(dirname(this.#journal.path)), this.#journal, currentSessionFile, currentSessionId);
+        const records = await this.#journal.read();
+        const sessionFiles = new Set(records.flatMap(record => record.type === "submitted" && record.sessionFile !== null ? [record.sessionFile] : []));
+        if (currentSessionFile !== null)
+            sessionFiles.add(currentSessionFile);
+        const sessionEntries = (await Promise.all([...sessionFiles].map(readSessionJournal))).flat();
+        const [pending, draft] = await Promise.all([
+            this.#journal.pending(sessionEntries),
+            this.#draft.restore(),
+        ]);
+        this.#recovered = { prompts: pending.map(value => value.submitted), draft: draft?.text ?? null };
+        return this.#recovered;
+    }
+    async admit(input, timeoutMs = 2_000) {
+        const fileExisted = input.sessionFile === null ? false : await stat(input.sessionFile).then(() => true, error => {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        });
+        let timer;
+        try {
+            return await Promise.race([
+                this.#journal.submit({ ...input, fileExisted }),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error("resident prompt journal admission timed out")), timeoutMs);
+                    timer.unref();
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    dispatched() { this.#faults.at("journal-after-dispatch"); }
+    async correlated(submissionId, entryId) {
+        await this.#journal.correlate(submissionId, entryId);
+        this.#active.push({ id: submissionId, entryId });
+    }
+    checkpoint(text) { this.#draft.change(text); }
+    async settled(sessionFile) {
+        const active = this.#active.splice(0);
+        if (active.length === 0 || sessionFile === null)
+            return;
+        await this.#synchronizer.settleMany(sessionFile, active);
+        for (const entry of active)
+            await this.#journal.retire(entry.id);
+        await this.#journal.compactIfRetired();
+    }
+    async gracefulStop(sessionFile) {
+        await this.#draft.flush();
+        if (sessionFile !== null)
+            await synchronizeSessionFile(sessionFile);
+        await this.#synchronizer.flush();
+    }
+}
+const MAX_SESSION_RECONCILE_BYTES = 64 * 1024 * 1024;
+const MAX_ADOPTION_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+async function adoptHistoricalJournals(profileTabsRoot, target, currentSessionFile, currentSessionId) {
+    if (currentSessionFile === null && currentSessionId === null)
+        return;
+    const history = join(profileTabsRoot, "registry-history");
+    const names = await readdir(history).catch(() => []);
+    for (const name of names.filter(value => /^tabset-.+\.json$/.test(value)).sort().reverse()) {
+        const path = join(history, name);
+        const metadata = await stat(path).catch(() => null);
+        if (metadata === null || Date.now() - metadata.mtimeMs > MAX_ADOPTION_AGE_MS)
+            continue;
+        let document;
+        try {
+            document = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const tabs = typeof document === "object" && document !== null && Array.isArray(document.tabs)
+            ? document.tabs : [];
+        for (const value of tabs) {
+            if (typeof value !== "object" || value === null)
+                continue;
+            const tab = value;
+            if (typeof tab.tabId !== "string")
+                continue;
+            const fileMatches = currentSessionFile !== null && typeof tab.sessionFile === "string"
+                && resolve(tab.sessionFile) === resolve(currentSessionFile);
+            const sourcePath = join(profileTabsRoot, tab.tabId, "journal.jsonl");
+            if (resolve(sourcePath) === resolve(target.path))
+                continue;
+            if (!await stat(sourcePath).then(() => true, () => false))
+                continue;
+            const source = new PromptJournal(sourcePath);
+            await source.initialize();
+            const records = await source.read();
+            const submitted = records.filter((record) => record.type === "submitted");
+            const idMatches = currentSessionId !== null && submitted.some(record => record.sessionId === currentSessionId);
+            if (!fileMatches && !idMatches)
+                continue;
+            const pending = await source.pending(currentSessionFile === null ? [] : await readSessionJournal(currentSessionFile));
+            for (const entry of pending) {
+                await target.adopt(entry.submitted);
+                await source.retire(entry.submitted.id);
+            }
+        }
+    }
+}
+/** Reconcile only durable user/assistant ancestry; a torn final JSONL record is not authority. */
+export async function readSessionJournal(path) {
+    let text;
+    try {
+        const metadata = await stat(path);
+        if (metadata.size > MAX_SESSION_RECONCILE_BYTES)
+            throw new Error("resident session exceeds the recovery scan limit");
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const raw = [];
+    const lines = text.split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line.length === 0)
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch (error) {
+            if (index === lines.length - 1 && !text.endsWith("\n"))
+                break;
+            throw error;
+        }
+        if (typeof value !== "object" || value === null)
+            continue;
+        const record = value;
+        const message = typeof record.message === "object" && record.message !== null
+            ? record.message
+            : null;
+        if (record.type !== "message" || typeof record.id !== "string" || message === null
+            || typeof message.role !== "string")
+            continue;
+        const content = message.content;
+        const promptText = typeof content === "string" ? content : Array.isArray(content)
+            ? content.flatMap(part => typeof part === "object" && part !== null
+                && part.type === "text"
+                && typeof part.text === "string"
+                ? [part.text] : []).join("")
+            : "";
+        raw.push({
+            id: record.id,
+            parentId: typeof record.parentId === "string" ? record.parentId : null,
+            role: message.role,
+            text: promptText,
+        });
+    }
+    const byId = new Map(raw.map(record => [record.id, record]));
+    const settled = new Set();
+    for (const record of raw) {
+        if (record.role !== "assistant")
+            continue;
+        let parent = record.parentId;
+        const visited = new Set();
+        while (parent !== null && !visited.has(parent)) {
+            visited.add(parent);
+            const ancestor = byId.get(parent);
+            if (ancestor === undefined)
+                break;
+            if (ancestor.role === "user") {
+                settled.add(ancestor.id);
+                break;
+            }
+            parent = ancestor.parentId;
+        }
+    }
+    return raw
+        .filter(record => record.role === "user")
+        .map(record => ({ entryId: record.id, text: record.text, settled: settled.has(record.id) }));
+}

package/dist/foundation/resident-tabs/routing.d.ts

@@ -0,0 +1,10 @@
+import type { EnsureTerminalHostResult } from "./ensure-terminal-host.js";
+export interface ResidentHostSelectionOptions {
+    readonly profileId: "a1" | "pi";
+    readonly hasSessionSelection: boolean;
+    readonly currentLaunchContract: boolean;
+    readonly readSetting: () => Promise<boolean>;
+    readonly ensureHost: () => Promise<EnsureTerminalHostResult>;
+}
+/** Invariant: every non-bare or default-off launch stays outside resident discovery and startup. */
+export declare function selectResidentHost(options: ResidentHostSelectionOptions): Promise<EnsureTerminalHostResult | null>;

package/dist/foundation/resident-tabs/routing.js

@@ -0,0 +1,8 @@
+/** Invariant: every non-bare or default-off launch stays outside resident discovery and startup. */
+export async function selectResidentHost(options) {
+    if (options.profileId !== "a1" || options.hasSessionSelection || !options.currentLaunchContract)
+        return null;
+    if (!await options.readSetting())
+        return null;
+    return await options.ensureHost();
+}