@timurproko/a1 0.2.7-dev.1231 → 0.2.7-dev.1233

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

@@ -0,0 +1,55 @@
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { RUNTIME_CONTROL_API } from "./runtime-control.js";
+import { runBoundedHostCommand } from "./bounded-host-command.js";
+import { resolveTerminalHostEntryPath, resolveTerminalHostPath } from "./ensure-terminal-host.js";
+import { verifyTerminalHostArtifact } from "./terminal-host-artifact.js";
+/** Activation authority requires a stable authenticated source-contract set, never an idle Agent. */
+export async function assertResidentContinuity(options) {
+    const { inspect = inspectResidentContinuity, ...context } = options;
+    const first = await inspect(context);
+    const second = await inspect(context);
+    if (first !== second && second !== await inspect(context)) {
+        throw new Error("Resident workspace changed during update readiness; the prior client remains selected.");
+    }
+}
+/** Native inspection/import is read-only toward execution and never starts or stops a source. */
+export async function inspectResidentContinuity(options) {
+    let hasRecords = false;
+    for (const directory of ["tabs", "resident-workspaces"]) {
+        try {
+            hasRecords ||= (await readdir(resolve(options.dataDir, directory))).length > 0;
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+                throw new Error("Resident workspace discovery is unavailable; update activation was refused.");
+            }
+        }
+    }
+    if (!hasRecords)
+        return "empty";
+    const manifest = JSON.parse(await readFile(resolve(options.releaseRoot, "package.json"), "utf8"));
+    const contracts = manifest.residentControlContracts;
+    if (!Array.isArray(contracts)
+        || ![RUNTIME_CONTROL_API, "resident-workspace-v1"].every(contract => contracts.includes(contract))) {
+        throw new Error("Candidate does not preserve the stable resident control and workspace contracts; activation was refused.");
+    }
+    const addon = resolveTerminalHostPath(options.releaseRoot, {}, process.platform, process.arch);
+    await verifyTerminalHostArtifact(addon, process.platform, process.arch);
+    const result = await runBoundedHostCommand({ executable: process.execPath, entry: resolveTerminalHostEntryPath(options.releaseRoot) }, [
+        "workspace-check", "--profile", options.profileRoot,
+        "--data-dir", options.dataDir, "--runtime-dir", options.runtimeDir,
+    ], { label: "resident continuity check", maxStdoutBytes: 4096, timeoutMs: 8_000, environment: options.environment });
+    let report;
+    try {
+        report = JSON.parse(result.stdout.trim());
+    }
+    catch {
+        throw new Error("Resident control compatibility could not be verified; the prior client remains selected.");
+    }
+    if (result.code !== 0 || report.schema !== "resident-workspace-check-v1" || report.compatible !== true
+        || typeof report.fingerprint !== "string" || !/^[a-f0-9]{64}$/u.test(report.fingerprint)) {
+        throw new Error("Resident control compatibility could not be verified; the prior client remains selected.");
+    }
+    return report.fingerprint;
+}

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

@@ -10,3 +10,6 @@ export { runTerminalHostMaintenance } from "./maintenance.js";
 export type { MaintenanceAction, MaintenanceHostState, MaintenanceOptions, MaintenanceReport } from "./maintenance.js";
 export { DOCTOR_MAX_BYTES, writeDoctorBundle } from "./doctor.js";
 export type { DoctorBundle, DoctorOptions } from "./doctor.js";
+export type { ContinuityOptions } from "./continuity.js";
+/** Load native continuity inspection only when a caller is preparing client activation. */
+export declare function assertResidentContinuity(options: import("./continuity.js").ContinuityOptions): Promise<void>;

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

@@ -4,3 +4,7 @@ export { selectResidentHost } from "./routing.js";
 export { readResidentReleaseHolds } from "./release-holds.js";
 export { runTerminalHostMaintenance } from "./maintenance.js";
 export { DOCTOR_MAX_BYTES, writeDoctorBundle } from "./doctor.js";
+/** Load native continuity inspection only when a caller is preparing client activation. */
+export async function assertResidentContinuity(options) {
+    await (await import("./continuity.js")).assertResidentContinuity(options);
+}

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

@@ -1,5 +1,5 @@
 import { type TerminalHostCommand } from "./ensure-terminal-host.js";
