@timurproko/a1 0.2.7-dev.806 → 0.2.7-dev.809

package/dist/composition/session-runtime-registry.js

@@ -0,0 +1,85 @@
+const SESSION_RUNTIME_REFRESH_MS = 30_000;
+/**
+ * The live worktree claims this runtime's agents hold: each agent's session identity, the heartbeat
+ * that keeps the claims fresh, and their release when the runtime is disposed.
+ */
+export class SessionRuntimeRegistry {
+    #options;
+    // Invariant: one entry per agent of this runtime; each agent holds its own claim, and the runtime's exit releases all.
+    #identities = new Map();
+    #owner = null;
+    #timer = null;
+    #refresh = Promise.resolve();
+    #disposed = false;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** The repository context reader for one agent; undefined names the primary agent. */
+    readerFor(agentId) {
+        return async (sessionId, sessionFile, signal) => {
+            const { runtimeId, inspectProcess } = this.#options;
+            const owner = await this.#ownerIdentity();
+            if (owner === null || runtimeId === undefined || inspectProcess === undefined)
+                return null;
+            const identity = { sessionId, sessionFile };
+            this.#identities.set(agentId, identity);
+            const { activateSessionRepositoryContext } = await import("../foundation/lifecycle/session-repository-context.js");
+            const context = await activateSessionRepositoryContext(identity, runtimeId, owner, {
+                signal,
+                inspectProcess,
+                ...(agentId === undefined ? {} : { agentId }),
+            });
+            this.#arm();
+            return context;
+        };
+    }
+    /** Stops the heartbeat, waits for an in-flight refresh, and releases every claim this runtime holds. */
+    async dispose() {
+        this.#disposed = true;
+        if (this.#timer !== null)
+            clearInterval(this.#timer);
+        this.#timer = null;
+        await this.#refresh;
+        const { runtimeId } = this.#options;
+        const owner = await this.#ownerIdentity();
+        if (runtimeId === undefined || owner === null)
+            return;
+        await import("../foundation/lifecycle/session-repository-context.js")
+            .then(module => module.releaseSessionRepositoryRuntime(runtimeId, owner))
+            .catch(() => undefined);
+    }
+    async #ownerIdentity() {
+        const { runtimeId, inspectProcess } = this.#options;
+        if (runtimeId === undefined || inspectProcess === undefined)
+            return null;
+        this.#owner ??= inspectProcess(process.pid).catch(() => null);
+        return await this.#owner;
+    }
+    #arm() {
+        if (this.#timer !== null)
+            return;
+        this.#timer = setInterval(() => this.#queueRefresh(), this.#options.refreshMs ?? SESSION_RUNTIME_REFRESH_MS);
+        this.#timer.unref();
+    }
+    #queueRefresh() {
+        const { runtimeId, inspectProcess } = this.#options;
+        if (this.#disposed || this.#identities.size === 0 || runtimeId === undefined || inspectProcess === undefined)
+            return;
+        this.#refresh = this.#refresh.then(async () => {
+            if (this.#disposed)
+                return;
+            const owner = await this.#ownerIdentity();
+            if (owner === null)
+                return;
+            const { registerSessionRepositoryRuntime } = await import("../foundation/lifecycle/session-repository-context.js");
+            for (const [agentId, identity] of this.#identities) {
+                if (this.#disposed)
+                    return;
+                await registerSessionRepositoryRuntime(identity, runtimeId, owner, {
+                    inspectProcess,
+                    ...(agentId === undefined ? {} : { agentId }),
+                }).catch(() => undefined);
+            }
+        }).catch(() => undefined);
+    }
+}

package/dist/composition/settings-route-host.d.ts

@@ -9,5 +9,10 @@ export interface OwnedReferenceProviders {
     hotkeys(): Promise<ReferenceDocumentProvider>;
     session(): Promise<ReferenceDocumentProvider>;
 }
+/** How the settings route is presented. */
+export interface OwnedRouteHostOptions {
+    /** The resident Settings tab: the screen is the tab, so it offers no screen-level close. */
+    readonly settingsPinned?: boolean;
+}
 /** Declares settings and lazy document routes. */
-export declare function createOwnedRouteHost(settings: OwnedSettingsManager, references?: OwnedReferenceProviders): UiRouteHost;
+export declare function createOwnedRouteHost(settings: OwnedSettingsManager, references?: OwnedReferenceProviders, options?: OwnedRouteHostOptions): UiRouteHost;

package/dist/composition/settings-route-host.js

@@ -3,7 +3,7 @@ import { SETTINGS_APP_ID, SETTINGS_ROUTE } from "../features/owned-ui/settings-r
 import { piTheme, renderPiAccentPreview } from "../integrations/pi/components/upstream/theme/theme.js";
 import { faint } from "../ui/components/text.js";
 /** Declares settings and lazy document routes. */
-export function createOwnedRouteHost(settings, references) {
+export function createOwnedRouteHost(settings, references, options = {}) {
     const routes = new Set([SETTINGS_ROUTE, ...(references === undefined ? [] : [CHANGELOG_ROUTE, HOTKEYS_ROUTE, "session"])]);
     return {
         claims: route => routes.has(route),
@@ -11,7 +11,7 @@ export function createOwnedRouteHost(settings, references) {
             if (!routes.has(route))
                 return null;
             if (route === SETTINGS_ROUTE) {
-                return deferredSurface(SETTINGS_APP_ID, "settings", () => loadSettingsSurface(settings));
+                return deferredSurface(SETTINGS_APP_ID, "settings", () => loadSettingsSurface(settings, options.settingsPinned === true));
             }
             const changelog = route === CHANGELOG_ROUTE;
             const session = route === "session";
@@ -61,9 +61,10 @@ function deferredSurface(id, label, load) {
         onExitRequested: listener => { onExit = listener; },
     };
 }
-async function loadSettingsSurface(settings) {
+async function loadSettingsSurface(settings, pinned) {
     const { SettingsApp } = await import("../features/owned-ui/settings-app.js");
-    return hostApp(SETTINGS_APP_ID, SETTINGS_ROUTE, () => new SettingsApp(settings));
+    // Invariant: a pinned Settings tab closes as a tab; neither Esc nor one Ctrl+C dismisses its screen.
+    return hostApp(SETTINGS_APP_ID, SETTINGS_ROUTE, () => new SettingsApp(settings, { pinned }), !pinned);
 }
 async function loadReferenceSurface(settings, id, route, title, document) {
     // Rationale: the app module and the document load together, so a document that fails
@@ -80,7 +81,7 @@ async function loadReferenceSurface(settings, id, route, title, document) {
         }),
     }));
 }
-async function hostApp(id, route, create) {
+async function hostApp(id, route, create, closeOnInterrupt = true) {
     const [{ UiAppHost }, { UiAppRegistry }] = await Promise.all([
         import("../ui/apps/host.js"),
         import("../ui/apps/registry.js"),
@@ -94,7 +95,7 @@ async function hostApp(id, route, create) {
     let onExit = () => undefined;
     const host = new UiAppHost({
         registry,
-        closeOnInterrupt: true,
+        closeOnInterrupt,
         theme: pinnedTheme(),
         surface: {
             size: () => size,

package/dist/composition/startup-route.d.ts

@@ -0,0 +1,32 @@
+import type { OwnedUiShellEngineOptions } from "../app/session-shell/index.js";
+import type { ReleaseNoteCatalog } from "../features/owned-ui/release-notes.js";
+type StartupRoute = NonNullable<OwnedUiShellEngineOptions["startupRoute"]>;
+export interface StartupReleaseNoteOptions {
+    readonly ownedSurfaces: boolean;
+    /** Deterministic catalog and version seams for composition tests. */
+    readonly releaseNotes?: ReleaseNoteCatalog;
+    readonly packageVersion?: string;
+    /** Without a profile there is nowhere to remember the note as seen, so it is never shown on startup. */
+    readonly profileId?: string;
+    readonly configDir: string;
+}
+export declare function readPackageVersion(): Promise<string>;
+/**
+ * The release notes bare A1 ships and the one note this version shows once per profile on startup:
+ * the packaged catalog (or why it could not be read), the running version, and the claim that
+ * marks the note seen after its route closes.
+ */
+export declare class StartupReleaseNote {
+    #private;
+    readonly catalog: ReleaseNoteCatalog | null;
+    readonly failure: unknown;
+    readonly packageVersion: string | null;
+    static load(options: StartupReleaseNoteOptions): Promise<StartupReleaseNote>;
+    private constructor();
+    /** The changelog route to present after the first frame, or undefined when there is no unseen note to show. */
+    get startupRoute(): StartupRoute | undefined;
+    /** Waits for a pending acknowledgement; a failed one stays unseen and is never reported. */
+    settleAcknowledgement(): Promise<void>;
+    releaseClaim(): Promise<void>;
+}
+export {};

package/dist/composition/startup-route.js

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+export async function readPackageVersion() {
+    const manifest = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
+    const version = manifest?.version;
+    if (typeof version !== "string")
+        throw new Error("A1 package version is unavailable");
+    return version;
+}
+/**
+ * The release notes bare A1 ships and the one note this version shows once per profile on startup:
+ * the packaged catalog (or why it could not be read), the running version, and the claim that
+ * marks the note seen after its route closes.
+ */
+export class StartupReleaseNote {
+    catalog;
+    failure;
+    packageVersion;
+    #current;
+    #claim;
+    #acknowledgement = null;
+    static async load(options) {
+        let catalog = null;
+        let failure;
+        if (options.ownedSurfaces) {
+            try {
+                catalog = options.releaseNotes
+                    ?? await import("../features/owned-ui/release-notes.js").then(module => module.readPackagedReleaseNotes());
+            }
+            catch (error) {
+                failure = error;
+            }
+        }
+        const packageVersion = options.ownedSurfaces ? options.packageVersion ?? await readPackageVersion() : null;
+        const current = packageVersion === null ? null : catalog?.current(packageVersion) ?? null;
+        const profileId = options.profileId;
+        const claim = current === null || profileId === undefined
+            ? null
+            : await import("../features/owned-ui/release-note-state.js").then(module => module.claimReleaseNote({
+                configDir: options.configDir, profileId, version: current.version,
+            }));
+        return new StartupReleaseNote(catalog, failure, packageVersion, current, claim);
+    }
+    constructor(catalog, failure, packageVersion, current, claim) {
+        this.catalog = catalog;
+        this.failure = failure;
+        this.packageVersion = packageVersion;
+        this.#current = current;
+        this.#claim = claim;
+    }
+    /** The changelog route to present after the first frame, or undefined when there is no unseen note to show. */
+    get startupRoute() {
+        const current = this.#current;
+        const claim = this.#claim;
+        if (current === null || claim === null)
+            return undefined;
+        return {
+            route: "changelog",
+            input: { document: current.markdown },
+            onClosed: () => {
+                this.#acknowledgement ??= claim.acknowledge();
+                return this.#acknowledgement;
+            },
+        };
+    }
+    /** Waits for a pending acknowledgement; a failed one stays unseen and is never reported. */
+    async settleAcknowledgement() {
+        await this.#acknowledgement?.catch(() => undefined);
+    }
+    async releaseClaim() {
+        await this.#claim?.release();
+    }
+}

package/dist/features/owned-ui/settings-app.d.ts

@@ -12,7 +12,10 @@ export declare const SETTINGS_SHORTCUTS: ShortcutRegistry<Action>;
 export declare class SettingsApp implements UiApp {
     #private;
     readonly id = "settings";
-    constructor(session: OwnedSettingsManager);
+    /** `pinned` presents the screen as a resident Settings tab, which offers no screen-level close. */
+    constructor(session: OwnedSettingsManager, options?: {
+        readonly pinned?: boolean;
+    });
     onActivate(host: AppHostServices): void;
     onClose(_host: AppHostServices): void;
     render(rect: PaneRect, host: AppHostServices): readonly string[];

package/dist/features/owned-ui/settings-app.js

@@ -120,8 +120,11 @@ export class SettingsApp {
     #activeUntil = 0;
     #activityTimer;
     #renderedScroll;
-    constructor(session) {
+    #pinned;
+    /** `pinned` presents the screen as a resident Settings tab, which offers no screen-level close. */
+    constructor(session, options = {}) {
         this.#session = session;
+        this.#pinned = options.pinned === true;
     }
     onActivate(host) {
         this.#closed = false;
@@ -251,7 +254,8 @@ export class SettingsApp {
         const selected = indexOfKey(rows, this.#selectedKey);
         switch (action) {
             case "close":
-                host.close();
+                if (!this.#pinned)
+                    host.close();
                 return { consumed: true };
             case "open-filter":
                 this.#scrollBeforeFilter = this.#scroll;
@@ -1016,7 +1020,9 @@ export class SettingsApp {
             return this.#dialogLines(open, width, theme);
         // Rationale: standing guidance is more useful than transient feedback; failures still
         // roll back without displacing the Settings interaction contract.
-        const status = renderShortcutHintsWithClose(SETTINGS_SHORTCUTS.hintEntries(SCOPE), theme, width, width > 0 ? 1 : 0);
+        const entries = SETTINGS_SHORTCUTS.hintEntries(SCOPE).filter(entry => !this.#pinned
+            || entry.key !== DIALOG_CLOSE_SHORTCUT_HINT.key || entry.action !== DIALOG_CLOSE_SHORTCUT_HINT.action);
+        const status = renderShortcutHintsWithClose(entries, theme, width, width > 0 ? 1 : 0);
         const input = this.#filter;
         if (input === null)
             return [status];

package/dist/features/resident-tab/shortcut-declarations.js

@@ -13,7 +13,7 @@ export const RESIDENT_TAB_SHORTCUTS = Object.freeze([
     { id: "tabs.new", defaultKey: "alt+a", scope: "global", description: "New A1 tab" },
     { id: "tabs.close", defaultKey: "alt+w", scope: "global", description: "Close A1 tab" },
     { id: "tabs.rename", defaultKey: "f2", scope: "global", description: "Rename A1 tab" },
-    { id: "tabs.settings", defaultKey: "alt+.", scope: "global", description: "Open Settings tab" },
+    { id: "tabs.settings", defaultKey: "alt+,", scope: "global", description: "Open Settings tab" },
     ...jumps,
     { id: "tabs.next", defaultKey: null, scope: "global", description: "View next A1 tab" },
     { id: "tabs.previous", defaultKey: null, scope: "global", description: "View previous A1 tab" },

package/dist/features/resident-tab/status-deriver.d.ts

@@ -1,9 +1,10 @@
-export type ResidentTabDerivedStatus = "starting" | "working" | "needs-input" | "done-unseen" | "idle" | "failed";
+/** How the tab's last agent turn settled; it persists until the next turn starts. */
+export type ResidentTabTurnSettlement = "done" | "aborted" | "error";
+export type ResidentTabDerivedStatus = "starting" | "working" | "needs-input" | "idle" | "failed" | ResidentTabTurnSettlement;
 export interface ResidentTabFacts {
     readonly lifecycle: string;
     readonly pendingRequests: number;
     readonly queuedInput: number;
-    readonly stopReason?: string;
-    readonly settledUnseen?: boolean;
+    readonly lastTurn?: ResidentTabTurnSettlement;
 }
 export declare function deriveResidentTabStatus(facts: ResidentTabFacts): ResidentTabDerivedStatus;

package/dist/features/resident-tab/status-deriver.js

@@ -1,3 +1,4 @@
+// Invariant: `failed` is reserved for a failed tab lifecycle; a turn that errored reports `error`.
 export function deriveResidentTabStatus(facts) {
     if (facts.lifecycle === "failed")
         return "failed";
@@ -7,9 +8,5 @@ export function deriveResidentTabStatus(facts) {
         return "working";
     if (facts.lifecycle === "starting")
         return "starting";
-    if (facts.stopReason === "error")
-        return "failed";
-    if (facts.settledUnseen === true)
-        return "done-unseen";
-    return "idle";
+    return facts.lastTurn ?? "idle";
 }

package/dist/foundation/release/bootstrap.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { CLEAR_EXIT_INTERVAL_MS, restoreAfterOwnedExit } from "../terminal-cleanup/index.js";
+import { RESIDENT_DETACH_INTERVAL_MS, restoreAfterOwnedExit } from "../terminal-cleanup/index.js";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { connect } from "node:net";
 import { resolve } from "node:path";
@@ -64,7 +64,7 @@ async function runBootstrapAttempt(options, retriesRemaining) {
                 residentRootExecutable: resident.executable.executable,
                 residentRootArguments: JSON.stringify([
                     resident.executable.entry,
-                    "attach", "--endpoint", resident.endpoint, "--cwd", process.cwd(), "--clear-exit-ms", String(CLEAR_EXIT_INTERVAL_MS),
+                    "attach", "--endpoint", resident.endpoint, "--cwd", process.cwd(), "--clear-exit-ms", String(RESIDENT_DETACH_INTERVAL_MS),
                     "--profile", environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir,
                     "--settings-file", resolve(agentProfileDir, "settings.json"),
                     "--data-dir", paths.dataDir, "--runtime-dir", paths.runtimeDir,

package/dist/foundation/resident-tabs/bridge-client.d.ts

@@ -1,4 +1,4 @@
-export type ResidentTabStatus = "starting" | "working" | "needs-input" | "done-unseen" | "idle" | "unresponsive" | "stalled" | "crashed" | "restarting" | "failed";
+export type ResidentTabStatus = "starting" | "working" | "needs-input" | "done-unseen" | "done" | "aborted" | "error" | "idle" | "unresponsive" | "stalled" | "crashed" | "restarting" | "failed";
 export interface TabBridgeCredentials {
     readonly tabId: string;
     readonly token: string;

package/dist/foundation/resident-tabs/bridge-client.js

@@ -137,7 +137,8 @@ export class TabBridgeClient {
             if (start === -1) {
                 let retained = 0;
                 const maximum = Math.min(prefix.length - 1, pending.length);
-                for (let length = maximum; length > 0; length--) {
+                // Invariant: a lone trailing Esc is a user key and passes at once; only `\x1bP` or more is withheld.
+                for (let length = maximum; length > 1; length--) {
                     if (pending.endsWith(prefix.slice(0, length))) {
                         retained = length;
                         break;

package/dist/foundation/resident-tabs/fixture-control.d.ts

@@ -0,0 +1,7 @@
+export type ResidentFixtureStoppedStage = "child-render-write";
+export interface ResidentFixtureControlPort {
+    stopped(stage: ResidentFixtureStoppedStage): boolean;
+    fragmentChildWrite(data: string): readonly string[];
+}
+/** Returns the exact-artifact fixture control, or null for every ordinary resident child. */
+export declare function residentFixtureControl(environment?: NodeJS.ProcessEnv): ResidentFixtureControlPort | null;

package/dist/foundation/resident-tabs/fixture-control.js

@@ -0,0 +1,35 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { residentProgressObserver } from "./progress-observation.js";
+/** Returns the exact-artifact fixture control, or null for every ordinary resident child. */
+export function residentFixtureControl(environment = process.env) {
+    const directory = environment[PRODUCT_IDENTITY.environment.residentFixtureControlDir];
+    if (environment === process.env)
+        delete process.env[PRODUCT_IDENTITY.environment.residentFixtureControlDir];
+    // Invariant: launch erases the bridge tab identity; the observer retains the observed one.
+    const tabId = residentProgressObserver(environment)?.tabId;
+    if (!directory || !tabId || !/^[a-z0-9-]{1,128}$/iu.test(tabId))
+        return null;
+    return {
+        stopped: stage => existsSync(join(directory, `${tabId}.${stage}.stop`)),
+        fragmentChildWrite: data => existsSync(join(directory, `${tabId}.child-render-fragments.enable`))
+            ? boundedFragments(data)
+            : [data],
+    };
+}
+function boundedFragments(data) {
+    const points = [...data];
+    if (points.length <= 1)
+        return [data];
+    if (points.length <= 16)
+        return points;
+    const fragments = points.slice(0, 8);
+    const middle = points.slice(8, -8);
+    const chunkSize = Math.max(1, Math.ceil(middle.length / 48));
+    for (let index = 0; index < middle.length; index += chunkSize) {
+        fragments.push(middle.slice(index, index + chunkSize).join(""));
+    }
+    fragments.push(...points.slice(-8));
+    return fragments;
+}

package/dist/foundation/resident-tabs/progress-observation.d.ts

@@ -0,0 +1,7 @@
+export interface ResidentProgressObserverPort {
+    readonly tabId: string;
+    engineDelivery(event: unknown): void;
+    childRenderWrite(bytes: number, fragments: number, transaction: "synchronized-output" | "ordinary", frameId?: number, renderCause?: string): void;
+}
+/** Returns the opt-in payload-free observer for a resident child, or null on ordinary launches. */
+export declare function residentProgressObserver(environment?: NodeJS.ProcessEnv): ResidentProgressObserverPort | null;

package/dist/foundation/resident-tabs/progress-observation.js

@@ -0,0 +1,119 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+const OBSERVATION_DIRECTORY_ENV = PRODUCT_IDENTITY.environment.residentProgressObservationDir;
+const OBSERVATION_RUN_ENV = PRODUCT_IDENTITY.environment.residentProgressRunId;
+const MAX_PENDING_BYTES = 256 * 1024;
+class ResidentProgressObserver {
+    #directory;
+    #runId;
+    #tabId;
+    #incarnation;
+    #processInstance;
+    #path;
+    #sequence = 0;
+    #engineSequence = 0;
+    #pendingBytes = 0;
+    #lost = 0;
+    #writing = Promise.resolve();
+    #failed = false;
+    get tabId() { return this.#tabId; }
+    constructor(directory, runId, tabId, incarnation) {
+        this.#directory = directory;
+        this.#runId = runId;
+        this.#tabId = tabId;
+        this.#incarnation = incarnation;
+        this.#processInstance = `${process.pid}-${randomUUID()}`;
+        this.#path = join(directory, `child-${this.#processInstance}.jsonl`);
+    }
+    engineDelivery(event) {
+        this.#engineSequence += 1;
+        this.#observe("engine-delivery", {
+            eventSequence: this.#engineSequence,
+            eventKind: eventKind(event),
+            count: 1,
+        });
+    }
+    childRenderWrite(bytes, fragments, transaction, frameId, renderCause) {
+        this.#observe("child-render-write", {
+            eventSequence: this.#engineSequence,
+            bytes,
+            count: 1,
+            fragmentCount: fragments,
+            transactionKind: transaction,
+            ...(frameId === undefined ? {} : { frameId }),
+            ...(renderCause === undefined ? {} : { renderCause }),
+        });
+    }
+    #observe(stage, fields) {
+        if (this.#failed)
+            return;
+        const lostBefore = this.#lost;
+        const record = {
+            schema: "a1-resident-progress-observation-v1",
+            runId: this.#runId,
+            role: "child",
+            stage,
+            pid: process.pid,
+            processInstance: this.#processInstance,
+            timestampUnixUs: Math.round((performance.timeOrigin + performance.now()) * 1_000),
+            // Rationale: timeOrigin is calibrated to the Unix epoch; retain a conservative cross-process error.
+            clockErrorUs: 1_000,
+            sequence: ++this.#sequence,
+            tabId: this.#tabId,
+            incarnation: this.#incarnation,
+            lostBefore,
+            ...fields,
+        };
+        const line = `${JSON.stringify(record)}\n`;
+        const length = Buffer.byteLength(line);
+        if (this.#pendingBytes + length > MAX_PENDING_BYTES) {
+            this.#lost = lostBefore + 1;
+            return;
+        }
+        this.#lost = 0;
+        this.#pendingBytes += length;
+        this.#writing = this.#writing.then(async () => {
+            await mkdir(this.#directory, { recursive: true });
+            await appendFile(this.#path, line, "utf8");
+        }).catch(() => {
+            this.#failed = true;
+        }).finally(() => {
+            this.#pendingBytes -= length;
+        });
+    }
+}
+let observer;
+/** Returns the opt-in payload-free observer for a resident child, or null on ordinary launches. */
+export function residentProgressObserver(environment = process.env) {
+    if (environment === process.env && observer !== undefined)
+        return observer;
+    const directory = environment[OBSERVATION_DIRECTORY_ENV];
+    const runId = environment[OBSERVATION_RUN_ENV];
+    const tabId = environment[PRODUCT_IDENTITY.environment.residentProgressTabId];
+    const incarnation = Number(environment[PRODUCT_IDENTITY.environment.residentProgressTabIncarnation]);
+    const value = directory && runId && runId.length <= 128 && tabId && Number.isSafeInteger(incarnation) && incarnation >= 0
+        ? new ResidentProgressObserver(directory, runId, tabId, incarnation)
+        : null;
+    if (environment === process.env) {
+        observer = value;
+        // Security: test evidence paths and tab identity are not child/tool configuration. Retain them only in
+        // this observer instance so extensions and spawned tools cannot append to the fixture trace.
+        for (const name of [
+            OBSERVATION_DIRECTORY_ENV,
+            OBSERVATION_RUN_ENV,
+            PRODUCT_IDENTITY.environment.residentProgressTabId,
+            PRODUCT_IDENTITY.environment.residentProgressTabIncarnation,
+        ])
+            delete process.env[name];
+    }
+    return value;
+}
+function eventKind(event) {
+    if (typeof event !== "object" || event === null)
+        return "unknown";
+    const value = event.type;
+    return typeof value === "string" && /^[a-z][a-z0-9_-]{0,63}$/iu.test(value) ? value : "unknown";
+}

package/dist/foundation/terminal-cleanup/index.d.ts

@@ -1,3 +1,3 @@
-export { CLEAR_EXIT_INTERVAL_MS, EMERGENCY_TERMINAL_RESET, boundedCleanup, restoreAfterOwnedExit, restoreProcessTerminal } from "./terminal-reset.js";
+export { CLEAR_EXIT_INTERVAL_MS, EMERGENCY_TERMINAL_RESET, RESIDENT_DETACH_INTERVAL_MS, boundedCleanup, restoreAfterOwnedExit, restoreProcessTerminal } from "./terminal-reset.js";
 export { installFatalExit, writeFatalDiagnostic } from "./fatal-exit.js";
 export type { FatalExitOptions } from "./fatal-exit.js";

package/dist/foundation/terminal-cleanup/index.js

@@ -1,2 +1,2 @@
-export { CLEAR_EXIT_INTERVAL_MS, EMERGENCY_TERMINAL_RESET, boundedCleanup, restoreAfterOwnedExit, restoreProcessTerminal } from "./terminal-reset.js";
+export { CLEAR_EXIT_INTERVAL_MS, EMERGENCY_TERMINAL_RESET, RESIDENT_DETACH_INTERVAL_MS, boundedCleanup, restoreAfterOwnedExit, restoreProcessTerminal } from "./terminal-reset.js";
 export { installFatalExit, writeFatalDiagnostic } from "./fatal-exit.js";

package/dist/foundation/terminal-cleanup/terminal-reset.d.ts

@@ -1,4 +1,9 @@
 export declare const CLEAR_EXIT_INTERVAL_MS = 500;
+/**
+ * How long a first `Ctrl+C` keeps the resident attach client's detach chord armed. It matches the
+ * owned dialogs' interrupt chord so an unhurried double press leaves resident tabs from any tab.
+ */
+export declare const RESIDENT_DETACH_INTERVAL_MS = 1500;
 export declare const EMERGENCY_TERMINAL_RESET: string;
 export declare function restoreProcessTerminal(): void;
 export declare function restoreAfterOwnedExit(ownsTerminal: boolean, code: number | null, signal: string | null, restore?: () => void): number;

package/dist/foundation/terminal-cleanup/terminal-reset.js

@@ -1,5 +1,10 @@
 import { writeSync } from "node:fs";
 export const CLEAR_EXIT_INTERVAL_MS = 500;
+/**
+ * How long a first `Ctrl+C` keeps the resident attach client's detach chord armed. It matches the
+ * owned dialogs' interrupt chord so an unhurried double press leaves resident tabs from any tab.
+ */
+export const RESIDENT_DETACH_INTERVAL_MS = 1_500;
 // Protocol: reset modes on both screens; setting keyboard flags to zero is idempotent,
 // unlike repeatedly popping a keyboard-protocol stack owned by a parent application.
 // Resetting parent-screen margins homes the cursor, so preserve its restored position.