@timurproko/a1 0.2.7-dev.792 → 0.2.7-dev.801

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

@@ -1,4 +1,4 @@
-export { ensureTerminalHost, resolveTerminalHostPath } from "./ensure-terminal-host.js";
+export { ensureTerminalHost, resolveTerminalHostEntryPath, resolveTerminalHostPath } from "./ensure-terminal-host.js";
 export { readResidentTabLaunchSettings } from "./settings.js";
 export { selectResidentHost } from "./routing.js";
 export { readResidentReleaseHolds } from "./release-holds.js";

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

@@ -1,3 +1,4 @@
+import { type TerminalHostCommand } from "./ensure-terminal-host.js";
 export type MaintenanceAction = "list" | "stop" | "stop-all" | "host-status" | "host-stop";
 export type MaintenanceHostState = "none" | "running" | "stopped" | "unresponsive" | "incompatible" | "refused" | "unverifiable" | "unavailable";
 /** The versioned `a1 tabs` report: `a1-tabs-maintenance-v1`, as printed by the terminal host. */
@@ -26,16 +27,16 @@ export interface MaintenanceOptions {
     readonly platform?: NodeJS.Platform;
     readonly architecture?: string;
     readonly timeoutMs?: number;
-    readonly verify?: (executable: string, platform: NodeJS.Platform, architecture: string) => Promise<unknown>;
-    readonly run?: (executable: string, arguments_: readonly string[], timeoutMs: number) => Promise<{
+    readonly verify?: (addon: string, platform: NodeJS.Platform, architecture: string) => Promise<unknown>;
+    readonly run?: (command: TerminalHostCommand, arguments_: readonly string[], timeoutMs: number) => Promise<{
         readonly code: number;
         readonly stdout: string;
     }>;
 }
 /**
  * Runs one maintenance form through a verified terminal host. When the running host speaks
- * another protocol generation, it retries once with the binary from the release that host
- * recorded, after verifying that release's manifest; it never runs an unverified binary.
+ * another protocol generation, it retries once with the addon from the release that host
+ * recorded, after verifying that release's manifest; it never loads an unverified addon.
  */
 export declare function runTerminalHostMaintenance(options: MaintenanceOptions): Promise<MaintenanceReport>;
 /** The largest maintenance report accepted from the terminal host. */

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

@@ -2,37 +2,38 @@ import { constants } from "node:fs";
 import { access } from "node:fs/promises";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { runBoundedHostCommand } from "./bounded-host-command.js";
-import { resolveTerminalHostPath } from "./ensure-terminal-host.js";
+import { resolveTerminalHostEntryPath, resolveTerminalHostPath } from "./ensure-terminal-host.js";
 import { verifyTerminalHostArtifact } from "./terminal-host-artifact.js";
 const INCOMPATIBLE_EXIT = 4;
 /**
  * Runs one maintenance form through a verified terminal host. When the running host speaks
- * another protocol generation, it retries once with the binary from the release that host
- * recorded, after verifying that release's manifest; it never runs an unverified binary.
+ * another protocol generation, it retries once with the addon from the release that host
+ * recorded, after verifying that release's manifest; it never loads an unverified addon.
  */
 export async function runTerminalHostMaintenance(options) {
     const platform = options.platform ?? process.platform;
     const architecture = options.architecture ?? process.arch;
-    const executable = await firstVerifiedHost(options, options.releaseRoots, platform, architecture);
-    if (executable === undefined)
+    const command = await firstVerifiedHost(options, options.releaseRoots, platform, architecture);
+    if (command === undefined)
         return unavailable(options.action, "no verified terminal host is installed");
-    const report = await invoke(options, executable);
+    const report = await invoke(options, command);
     if (report.exitCode !== INCOMPATIBLE_EXIT || typeof report.releaseRoot !== "string")
         return report;
     const cohort = await firstVerifiedHost({ ...options, environment: {} }, [report.releaseRoot], platform, architecture);
-    if (cohort === undefined || cohort === executable) {
+    if (cohort === undefined || cohort.entry === command.entry) {
         return { ...report, message: "the running tabs use another version whose terminal host cannot be verified" };
     }
-    return await invoke(options, cohort);
+    return await invoke({ ...options, environment: installedEnvironment(options.environment) }, cohort);
 }
 function arguments_(options) {
     const command = options.action === "stop" ? ["stop", options.tabId ?? ""] : [options.action];
     return ["tabs", ...command, "--profile", options.profileRoot, "--data-dir", options.dataDir, "--runtime-dir", options.runtimeDir];
 }
-async function invoke(options, executable) {
+async function invoke(options, command) {
     const timeoutMs = options.timeoutMs ?? 120_000;
     try {
-        const result = await (options.run ?? runHost)(executable, arguments_(options), timeoutMs);
+        const run = options.run ?? ((host, argumentsValue, limit) => runHost(host, argumentsValue, limit, options.environment));
+        const result = await run(command, arguments_(options), timeoutMs);
         const line = result.stdout.trim().split(/\r?\n/u).at(-1) ?? "";
         const parsed = JSON.parse(line);
         if (parsed.schema !== "a1-tabs-maintenance-v1" || typeof parsed.host !== "string")
@@ -48,19 +49,22 @@ async function firstVerifiedHost(options, roots, platform, architecture) {
         ? options.environment[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim()
         : undefined;
     if (override) {
+        const entry = roots[0] === undefined ? undefined : resolveTerminalHostEntryPath(roots[0]);
+        if (entry === undefined)
+            return undefined;
         try {
-            await access(override, constants.R_OK | (platform === "win32" ? 0 : constants.X_OK));
-            return override;
+            await Promise.all([access(override, constants.R_OK), access(entry, constants.R_OK)]);
+            return { executable: process.execPath, entry };
         }
         catch {
             return undefined;
         }
     }
     for (const root of roots) {
-        const candidate = resolveTerminalHostPath(root, {}, platform, architecture);
+        const addon = resolveTerminalHostPath(root, {}, platform, architecture);
         try {
-            await (options.verify ?? verifyTerminalHostArtifact)(candidate, platform, architecture);
-            return candidate;
+            await (options.verify ?? verifyTerminalHostArtifact)(addon, platform, architecture);
+            return { executable: process.execPath, entry: resolveTerminalHostEntryPath(root) };
         }
         catch {
             // Rationale: an older retained release may predate the packaged host; try the next one.
@@ -68,11 +72,22 @@ async function firstVerifiedHost(options, roots, platform, architecture) {
     }
     return undefined;
 }
+function installedEnvironment(environment) {
+    const sanitized = { ...environment };
+    delete sanitized[PRODUCT_IDENTITY.environment.developmentInstanceId];
+    delete sanitized[PRODUCT_IDENTITY.environment.terminalHostPath];
+    return sanitized;
+}
 function unavailable(action, message) {
     return { schema: "a1-tabs-maintenance-v1", command: action, host: "unavailable", message, exitCode: 3 };
 }
 /** The largest maintenance report accepted from the terminal host. */
 export const MAX_MAINTENANCE_REPORT_BYTES = 4 * 1024 * 1024;
-async function runHost(executable, arguments_, timeoutMs) {
-    return await runBoundedHostCommand(executable, arguments_, { maxStdoutBytes: MAX_MAINTENANCE_REPORT_BYTES, timeoutMs, label: "terminal host maintenance" });
+async function runHost(command, arguments_, timeoutMs, environment) {
+    return await runBoundedHostCommand(command, arguments_, {
+        environment,
+        maxStdoutBytes: MAX_MAINTENANCE_REPORT_BYTES,
+        timeoutMs,
+        label: "terminal host maintenance",
+    });
 }

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/resident-tabs/release-holds.d.ts

@@ -1,3 +1,4 @@
+import { type TerminalHostCommand } from "./ensure-terminal-host.js";
 export interface ResidentReleaseHoldReport {
     /** False when any resident record or identity could not be verified; callers then keep every release. */
     readonly complete: boolean;
@@ -11,8 +12,8 @@ export interface ResidentReleaseHoldOptions {
     readonly platform?: NodeJS.Platform;
     readonly architecture?: string;
     readonly timeoutMs?: number;
-    readonly verify?: (executable: string, platform: NodeJS.Platform, architecture: string) => Promise<unknown>;
-    readonly run?: (executable: string, arguments_: readonly string[], timeoutMs: number) => Promise<{
+    readonly verify?: (addon: string, platform: NodeJS.Platform, architecture: string) => Promise<unknown>;
+    readonly run?: (command: TerminalHostCommand, arguments_: readonly string[], timeoutMs: number) => Promise<{
         readonly code: number;
         readonly stdout: string;
     }>;

package/dist/foundation/resident-tabs/release-holds.js

@@ -1,7 +1,8 @@
 import { readdir, stat } from "node:fs/promises";
 import { resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { runBoundedHostCommand } from "./bounded-host-command.js";
-import { resolveTerminalHostPath } from "./ensure-terminal-host.js";
+import { resolveTerminalHostEntryPath, resolveTerminalHostPath } from "./ensure-terminal-host.js";
 import { verifyTerminalHostArtifact } from "./terminal-host-artifact.js";
 const COMPLETE_EMPTY = Object.freeze({ complete: true, releaseRoots: Object.freeze([]), uncertain: Object.freeze([]) });
 /**
@@ -15,22 +16,22 @@ export async function readResidentReleaseHolds(options) {
     const platform = options.platform ?? process.platform;
     const architecture = options.architecture ?? process.arch;
     const verify = options.verify ?? verifyTerminalHostArtifact;
-    let executable;
+    let command;
     for (const root of options.releaseRoots) {
         const candidate = resolveTerminalHostPath(root, {}, platform, architecture);
         try {
             await verify(candidate, platform, architecture);
-            executable = candidate;
+            command = { executable: process.execPath, entry: resolveTerminalHostEntryPath(root) };
             break;
         }
         catch {
             // Rationale: an older release may predate the packaged host; another retained release may still carry it.
         }
     }
-    if (!executable)
+    if (!command)
         return incomplete("no verified terminal host is installed to inspect resident records");
     try {
-        const result = await (options.run ?? runHost)(executable, ["release-holds", "--data-dir", options.dataDir], options.timeoutMs ?? 5_000);
+        const result = await (options.run ?? runHost)(command, ["release-holds", "--data-dir", options.dataDir], options.timeoutMs ?? 5_000);
         const report = JSON.parse(result.stdout.trim().split(/\r?\n/u).at(-1) ?? "");
         if (result.code !== 0 || report.schema !== "a1-resident-release-holds-v1" || typeof report.complete !== "boolean"
             || !isStringArray(report.releaseRoots) || !isStringArray(report.uncertain)) {
@@ -72,6 +73,14 @@ function isStringArray(value) {
 }
 /** The largest release-hold report accepted from the terminal host. */
 export const MAX_RELEASE_HOLD_REPORT_BYTES = 1024 * 1024;
-async function runHost(executable, arguments_, timeoutMs) {
-    return await runBoundedHostCommand(executable, arguments_, { maxStdoutBytes: MAX_RELEASE_HOLD_REPORT_BYTES, timeoutMs, label: "terminal host release-hold inspection" });
+async function runHost(command, arguments_, timeoutMs) {
+    const environment = { ...process.env };
+    delete environment[PRODUCT_IDENTITY.environment.developmentInstanceId];
+    delete environment[PRODUCT_IDENTITY.environment.terminalHostPath];
+    return await runBoundedHostCommand(command, arguments_, {
+        environment,
+        maxStdoutBytes: MAX_RELEASE_HOLD_REPORT_BYTES,
+        timeoutMs,
+        label: "terminal host release-hold inspection",
+    });
 }

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

@@ -3,7 +3,6 @@ export declare const RESIDENT_TABS_MAX_CONCURRENT_STARTS_CAP = 8;
 export declare const RESIDENT_TABS_PREWARM_COUNT = 1;
 export declare const RESIDENT_TABS_PREWARM_CAP = 1;
 export interface ResidentTabLaunchSettings {
-    readonly tabsMax: number;
     readonly tabsAutoName: boolean;
     readonly maxConcurrentStarts: number;
     readonly prewarmCount: number;

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

@@ -7,7 +7,6 @@ export const RESIDENT_TABS_MAX_CONCURRENT_STARTS_CAP = 8;
 export const RESIDENT_TABS_PREWARM_COUNT = 1;
 export const RESIDENT_TABS_PREWARM_CAP = 1;
 const DEFAULTS = Object.freeze({
-    tabsMax: 10,
     tabsAutoName: true,
     maxConcurrentStarts: RESIDENT_TABS_MAX_CONCURRENT_STARTS,
     prewarmCount: RESIDENT_TABS_PREWARM_COUNT,
@@ -46,17 +45,12 @@ export async function readResidentTabLaunchSettings(profileDir, namespace = "a1"
 }
 function resolveLaunchValues(document, migrations) {
     const resolution = resolveOwnedUiSettings({
-        declarations: [
-            OWNED_SETTING_DECLARATIONS.tabsMax,
-            OWNED_SETTING_DECLARATIONS.tabsAutoName,
-        ],
+        declarations: [OWNED_SETTING_DECLARATIONS.tabsAutoName],
         migrations,
         document,
         currentVersion: OWNED_UI_SETTINGS_VERSION,
     });
-    const tabsMax = document.values?.["tabsMax"] ?? settingValue(resolution, "tabsMax");
     return {
-        tabsMax: typeof tabsMax === "number" && Number.isFinite(tabsMax) ? Math.max(1, Math.min(50, Math.trunc(tabsMax))) : DEFAULTS.tabsMax,
         tabsAutoName: settingValue(resolution, "tabsAutoName") === true,
         maxConcurrentStarts: RESIDENT_TABS_MAX_CONCURRENT_STARTS,
         prewarmCount: RESIDENT_TABS_PREWARM_COUNT,

package/dist/foundation/resident-tabs/terminal-host-artifact.d.ts

@@ -1,18 +1,14 @@
 export declare const TERMINAL_HOST_MANIFEST_FILENAME = "terminal-host.manifest.json";
-export declare const TERMINAL_HOST_GENERATION = 1;
-export type TerminalHostArtifactCode = "TERMINAL_HOST_ARTIFACT_MISSING" | "TERMINAL_HOST_ARTIFACT_INCOMPATIBLE" | "TERMINAL_HOST_ARTIFACT_UNSUPPORTED" | "TERMINAL_HOST_ARTIFACT_TAMPERED";
-export interface VerifiedTerminalHostArtifact {
-    readonly executable: string;
-    readonly sessionLock: string;
-    readonly generation: number;
-}
+export type TerminalHostArtifactErrorCode = "TERMINAL_HOST_ARTIFACT_MISSING" | "TERMINAL_HOST_ARTIFACT_TAMPERED" | "TERMINAL_HOST_ARTIFACT_INCOMPATIBLE" | "TERMINAL_HOST_ARTIFACT_UNSUPPORTED";
 export declare class TerminalHostArtifactError extends Error {
-    readonly code: TerminalHostArtifactCode;
-    constructor(message: string, code: TerminalHostArtifactCode);
+    readonly code: TerminalHostArtifactErrorCode;
+    readonly manifestPath: string;
+    constructor(code: TerminalHostArtifactErrorCode, manifestPath: string, message: string);
+}
+export interface VerifiedTerminalHostArtifact {
+    readonly addon: string;
+    readonly entry: string;
+    readonly generation: 1;
 }
-/**
- * Verifies a release's terminal host and its session-writer lock against their manifest before
- * anything executes or loads them: schema, generation, platform, architecture, file names, sizes,
- * and SHA-256 digests.
- */
-export declare function verifyTerminalHostArtifact(executable: string, platform?: NodeJS.Platform, architecture?: string, generation?: number): Promise<VerifiedTerminalHostArtifact>;
+/** Verifies every runtime file certified by the terminal-host v2 manifest before Node loads it. */
+export declare function verifyTerminalHostArtifact(addonPath: string, platform?: NodeJS.Platform, architecture?: string): Promise<VerifiedTerminalHostArtifact>;

package/dist/foundation/resident-tabs/terminal-host-artifact.js

@@ -1,53 +1,78 @@
 import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
 export const TERMINAL_HOST_MANIFEST_FILENAME = "terminal-host.manifest.json";
-export const TERMINAL_HOST_GENERATION = 1;
+const SCHEMA = "a1-terminal-host-artifact-v2";
+const GENERATION = 1;
+const NODE_API = 9;
+const NOTICES_NAME = "terminal-host-THIRD-PARTY-NOTICES.txt";
 export class TerminalHostArtifactError extends Error {
     code;
-    constructor(message, code) {
+    manifestPath;
+    constructor(code, manifestPath, message) {
         super(message);
         this.name = "TerminalHostArtifactError";
         this.code = code;
+        this.manifestPath = manifestPath;
     }
 }
-/**
- * Verifies a release's terminal host and its session-writer lock against their manifest before
- * anything executes or loads them: schema, generation, platform, architecture, file names, sizes,
- * and SHA-256 digests.
- */
-export async function verifyTerminalHostArtifact(executable, platform = process.platform, architecture = process.arch, generation = TERMINAL_HOST_GENERATION) {
-    const directory = dirname(executable);
+/** Verifies every runtime file certified by the terminal-host v2 manifest before Node loads it. */
+export async function verifyTerminalHostArtifact(addonPath, platform = process.platform, architecture = process.arch) {
+    const directory = dirname(addonPath);
+    const releaseRoot = resolve(directory, "../../..");
+    const manifestPath = resolve(directory, TERMINAL_HOST_MANIFEST_FILENAME);
     let manifest;
     try {
-        manifest = JSON.parse(await readFile(resolve(directory, TERMINAL_HOST_MANIFEST_FILENAME), "utf8"));
+        const parsed = JSON.parse(await readFile(manifestPath, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            throw new TypeError("terminal host manifest is not an object");
+        manifest = parsed;
     }
     catch (error) {
-        throw new TerminalHostArtifactError(`terminal host manifest is missing or malformed: ${errorMessage(error)}`, "TERMINAL_HOST_ARTIFACT_MISSING");
+        const code = error instanceof Error && "code" in error && error.code === "ENOENT"
+            ? "TERMINAL_HOST_ARTIFACT_MISSING"
+            : "TERMINAL_HOST_ARTIFACT_INCOMPATIBLE";
+        throw new TerminalHostArtifactError(code, manifestPath, "terminal host manifest is missing or invalid");
     }
-    if (manifest.schema !== "a1-terminal-host-artifact-v1" || manifest.protocolVersion !== 1 || manifest.generation !== generation
-        || manifest.platform !== platform || manifest.architecture !== architecture
-        || manifest.artifact?.filename !== basename(executable) || typeof manifest.sessionLock?.filename !== "string"
-        || basename(manifest.sessionLock.filename) !== manifest.sessionLock.filename) {
-        throw new TerminalHostArtifactError("terminal host manifest is incompatible with this platform or generation", "TERMINAL_HOST_ARTIFACT_INCOMPATIBLE");
+    if (manifest.capability === "unsupported") {
+        throw new TerminalHostArtifactError("TERMINAL_HOST_ARTIFACT_UNSUPPORTED", manifestPath, "terminal host is unsupported on this platform");
     }
-    if (manifest.capability !== "supported") {
-        throw new TerminalHostArtifactError(`resident tabs are not supported on ${platform}-${architecture}`, "TERMINAL_HOST_ARTIFACT_UNSUPPORTED");
+    if (manifest.schema !== SCHEMA || manifest.kind !== "node-addon" || manifest.nodeApi !== NODE_API
+        || manifest.protocolVersion !== 1 || manifest.generation !== GENERATION
+        || manifest.platform !== platform || manifest.architecture !== architecture || manifest.capability !== "supported"
+        || !validRecord(manifest.artifact) || !validRecord(manifest.entry) || !validRecord(manifest.notices)
+        || manifest.artifact.filename !== `${PRODUCT_IDENTITY.artifacts.terminalHostAddon}.node`
+        || manifest.entry.filename !== `dist/foundation/resident-tabs/${PRODUCT_IDENTITY.artifacts.terminalHostEntry}.js`
+        || manifest.notices.filename !== NOTICES_NAME
+        || basename(addonPath) !== manifest.artifact.filename) {
+        throw new TerminalHostArtifactError("TERMINAL_HOST_ARTIFACT_INCOMPATIBLE", manifestPath, "terminal host manifest is incompatible");
     }
-    const sessionLock = resolve(directory, manifest.sessionLock.filename);
-    await verifyFile(executable, manifest.artifact, "terminal host");
-    await verifyFile(sessionLock, manifest.sessionLock, "session-writer lock");
-    return { executable, sessionLock, generation: manifest.generation };
+    const entry = resolve(releaseRoot, manifest.entry.filename);
+    await verifyFile(addonPath, manifest.artifact, manifestPath);
+    await verifyFile(entry, manifest.entry, manifestPath);
+    await verifyFile(resolve(directory, manifest.notices.filename), manifest.notices, manifestPath);
+    return { addon: addonPath, entry, generation: 1 };
 }
-async function verifyFile(path, expected, label) {
-    const [bytes, metadata] = await Promise.all([readFile(path), stat(path)]).catch((error) => {
-        throw new TerminalHostArtifactError(`${label} artifact is unavailable: ${errorMessage(error)}`, "TERMINAL_HOST_ARTIFACT_MISSING");
-    });
-    const digest = createHash("sha256").update(bytes).digest("hex");
-    if (metadata.size !== expected.size || digest !== expected.sha256) {
-        throw new TerminalHostArtifactError(`${label} artifact integrity verification failed`, "TERMINAL_HOST_ARTIFACT_TAMPERED");
-    }
+function validRecord(value) {
+    return typeof value === "object" && value !== null
+        && typeof value.filename === "string"
+        && /^[a-f0-9]{64}$/u.test(value.sha256)
+        && Number.isSafeInteger(value.size) && value.size >= 0;
 }
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
+async function verifyFile(path, record, manifestPath) {
+    let bytes;
+    let metadata;
+    try {
+        [bytes, metadata] = await Promise.all([readFile(path), stat(path)]);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            throw new TerminalHostArtifactError("TERMINAL_HOST_ARTIFACT_MISSING", manifestPath, `certified terminal host file is missing: ${record.filename}`);
+        }
+        throw error;
+    }
+    if (!metadata.isFile() || bytes.byteLength !== record.size || createHash("sha256").update(bytes).digest("hex") !== record.sha256) {
+        throw new TerminalHostArtifactError("TERMINAL_HOST_ARTIFACT_TAMPERED", manifestPath, `certified terminal host file failed verification: ${record.filename}`);
+    }
 }

package/dist/foundation/session-writer-lock/index.d.ts

@@ -19,9 +19,7 @@ export interface SessionWriterHandle {
     bind(createdPath?: string): void;
     release(): void;
 }
-/** Development-only override naming a native lock addon to load first. */
-export declare const SESSION_LOCK_OVERRIDE_ENVIRONMENT = "A1_SESSION_LOCK_PATH";
-/** Security: a release that carries its own lock never loads an addon chosen by the environment or cwd. */
+/** Security: a release that carries its own terminal-host addon never loads one chosen by cwd. */
 export declare function nativeCandidates(moduleUrl?: string, env?: NodeJS.ProcessEnv, cwd?: string, exists?: typeof existsSync): string[];
 export declare function acquireExisting(path: string): SessionWriterHandle;
 export declare function reserveNew(parent: string, name: string): SessionWriterHandle;

package/dist/foundation/session-writer-lock/index.js

@@ -18,15 +18,17 @@ export class SessionWriterConflict extends Error {
 }
 let backendOverride;
 let cachedBackend;
-/** Development-only override naming a native lock addon to load first. */
-export const SESSION_LOCK_OVERRIDE_ENVIRONMENT = "A1_SESSION_LOCK_PATH";
-/** Security: a release that carries its own lock never loads an addon chosen by the environment or cwd. */
+/** Security: a release that carries its own terminal-host addon never loads one chosen by cwd. */
 export function nativeCandidates(moduleUrl = import.meta.url, env = process.env, cwd = process.cwd(), exists = existsSync) {
-    const addon = "a1_session_lock.node";
+    const addon = `${PRODUCT_IDENTITY.artifacts.terminalHostAddon}.node`;
     // Invariant: this module sits at dist/foundation/session-writer-lock/ inside the release root.
     const own = resolve(fileURLToPath(new URL("../../../", moduleUrl)), "dist", "native", `${process.platform}-${process.arch}`, addon);
-    const override = env[PRODUCT_IDENTITY.environment.developmentInstanceId] ? env[SESSION_LOCK_OVERRIDE_ENVIRONMENT]?.trim() || undefined : undefined;
-    const local = exists(own) ? [own] : [resolve(cwd, "dist", "native", `${process.platform}-${process.arch}`, addon), resolve(cwd, ".artifacts", "terminal-host", addon)];
+    const override = env[PRODUCT_IDENTITY.environment.developmentInstanceId]
+        ? env[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim() || undefined
+        : undefined;
+    const local = exists(own)
+        ? [own]
+        : [resolve(cwd, "dist", "native", `${process.platform}-${process.arch}`, addon), resolve(cwd, ".artifacts", "terminal-host", addon)];
     return override ? [override, ...local] : local;
 }
 function loadNativeBackend() {

package/dist/integrations/pi/components/shell-editor-autocomplete.js

@@ -143,7 +143,8 @@ export function createPiShellEditor(options) {
         tui.requestRender();
     };
     let autocompleteProvider;
-    const builtInCatalog = options.keybindingProfile === "a1" ? OWNED_BUILTIN_SLASH_COMMANDS : PINNED_PI_BUILTIN_SLASH_COMMANDS;
+    const builtInCatalog = (options.keybindingProfile === "a1" ? OWNED_BUILTIN_SLASH_COMMANDS : PINNED_PI_BUILTIN_SLASH_COMMANDS)
+        .filter(command => !options.hideSettingsCommand || command.name !== "settings");
     const setAutocompleteCommands = (installed) => {
         // Invariant: collapse is a bare-A1 presentation; the comparison profile installs the pinned list.
         const collapsed = options.keybindingProfile === "a1" && options.skillsPresentation?.() === "collapse"

package/dist/integrations/pi/components/shell-shared-facade.d.ts

@@ -164,6 +164,8 @@ export interface PiShellEditorOptions {
     readonly historyEditor?: HistoryEditorConstructor;
     /** Bare A1 adds ergonomic aliases while comparison profiles retain Pi defaults. */
     readonly keybindingProfile?: "pi" | "a1";
+    /** Resident Agents expose Settings through the global tab instead of a slash command. */
+    readonly hideSettingsCommand?: boolean;
     /** The process's shared keybindings; its profile must match `keybindingProfile`. */
     readonly keybindings?: PiKeybindingsHost;
     readonly getColumns: () => number;

package/dist/integrations/pi/engine/session-runtime.js

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { promisify } from "node:util";
 import { PRODUCT_IDENTITY } from "../../../product-identity.js";
+import { residentProgressObserver } from "../../../foundation/resident-tabs/progress-observation.js";
 import { observeCompactionProgress } from "./compaction-progress.js";
 import { createPiRuntimeIntegration } from "./runtime-integration.js";
 import { PiSessionCommandIntegration } from "./session-integration.js";
@@ -369,8 +370,10 @@ export class PiEngineRuntime {
             return;
         const generation = this.#sessionGeneration;
         this.#unsubscribe = session.subscribe(event => {
-            if (generation === this.#sessionGeneration && !this.#ports.disposed())
-                this.#ports.event(event);
+            if (generation !== this.#sessionGeneration || this.#ports.disposed())
+                return;
+            residentProgressObserver()?.engineDelivery(event);
+            this.#ports.event(event);
         });
     }
     /**

package/dist/integrations/pi/tui-runtime/damage-aware-terminal.d.ts

@@ -52,6 +52,17 @@ export interface DamageAwareTerminalOptions {
     };
     readonly onResize?: () => void;
     readonly onHyperlinkCleanupRequired?: () => void;
+    /** Exact-artifact fault controls evaluated before physical writes; absent in ordinary sessions. */
+    readonly allowWrite?: () => boolean;
+    readonly writeChunks?: (data: string) => readonly string[];
+    /** Optional payload-free observation after a terminal write returns. */
+    readonly onWrite?: (metadata: {
+        readonly bytes: number;
+        readonly fragments: number;
+        readonly transaction: "synchronized-output" | "ordinary";
+        readonly frameId?: number;
+        readonly cause?: string;
+    }) => void;
 }
 /**
  * A fail-closed adapter for one pinned Pi fullscreen write grammar. Semantic