-export type MaintenanceAction = "list" | "stop" | "stop-all" | "host-status" | "host-stop";
+export type MaintenanceAction = "list" | "stop" | "stop-all" | "host-status" | "host-stop" | "runtime-control";
 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. */
 export interface MaintenanceReport {

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

@@ -44,15 +44,18 @@ export async function readResidentReleaseHolds(options) {
     }
 }
 async function hasResidentRecords(dataDir) {
-    let profiles;
-    try {
-        profiles = await readdir(resolve(dataDir, "tabs"));
-    }
-    catch (error) {
-        return !(error instanceof Error && "code" in error && error.code === "ENOENT");
+    for (const directory of ["tabs", "resident-workspaces"]) {
+        try {
+            // Invariant: native inspection, not a following stat, judges unknown or linked entries.
+            if ((await readdir(resolve(dataDir, directory))).length > 0)
+                return true;
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                return true;
+        }
     }
-    // Invariant: native inspection, not a following stat, judges unknown or linked namespace entries.
-    return profiles.length > 0;
+    return false;
 }
 function incomplete(reason) {
     return { complete: false, releaseRoots: [], uncertain: [reason] };

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

@@ -0,0 +1,38 @@
+import { type MaintenanceOptions, type MaintenanceReport } from "./maintenance.js";
+/** Mandatory native control semantics; optional methods never establish source authority. */
+export declare const RUNTIME_CONTROL_API = "resident-control-v1";
+export declare const RUNTIME_CONTROL_CORE: readonly ["attach", "tab.list", "tab.view", "input", "resize", "detach", "controller-boundary"];
+export interface RuntimeControlIdentity {
+    readonly releaseId: string;
+    readonly scope: string;
+    readonly epoch: number;
+    readonly bootId: string;
+    readonly osSessionId: string;
+}
+export interface RuntimeControlDescription extends RuntimeControlIdentity {
+    readonly api: typeof RUNTIME_CONTROL_API;
+    readonly generation: 1;
+    readonly core: readonly string[];
+    readonly frameLimit: number;
+    readonly inputLimit: number;
+    readonly retryInput: false;
+}
+export type RuntimeControlVerdict = {
+    readonly status: "compatible";
+    readonly contract: RuntimeControlDescription;
+} | {
+    readonly status: "blocked";
+    readonly reason: "unavailable" | "invalid-contract" | "unsupported-api" | "source-mismatch" | "stale-epoch" | "missing-core";
+};
+/**
+ * Validates an authenticated source's descriptor against separately verified source custody.
+ * This is not an activation verdict: the caller must also reconcile every live tab and fence
+ * changes to that topology before committing a client selection.
+ */
+export declare function assessRuntimeControl(value: unknown, expected: RuntimeControlIdentity): RuntimeControlVerdict;
+export interface ReadRuntimeControlOptions extends Omit<MaintenanceOptions, "action" | "tabId"> {
+    readonly expected: RuntimeControlIdentity;
+    readonly maintain?: (options: MaintenanceOptions) => Promise<MaintenanceReport>;
+}
+/** A bounded read-only authenticated exchange; it never starts a host or substitutes a release. */
+export declare function readRuntimeControl(options: ReadRuntimeControlOptions): Promise<RuntimeControlVerdict>;

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

@@ -0,0 +1,73 @@
+import { runTerminalHostMaintenance } from "./maintenance.js";
+/** Mandatory native control semantics; optional methods never establish source authority. */
+export const RUNTIME_CONTROL_API = "resident-control-v1";
+export const RUNTIME_CONTROL_CORE = Object.freeze([
+    "attach", "tab.list", "tab.view", "input", "resize", "detach", "controller-boundary",
+]);
+/**
+ * Validates an authenticated source's descriptor against separately verified source custody.
+ * This is not an activation verdict: the caller must also reconcile every live tab and fence
+ * changes to that topology before committing a client selection.
+ */
+export function assessRuntimeControl(value, expected) {
+    if (!isRecord(value))
+        return blocked("invalid-contract");
+    if (value.api !== RUNTIME_CONTROL_API || value.generation !== 1)
+        return blocked("unsupported-api");
+    if (!identityValid(value) || !identityValid(expected)
+        || !boundedStrings(value.core) || typeof value.retryInput !== "boolean"
+        || !positiveInteger(value.frameLimit, 2 * 1024 * 1024)
+        || !positiveInteger(value.inputLimit, 1024 * 1024) || value.inputLimit > value.frameLimit) {
+        return blocked("invalid-contract");
+    }
+    if (value.releaseId !== expected.releaseId || value.scope !== expected.scope
+        || value.bootId !== expected.bootId || value.osSessionId !== expected.osSessionId)
+        return blocked("source-mismatch");
+    if (value.epoch !== expected.epoch)
+        return blocked("stale-epoch");
+    const core = value.core;
+    if (value.retryInput || RUNTIME_CONTROL_CORE.some(method => !core.includes(method)))
+        return blocked("missing-core");
+    // Security: retain only allowlisted metadata, never arbitrary optional source data.
+    return { status: "compatible", contract: Object.freeze({
+            api: RUNTIME_CONTROL_API, generation: 1, releaseId: value.releaseId, scope: value.scope,
+            epoch: value.epoch, bootId: value.bootId, osSessionId: value.osSessionId,
+            core: Object.freeze([...value.core]), frameLimit: value.frameLimit, inputLimit: value.inputLimit,
+            retryInput: false,
+        }) };
+}
+/** A bounded read-only authenticated exchange; it never starts a host or substitutes a release. */
+export async function readRuntimeControl(options) {
+    const { expected, maintain = runTerminalHostMaintenance, ...maintenance } = options;
+    try {
+        const report = await maintain({ ...maintenance, action: "runtime-control" });
+        if (report.schema !== "a1-tabs-maintenance-v1" || report.exitCode !== 0
+            || report.host !== "running" || report.command !== "runtime-control")
+            return blocked("unavailable");
+        return assessRuntimeControl(report.result, expected);
+    }
+    catch {
+        return blocked("unavailable");
+    }
+}
+function blocked(reason) {
+    return { status: "blocked", reason };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function positiveInteger(value, maximum = Number.MAX_SAFE_INTEGER) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0 && value <= maximum;
+}
+function boundedStrings(value) {
+    return Array.isArray(value) && value.length <= 64 && new Set(value).size === value.length
+        && value.every(entry => typeof entry === "string" && entry.length > 0 && entry.length <= 64);
+}
+function identityValid(value) {
+    const record = value;
+    return typeof record.releaseId === "string" && /^[a-f0-9]{64}$/u.test(record.releaseId)
+        && typeof record.scope === "string" && /^[a-f0-9]{20}$/u.test(record.scope)
+        && positiveInteger(record.epoch)
+        && [record.bootId, record.osSessionId].every(entry => typeof entry === "string" && entry.length > 0
+            && entry.length <= 256 && !/[\x00-\x1f\x7f]/u.test(entry));
+}

package/dist/integrations/pi/engine/adapter.js

@@ -211,6 +211,11 @@ export class PiEngineAdapter {
     #announceReleaseUpdate(release) {
         if (this.#disposed)
             return;
+        if (release.status === "client-connected") {
+            if (this.#state.diagnosticsState.acknowledgeClientVersion(release.version))
+                this.#emitView();
+            return;
+        }
         if (release.status === "installed") {
             this.#addDiagnostic("info", "release-update-installed", `Update ${release.version} installed; restart to update.`, true);
         }
@@ -510,7 +515,7 @@ export class PiEngineAdapter {
             this.#engine.resume();
     }
     #recordDiagnostic(severity, code, message, recoverable) {
-        return this.#state.recordDiagnostic(severity, code, message, recoverable);
+        return this.#state.diagnosticsState.record(severity, code, message, recoverable);
     }
 }
 export async function createPiEngineAdapter(options) {

package/dist/integrations/pi/engine/diagnostics-state.d.ts

@@ -0,0 +1,9 @@
+import type { OwnedUiDiagnostics } from "../../../contracts/owned-ui/index.js";
+/** Bounded structured notices; acknowledgements never inspect terminal cells or touch Agent work. */
+export declare class EngineDiagnostics {
+    #private;
+    get values(): readonly OwnedUiDiagnostics[];
+    get messages(): readonly string[];
+    record(severity: OwnedUiDiagnostics["severity"], code: string, message: string, recoverable: boolean): OwnedUiDiagnostics;
+    acknowledgeClientVersion(version: string): boolean;
+}

package/dist/integrations/pi/engine/diagnostics-state.js

@@ -0,0 +1,34 @@
+import { gte, valid as validSemver } from "semver";
+/** Bounded structured notices; acknowledgements never inspect terminal cells or touch Agent work. */
+export class EngineDiagnostics {
+    #values = [];
+    #messages = [];
+    #sequence = 0;
+    get values() { return this.#values; }
+    get messages() { return this.#messages; }
+    record(severity, code, message, recoverable) {
+        const diagnostic = { sequence: this.#sequence++, code, severity, message, recoverable };
+        this.#values.push(diagnostic);
+        if (this.#values.length > 100)
+            this.#values.shift();
+        this.#messages = [...this.#messages, message].slice(-8);
+        return diagnostic;
+    }
+    acknowledgeClientVersion(version) {
+        if (validSemver(version) === null)
+            return false;
+        const removed = new Set();
+        for (let index = this.#values.length - 1; index >= 0; index--) {
+            const diagnostic = this.#values[index];
+            const installed = diagnostic.code === "release-update-installed" ? /^Update (\S+) installed; restart to update\.$/u.exec(diagnostic.message)?.[1] : undefined;
+            if (installed !== undefined && validSemver(installed) !== null && gte(version, installed)) {
+                removed.add(diagnostic.message);
+                this.#values.splice(index, 1);
+            }
+        }
+        if (removed.size === 0)
+            return false;
+        this.#messages = this.#messages.filter(message => !removed.has(message) || this.#values.some(diagnostic => diagnostic.message === message));
+        return true;
+    }
+}

package/dist/integrations/pi/engine/view-state.d.ts

@@ -1,3 +1,4 @@
+import { EngineDiagnostics } from "./diagnostics-state.js";
 import type { OwnedUiDiagnostics, OwnedUiEditorState, OwnedUiModelInfo, OwnedUiSessionViewModel, OwnedUiStatusView, OwnedUiTerminalSurface, OwnedUiThinkingLevel, OwnedUiUsageView } from "../../../contracts/owned-ui/index.js";
 /**
  * The engine adapter's own view-model state: lifecycle, editor, status, terminal surface, active
@@ -10,6 +11,7 @@ export declare class EngineViewState {
     lifecycle: OwnedUiSessionViewModel["lifecycle"];
     activeModel: OwnedUiModelInfo | null;
     thinkingLevel: OwnedUiThinkingLevel;
+    readonly diagnosticsState: EngineDiagnostics;
     get revision(): number;
     get editor(): OwnedUiEditorState;
     get status(): OwnedUiStatusView;
@@ -38,5 +40,4 @@ export declare class EngineViewState {
     replaceSession(): void;
     /** Delivery overload ended the run: ready when it can resume, stopped once disposed, otherwise failed. */
     settleOverload(canResume: boolean, disposed: boolean): void;
-    recordDiagnostic(severity: OwnedUiDiagnostics["severity"], code: string, message: string, recoverable: boolean): OwnedUiDiagnostics;
 }

package/dist/integrations/pi/engine/view-state.js

@@ -1,11 +1,10 @@
+import { EngineDiagnostics } from "./diagnostics-state.js";
 const DEFAULT_SURFACE = {
     columns: 100,
     rows: 32,
     focusedRegion: "editor",
     hardwareCursor: false,
 };
-const MAX_DIAGNOSTICS = 100;
-const MAX_STATUS_DIAGNOSTICS = 8;
 /**
  * The engine adapter's own view-model state: lifecycle, editor, status, terminal surface, active
  * model, thinking level, the usage cache, diagnostics, and the view revision. Every change that
@@ -33,12 +32,12 @@ export class EngineViewState {
     activeModel = null;
     thinkingLevel = "medium";
     #usage;
-    #diagnostics = [];
+    diagnosticsState = new EngineDiagnostics();
     get revision() { return this.#revision; }
     get editor() { return this.#editor; }
-    get status() { return this.#status; }
+    get status() { return { ...this.#status, diagnostics: this.diagnosticsState.messages }; }
     get terminal() { return this.#terminal; }
-    get diagnostics() { return this.#diagnostics; }
+    get diagnostics() { return this.diagnosticsState.values; }
     /** Any emitted event advances the revision. */
     advance() {
         this.#revision += 1;
@@ -112,15 +111,4 @@ export class EngineViewState {
         this.#editor = { ...this.#editor, submitEnabled: canResume && !disposed };
         this.#revision += 1;
     }
-    recordDiagnostic(severity, code, message, recoverable) {
-        const diagnostic = { sequence: this.#diagnostics.length, code, severity, message, recoverable };
-        this.#diagnostics.push(diagnostic);
-        if (this.#diagnostics.length > MAX_DIAGNOSTICS)
-            this.#diagnostics.shift();
-        this.#status = {
-            ...this.#status,
-            diagnostics: [...this.#status.diagnostics, message].slice(-MAX_STATUS_DIAGNOSTICS),
-        };
-        return diagnostic;
-    }
 }

package/dist/native/darwin-arm64/manifest.json

@@ -7,7 +7,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-10-31T18:04:55.424Z",
+  "builtAt": "2026-11-03T07:34:59.833Z",
   "artifact": {
     "filename": "process-guardian.node",
     "sha256": "a87eaaffcd986b624c8b044b756446cc1bdaf4334a1775b97820542fe34f9fb7",

package/dist/native/darwin-arm64/terminal-host.manifest.json

@@ -9,11 +9,11 @@
   "architecture": "arm64",
   "target": "aarch64-apple-darwin",
   "capability": "supported",
-  "builtAt": "2026-10-31T18:08:37.997Z",
+  "builtAt": "2026-11-03T07:38:20.584Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "4e35835f3af4c0d9ae9582886f3a1f66d8a8bd306014d24af29e979ca504aed6",
-    "size": 6019520
+    "sha256": "61ed28a1cb8a7e65c8b963a672917864b607f12b418468700e214663b9506b61",
+    "size": 6566864
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

package/dist/native/darwin-x64/manifest.json

@@ -7,7 +7,7 @@
   "platform": "darwin",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-31T18:05:02.327Z",
+  "builtAt": "2026-11-03T07:35:06.034Z",
   "artifact": {
     "filename": "process-guardian.node",
     "sha256": "783a65f0de287a1c02cd5429dbe97bc8633f4cc8a7b92e3e961180b9bdcff814",

package/dist/native/darwin-x64/terminal-host.manifest.json

@@ -9,11 +9,11 @@
   "architecture": "x64",
   "target": "x86_64-apple-darwin",
   "capability": "supported",
-  "builtAt": "2026-10-31T18:11:47.607Z",
+  "builtAt": "2026-11-03T07:41:31.478Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "7161d3bde5cf9d1caf2978fe623b6d26dbdc257093a48b2870d510804563a1b3",
-    "size": 6566416
+    "sha256": "4e257b645cda56dce14b3c442b673da98049ec91fa7d8c7cd7d265ddd61d9c5b",
+    "size": 7159480
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

package/dist/native/linux-x64/manifest.json

@@ -7,7 +7,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-31T18:04:50.100Z",
+  "builtAt": "2026-11-03T07:34:54.153Z",
   "artifact": {
     "filename": "process-guardian.node",
     "sha256": "118e5954e3864672bd8482ab7edf419cb27dcdf2533720316979b7f5cc5a53a5",

package/dist/native/linux-x64/terminal-host.manifest.json

@@ -9,11 +9,11 @@
   "architecture": "x64",
   "target": "x86_64-unknown-linux-gnu",
   "capability": "supported",
-  "builtAt": "2026-10-31T18:08:05.383Z",
+  "builtAt": "2026-11-03T07:37:37.426Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "41212856c811ddef6e918e96b49dc957b2d49946d7ef5494962db8d70937d760",
-    "size": 7306168
+    "sha256": "913e106efd96c5d59b33cdeea2261873a1e4a1bb73b3e94fbb847c6af5f941ba",
+    "size": 7936048
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

package/dist/native/win32-x64/manifest.json

@@ -7,10 +7,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-31T18:05:42.004Z",
+  "builtAt": "2026-11-03T07:35:37.945Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "e67e64206f795842ae72fd9ef77437165a0a7a8892c0256b51658f19aee4375e",
+    "sha256": "f1906525fc8654e10b859c6ec679548c48f6f136441afac37a13a596cfcbaf35",
     "size": 402432
   },
   "provenance": {

package/dist/native/win32-x64/terminal-host.manifest.json

@@ -9,11 +9,11 @@
   "architecture": "x64",
   "target": "x86_64-pc-windows-msvc",
   "capability": "supported",
-  "builtAt": "2026-10-31T18:08:25.857Z",
+  "builtAt": "2026-11-03T07:38:31.534Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "e22f344176b06f44427a2855d21b271a0d2a780aa89003cd90948d9bbcb6b9a3",
-    "size": 6397440
+    "sha256": "516d1cf1cfd627ce7f2594c67766ee1db644cf7952bb9a6522ab48417f6a91d0",
+    "size": 7048192
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

package/docs/architecture/native-fixture-isolation.md

@@ -0,0 +1,23 @@
+# Native fixture validation
+
+## Normal automatic CI
+
+Development, Full regression and publication run native builds and fixtures directly on their normal GitHub-hosted runners. The agent-added sandbox, restricted OS accounts, network provisioning, fixture receipts, feature/runtime permission checks and additional security gates have been removed.
+
+The existing required suites remain required: terminal-host partitions, release isolation, resident chaos, exact-package published-predecessor continuity, terminal fidelity/latency certificates and bounded decoder fuzzing. Their platform coverage and product assertions are unchanged. Production publication protection is unchanged.
+
+When implementation outcomes are complete, trusted readiness/finalization publishes the exact candidate head and normal PR validation starts automatically. A repair push triggers the same flow for its new head. No fixture approval, deployment review, manual dispatch or workflow restart is required. Failed, missing or cancelled required results block integration; the maintainer chooses when to merge after required checks pass.
+
+## Optional local checks
+
+`npm run check:local` runs typechecking, architecture/identity/naming checks and non-native workflow regression tests. It does not build native artifacts or launch application/fixture processes. It is a convenience command, not an execution permission system or a prerequisite for CI advancement.
+
+The previous Defender report is unresolved historical evidence, not a passing security verdict. This workflow rollback changes no workstation protection setting or quarantined file.
+
+## macOS custody
+
+The macOS predecessor custody repair remains independent of CI provisioning. `getaudit_addr` supplies kernel audit user/session IDs; `audit_session_self()` returns only a process-local Mach port name.
+
+For immutable predecessors using the older metadata, the explicit source route still requires unchanged boot, exact native PID/start identity, source credentials/epoch and a connected kernel `LOCAL_PEERTOKEN` matching PID, real/effective UID and current audit user/session. Incomparable metadata is retained, not treated as proof of login equality or termination. Generic cross-release admission is unchanged.
+
+Static/workflow tests are not native platform execution evidence. Required exact-head native results remain the CI authority.

package/docs/architecture/resident-tabs.md

@@ -175,7 +175,7 @@ Transport correctness does not rely on `timeBeginPeriod`. The existing per-role
 
 The existing opt-in progress route (`A1_RESIDENT_PROGRESS_OBSERVATION_DIR` plus `A1_RESIDENT_PROGRESS_RUN_ID`) adds `pipe-frame-read`, `pipe-write-complete`, `outer-write-complete`, `wake-gap`, and `wake-repaint-requested` stages. Connection-level records may omit tab identity. `durationUs` is local monotonic completion/assembly time; `idleWaitUs` separately describes waiting for the next frame and is not delivery latency. Native records include `monotonicUs`, `clockEpoch`, and optional `clockDiscontinuity`. Consumers exclude negative, epoch-crossing, and clock-discontinuity-crossing derived samples, while retaining valid local completion durations. The queue remains bounded and asynchronous, with loss accounting and no terminal content or credentials. Outer-write completion is not proof of physical pixels.
 
-For recurring post-wake stalls, compare an existing resident client, a new client on the same resident host, and direct `a1 solo` in the same outer terminal. Use matched holder/attach revisions and local I/O durations to distinguish child progress, transport delay, and outer writes. If solo and other terminal applications also stall, do not assign the failure to resident pipes without further evidence. Simulated-gap fixtures do not certify physical sleep/wake recovery; do not automate workstation suspend. Updates retain old resident cohorts, but a new launch selects its own immutable release namespace rather than reusing their host. Existing roles keep their original code and lifecycle; installing an update never recycles running tabs.
+For recurring post-wake stalls, compare an existing resident client, a new client on the same resident host, and direct `a1 solo` in the same outer terminal. Use matched holder/attach revisions and local I/O durations to distinguish child progress, transport delay, and outer writes. If solo and other terminal applications also stall, do not assign the failure to resident pipes without further evidence. Simulated-gap fixtures do not certify physical sleep/wake recovery; do not automate workstation suspend. Updates retain old resident cohorts. A new client aggregates verified source routes while new execution uses its selected immutable release. Existing roles keep their original code and lifecycle; installing an update never recycles running tabs.
 
 ### 3. Host scope, endpoints, writer authority, and credentials
 
@@ -326,11 +326,27 @@ Tab status is an A1-owned state machine fed by `bridge.status`:
 ### 10. Updates and version skew
 
 - **Artifacts and process images.** The server and holders are Node runtimes that load the addon and fixed entry from immutable release directories, never from the mutable npm prefix. Activation therefore never overwrites a loaded addon or entry, and release retention keeps every release used by a verified resident process.
-- **Exact release admission.** Clients, holders and bridges present a release identity before capability negotiation. Matching protocol generation or display version does not permit cross-release attachment. Native clients also check the welcome identity; bridge identity is consumed from holder-private launch context before extensions load.
-- **Independent activation.** A newer release starts or reuses its own host. Existing resident and solo processes remain untouched. Server recovery and child launches retain the originating fixed Node, entry and addon; the active-release pointer never retargets them. No automatic migration, handoff or idle recycling is performed.
+- **Exact release admission.** Ordinary attach clients, holders and bridges present their originating release identity before capability negotiation. Matching protocol generation or display version does not permit implicit cross-release attachment. The explicit `SourceRoute` adapter selects and verifies one source namespace, native owner and epoch before authenticating client control to that source; it never adopts foreign holders or rewrites execution custody. Native clients also check the welcome identity; bridge identity is consumed from holder-private launch context before extensions load.
+- **Independent activation.** A newer client starts or reuses its own execution source for new tabs, then reconnects the same profile workspace through compatible explicit source routes. Readiness and active-reference publication require repeated verified source-contract inspection; incompatibility keeps an eligible verified prior client selected. Existing resident and solo processes remain untouched. Source recovery and child launches retain the originating fixed Node, entry and addon; the active-release pointer never retargets them. No automatic migration, execution handoff or idle recycling is performed.
 - **Retention.** Read-only bounded collection scans every flat release namespace and legacy profile namespace. It keeps server, holder and child releases while identities verify and retains all candidates on unreadable, linked, oversized or unverifiable state. Package activation never overwrites loaded artifacts.
 - **Maintenance and legacy state.** Maintenance resolves the invoking package's immutable materialization without activation or host startup, uses only that release's verified entry, and never retries another recorded cohort. List, stop, status and doctor remain release-local, including unresponsive-host termination. Legacy unversioned state is neither migrated nor adopted; it is read only for conservative retention. Shared configuration and session file locks remain profile-neutral.
 
+#### Stable runtime control and profile workspace
+
+The `resident-control-v1` descriptor is available through authenticated native `runtime.describe` maintenance. It binds the mandatory attach/list/view/input/resize/detach/controller-boundary semantics to an exact source release, profile scope, epoch and boot/login identity. It explicitly forbids automatic input retry after uncertain delivery. Native MessagePack fixtures and the TypeScript consumer pin the same bytes; unknown optional metadata is not retained. This descriptor alone is not proof that every live Agent can be controlled and is not an activation verdict.
+
+`SourceRoute` verifies canonical profile/source scope, bounded owner-private records, native owner/start identity, boot/login, credentials and the authenticated epoch. Inspection starts no source and loads no source code. The explicit attach adapter permits client control through the source's existing controller barriers, without acquiring holder or session-writer custody. Generic same-release refusal and release-local maintenance remain unchanged. Supported published generation-1 predecessors use their proven mandatory features and neutral private launch contract; sources advertising `resident-control-v1` must satisfy its exact binding and non-replay semantics. Unsupported declared versions fail closed.
+
+`WorkspaceStore` lives at `<data>/resident-workspaces/<canonical-profile-token>/`. Its kernel writer lease, independent monotonic epoch counter, atomic primary/previous generations and bounded corruption preservation prevent stale writers and empty reinitialization over known state. It stores source-qualified logical tab identities, names, order, selection and custody metadata, not credentials, environment, prompts, drafts or terminal bytes. Only a positively authenticated complete source snapshot may remove that source's entries; discovery absence cannot remove another source. A positively ended boot/login archives bounded topology history rather than restoring Agents.
+
+Ordinary resident launch uses the native workspace proxy. Its connection, routing, view-admission and persistence modules aggregate source lists/statuses and retained surfaces; new Agent and singleton creation uses the selected release. Input, paste, pointer/focus, resize, dialogs and explicit lifecycle requests go to the authenticated live owner. Drafts, attachments, queued work, session configuration and interaction state stay in the original child, not a client-side reconstruction. Selection commits durably before the exact source/tab/view generation can release bounded queued input. Superseded or failed views reject that input. Reconnection restores observation/resize only and repeats view admission; it never retries input or lifecycle mutations. Source status inspection and durable index writes run in workers, not the live control loop.
+
+Coordinator/client loss retains source execution and uses the originating source's existing recovery path. Current and previous workspace generations retain source artifacts until positive closure; missing artifacts are not closure. Release/dependency retention also covers recent private recovery custody using bounded metadata only, without reading, exporting or deleting draft/journal contents. Unknown custody retains candidates. Explicit host shutdown remains execution-only rather than being blocked by recovery files.
+
+Optional authenticated client-build metadata is advisory, not execution identity or controller authority. Modern retained children acknowledge installed update notices already satisfied by that connected client while preserving copy feedback and Notify/No behavior. An immutable predecessor unable to acknowledge that metadata gets a client-owned notice explaining that retained Agent UI notices do not require restarting Agents. Existing engine code remains its original version.
+
+Real published-predecessor tests are included in exact-package CI on Windows x64, Linux x64 and macOS arm64. The focused Windows run exercises live model/tool work, queued input, retained draft/selection, hard client death and originating-coordinator recovery with unchanged Agent/holder/tool identities and no replay or deferred idle restart. Local evidence is not certification of unrun platforms or of the exact packed CI candidate.
+
 ### 11. Foreground UX
 
 - **Strip.** Row 0, drawn by the attach client, reproduces the approved v2 default appearance:
@@ -376,13 +392,16 @@ Tab status is an A1-owned state machine fed by `bridge.status`:
 - **Changelog.** The changelog opens as a singleton `changelog-` tab titled `Changelog`, from the palette or the unbound `tabs.changelog` action. The tab registry accepts the `agent`, `settings`, and `changelog` kinds. Its provider registration makes it non-renameable, Close-only, sessionless, prewarmed, and hidden: the attach client starts it with `tab.prewarm-changelog` once Settings is ready, and again after a Changelog tab closes, so opening it shows the running tab at once. Like a hidden Settings tab, a hidden Changelog never takes the view when the viewed tab closes, so closing the last Agent shows the landing. Its screen is the tab: it shows no `Esc close` hint, and neither `Esc` nor one `Ctrl+C` closes it.
 - **Tab-bar provider.** Agent, Settings, and Changelog are registered once in the I/O-free `TabKind` provider shared by the attach client and server. Each registration declares its label, shortcut action, multiplicity, create-or-toggle activation, prewarm policy, renameability, Agent-session ownership, child route, and launcher marker. Shortcuts, the command palette, `+`, popup capabilities, registry validation, session handling, and route delivery consume that provider instead of rebuilding Agent or utility tables. Multi-instance Agent activation creates a tab; singleton-toggle activation creates or reveals its one tab, selects it in place when already shown, and hides it while viewed according to the common toggle rule. Singleton visibility and prewarm state are arrays in provider order, so adding another singleton does not add a concrete view field.
   - The tab bar also owns one kind-neutral ordering API: every newly created tab and every hidden tab newly joining the strip appends after all live tabs; selecting an already shown tab retains its slot; drag order remains authoritative; and stopped registry records never affect the visible insertion destination. Cold holder creation, standby promotion, and singleton reveal use these same operations, so `Agent`, then `Settings`, then another `Agent` stays in that order.
+  - The workspace proxy reserves creation positions before source IDs arrive, restores caller request identities, and prevents old prewarm responses from taking an explicit open. It publishes final topology before requesting the first selected source surface, including when a prewarmed utility ID already exists in an older client position. Durable acknowledgements update custody without replacing newer user order. Hidden foreign singleton records never produce duplicate Settings/Changelog chips or consume published reorder indexes, and unchanged list replies do not invent new topology revisions.
+  - Normal lifecycle reconciliation is quiet: known-closed identities absorb duplicate Close, stale references refresh topology rather than become input errors, and superseded or closed views cancel without banners. Source-side repeated Close does not repeat stop or persistence. Storage uses one coalesced latest-intent slot plus its in-flight operation, retains every affected source, and waits for other clients' writer leases only off the UI loop. Passive source recovery retains observation/resize intent but never queued input. See the delivery's tab-notification audit for producer coverage.
+  - Utility toggles hide and reuse their process even when the final visible utility leaves the strip; the landing replaces it. Explicit Close still removes the instance. Source/tab/generation fencing and one complete synchronized presentation commit exclude stale bodies and intermediate selection jumps. The full-coverage host landing repaints in place rather than clearing the strip between utility transitions.
   - `bin/ui.js` resolves the utility route from the consumed tab id before loading the declared Agent startup graph. A utility id imports the slim composition instead, so no Pi engine host, Agent session, extensions, prompt history, suggestions, or draft recovery are loaded or started; Agent tabs, the standby, `a1 solo`, and `a1 pi` keep the full graph.
   - The slim process still owns one fullscreen `OwnedUiTerminalHost`, the background canvas, theme and accent singletons, Pi keybindings, controller-boundary input, and the tab bridge. A minimal presenter opens only the pinned route. It publishes effective tab shortcuts, requests the attach client's Plus Menu through `configure-plus`, requests tab close when the screen closes, detaches the controlling client on the interrupt exit, and ends on `bridge.stop`.
   - Settings builds its Agent section from Pi's persisted `SettingsManager` after the ordinary project-trust decision, with persist-only bindings because each Agent process owns live effects. Its per-model thinking choices come from an offline `ModelRuntime` over the profile's `auth.json` and `models.json`. Changelog reads the packaged release-note catalog directly and never takes or acknowledges an Agent startup "What's New" claim.
 - **Reveal.** Opening a tab draws it at once: a created Agent and a revealed Settings or Changelog tab both keep the current content, another tab or the landing, until their first nonblank drawn frame commits, a retained blank surface included. Blank child revisions remain parked for any duration rather than exposing an empty body or child cursor; explicit failure and recovery outcomes still replace the startup presentation. Every changed-size resize forwards geometry immediately and repaints the retained strip and child surface directly at the new dimensions; no resize curtain or fade remains. Inactive terminal-tab resizes also repaint without an overlay, and focus return refreshes the complete frame. A starting chip shows no spinner. One tab opens at a time: new-Agent input while a tab the client asked for is starting or not yet shown starts nothing.
 - **Rename selection.** The inline rename draws a selection on the prompt editor's selection background (RGB `38,79,120`, palette `24`) and keeps the chip's text color, restoring the chip's background after it; only the caret is a reversed cell.
 - **Close.** `Alt+W` and the right-click menu close a tab directly, including while it is working. Closing removes the chip without a confirmation, stopping/read-only frame, or close glyph, then gracefully stops the child under the existing bounded termination policy. Its session stays resumable. Closing the last tab leaves `+` and the clock beside the landing.
-- **Landing.** While the attach client has no tab to show, the attach role renders the a1 landing as the frame's body. The launch cwd sits where an Agent tab's footer shows it, flush left on the second-to-last body row with the same `~` formatting and `dim` color, so the folder does not move when a tab opens or closes; `v<version>`, read once from the release root's `package.json`, sits below it and the three-row half-block `a1` wordmark in the profile's accent above it (omitted in Apple Terminal). The accent colors are a native table pinned by `landing_accents.json`, which a TypeScript test checks against `derivePiAccentProjection`. The body is painted with the canvas `backgroundStyle` gives Agent tabs. The landing holds no input: tab shortcuts, the launcher, strip mouse, and double-`Ctrl+C` behave as with tabs, and no cursor shows. A hidden Settings tab is prewarmed and kept running beside the landing, as beside Agents, so Settings opens without a start; it closes when the client detaches, and an attach treats a registry holding only Settings as empty, so it starts and views its first Agent. An Agent record whose child exited and that no holder owns (an update shutdown, a crash, a kill) is treated the same way: `attach.start` drops those stopped records and starts a new Agent under a fresh `tab-` id so it never adopts a stopped tab's directory, draft, or recovery screen, while a profile that never had an Agent keeps `tab-1`; admission never pins a stopped record as the view, and it names the fresh id itself, which `attach.start` reads back from the client session, so the surface subscription admission takes and the tab it starts agree. On the client, a first registry list with nothing to show counts as the strip shown empty, so the landing with `+` and the clock paints at once instead of an empty screen, while a listed starting tab keeps its first-draw gate. Adding a tab from the landing keeps it until the tab's first drawn frame replaces it at once; the landing has no animation of its own.
+- **Landing.** While the attach client has no tab to show, the attach role renders the a1 landing as the frame's body. The launch cwd sits where an Agent tab's footer shows it, flush left on the second-to-last body row with the same `~` formatting and `dim` color, so the folder does not move when a tab opens or closes; `v<version>`, read once from the release root's `package.json`, sits below it and the three-row half-block `a1` wordmark in the profile's accent above it (omitted in Apple Terminal). The accent colors are a native table pinned by `landing_accents.json`, which a TypeScript test checks against `derivePiAccentProjection`. The body is painted with the canvas `backgroundStyle` gives Agent tabs. The landing holds no input: tab shortcuts, the launcher, strip mouse, and double-`Ctrl+C` behave as with tabs, and no cursor shows. A hidden Settings tab is prewarmed and kept running beside the landing, as beside Agents, so Settings opens without a start; it closes when the client detaches. Plain workspace launch treats a roster holding only utilities as empty and shows the landing without creating an Agent; new execution requires an explicit Agent or session-open action. An Agent record whose child exited and that no holder owns is not a live Agent for plain launch: remain on the landing rather than replacing its execution. Explicit creation uses a fresh identity and never adopts a stopped tab's directory, draft or recovery screen. A retained live workspace is selected from the complete authenticated roster before admission; its selected source/tab/generation is explicitly observed before the first nonempty frame, so no landing is painted while those Agents reconnect. On the client, a first registry list with nothing to show counts as the strip shown empty, so the landing with `+` and the clock paints at once instead of an empty screen, while a listed starting tab keeps its first-draw gate. Adding a tab from the landing keeps it until the tab's first drawn frame replaces it at once; the landing has no animation of its own.
 - **Detach.**
   - `Ctrl+C` twice detaches from any tab and is handled by the attach client, so it works even when the bridge is down. Inside an A1 tab, `/quit` and empty-editor `Ctrl+D` send a detach request carrying the immutable command-origin controller identity and revision; stale, ambiguous or unavailable attribution keeps the tab running and directs the user to `Ctrl+C` twice.
   - The client restores the terminal. When agents are still running, it prints `1 agent still running run a1 to return.` or `N agents still running run a1 to return.`; otherwise it prints the resume hint.