@timurproko/a1 0.1.1-dev.5 → 0.1.1-dev.7

package/dist/src/foundation/ui-components/surface.d.ts

@@ -0,0 +1,20 @@
+import { type ScrollbarGeometry } from "./scrollbar.js";
+import type { UiTheme } from "./theme.js";
+/**
+ * The chrome around a list: the rail down its right edge, and what it shows when
+ * there is nothing to list. Both are the same on any screen, so neither is a
+ * screen's to draw.
+ */
+/** Columns the rail occupies: its own, plus the gap before it. */
+export declare const RAIL_COLUMNS = 2;
+export interface RailOptions {
+    /** Rows at the top the rail does not run beside, such as a sticky header. */
+    readonly topInset?: number;
+}
+/** Draws the rail beside each row, padding the rows to a common width first. */
+export declare function withScrollbarRail(lines: readonly string[], geometry: ScrollbarGeometry | null, contentWidth: number, theme: UiTheme, options?: RailOptions): readonly string[];
+/**
+ * What a list shows instead of rows: a mark and a line, both quiet, sitting in
+ * the middle of the space the rows would have had.
+ */
+export declare function renderEmptyState(message: string, mark: string, height: number, width: number, theme: UiTheme): readonly string[];

package/dist/src/foundation/ui-components/surface.js

@@ -0,0 +1,38 @@
+import { isThumbRow } from "./scrollbar.js";
+import { displayWidth } from "./text.js";
+/**
+ * The chrome around a list: the rail down its right edge, and what it shows when
+ * there is nothing to list. Both are the same on any screen, so neither is a
+ * screen's to draw.
+ */
+/** Columns the rail occupies: its own, plus the gap before it. */
+export const RAIL_COLUMNS = 2;
+/** Draws the rail beside each row, padding the rows to a common width first. */
+export function withScrollbarRail(lines, geometry, contentWidth, theme, options = {}) {
+    const inset = options.topInset ?? 0;
+    return lines.map((line, offset) => {
+        const cell = offset < inset || geometry === null
+            ? " "
+            : isThumbRow(geometry, offset - inset) ? theme.fg("accent", "│") : theme.fg("dim", "│");
+        return `${pad(line, contentWidth)} ${cell}`;
+    });
+}
+/**
+ * What a list shows instead of rows: a mark and a line, both quiet, sitting in
+ * the middle of the space the rows would have had.
+ */
+export function renderEmptyState(message, mark, height, width, theme) {
+    const middle = Math.floor(height / 2);
+    return Array.from({ length: Math.max(0, height) }, (_line, index) => {
+        if (index === middle - 1)
+            return centre(theme.fg("muted", mark), mark, width);
+        return index === middle ? centre(theme.fg("muted", message), message, width) : "";
+    });
+}
+function centre(painted, raw, width) {
+    return `${" ".repeat(Math.max(0, Math.floor((width - displayWidth(raw)) / 2)))}${painted}`;
+}
+function pad(line, width) {
+    const visible = displayWidth(line);
+    return visible >= width ? line : line + " ".repeat(width - visible);
+}

package/dist/src/foundation/ui-components/text.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Display-width text handling. Terminals lay out by column, not by code unit,
+ * so measuring with `String.length` mis-sizes CJK, emoji, and combining marks,
+ * and counting styling escapes as visible width breaks every layout that uses
+ * colour.
+ */
+/** Removes styling sequences so only visible characters remain. */
+export declare function stripAnsi(text: string): string;
+/** Columns this text occupies once styling is removed. */
+export declare function displayWidth(text: string): number;
+/**
+ * Truncates to a column budget without splitting a grapheme. Styling sequences
+ * are carried through and a reset is appended when any style was opened, so a
+ * truncated row cannot leak colour into the rest of the line.
+ */
+export declare function truncateToWidth(text: string, maxWidth: number): string;
+/** Pads to an exact column count, truncating when the text is already wider. */
+export declare function padToWidth(text: string, width: number): string;
+/**
+ * A control that is present but cannot be used: the terminal own faint
+ * attribute over whatever colour it already carries, so it reads as half of what
+ * it would otherwise be in any theme.
+ */
+export declare function faint(text: string): string;

package/dist/src/foundation/ui-components/text.js

@@ -0,0 +1,123 @@
+/**
+ * Display-width text handling. Terminals lay out by column, not by code unit,
+ * so measuring with `String.length` mis-sizes CJK, emoji, and combining marks,
+ * and counting styling escapes as visible width breaks every layout that uses
+ * colour.
+ */
+const ANSI_PATTERN = /\[[0-9;:?]*[ -/]*[@-~]|\][^]*(?:|\\)|[@-Z\\-_]/g;
+const SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/** Removes styling sequences so only visible characters remain. */
+export function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, "");
+}
+function codePointWidth(codePoint) {
+    // Zero-width: combining marks, joiners, variation selectors, and format characters.
+    if (codePoint === 0x200d || codePoint === 0xfeff)
+        return 0;
+    if (codePoint >= 0x0300 && codePoint <= 0x036f)
+        return 0;
+    if (codePoint >= 0x200b && codePoint <= 0x200f)
+        return 0;
+    if (codePoint >= 0xfe00 && codePoint <= 0xfe0f)
+        return 0;
+    if (codePoint >= 0x20d0 && codePoint <= 0x20f0)
+        return 0;
+    if (codePoint >= 0x1ab0 && codePoint <= 0x1aff)
+        return 0;
+    if (codePoint >= 0x1dc0 && codePoint <= 0x1dff)
+        return 0;
+    if (codePoint >= 0xe0100 && codePoint <= 0xe01ef)
+        return 0;
+    // Wide: CJK, Hangul, fullwidth forms, and the emoji planes terminals render double-width.
+    if (codePoint >= 0x1100 && codePoint <= 0x115f)
+        return 2;
+    if (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f)
+        return 2;
+    if (codePoint >= 0xac00 && codePoint <= 0xd7a3)
+        return 2;
+    if (codePoint >= 0xf900 && codePoint <= 0xfaff)
+        return 2;
+    if (codePoint >= 0xfe30 && codePoint <= 0xfe6f)
+        return 2;
+    if (codePoint >= 0xff00 && codePoint <= 0xff60)
+        return 2;
+    if (codePoint >= 0xffe0 && codePoint <= 0xffe6)
+        return 2;
+    if (codePoint >= 0x1f300 && codePoint <= 0x1f64f)
+        return 2;
+    if (codePoint >= 0x1f900 && codePoint <= 0x1f9ff)
+        return 2;
+    if (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+        return 2;
+    // Control characters occupy nothing.
+    if (codePoint < 0x20 || (codePoint >= 0x7f && codePoint < 0xa0))
+        return 0;
+    return 1;
+}
+/** Width of one grapheme cluster: the widest code point it contains, marks excluded. */
+function graphemeWidth(grapheme) {
+    let width = 0;
+    for (const character of grapheme) {
+        width = Math.max(width, codePointWidth(character.codePointAt(0) ?? 0));
+    }
+    return width;
+}
+/** Columns this text occupies once styling is removed. */
+export function displayWidth(text) {
+    let width = 0;
+    for (const { segment } of SEGMENTER.segment(stripAnsi(text)))
+        width += graphemeWidth(segment);
+    return width;
+}
+/**
+ * Truncates to a column budget without splitting a grapheme. Styling sequences
+ * are carried through and a reset is appended when any style was opened, so a
+ * truncated row cannot leak colour into the rest of the line.
+ */
+export function truncateToWidth(text, maxWidth) {
+    if (maxWidth <= 0)
+        return "";
+    if (displayWidth(text) <= maxWidth)
+        return text;
+    let out = "";
+    let width = 0;
+    let styled = false;
+    let index = 0;
+    while (index < text.length) {
+        ANSI_PATTERN.lastIndex = index;
+        const match = ANSI_PATTERN.exec(text);
+        if (match && match.index === index) {
+            out += match[0];
+            styled = true;
+            index += match[0].length;
+            continue;
+        }
+        const nextEscape = match ? match.index : text.length;
+        for (const { segment } of SEGMENTER.segment(text.slice(index, nextEscape))) {
+            const segmentWidth = graphemeWidth(segment);
+            if (width + segmentWidth > maxWidth)
+                return styled ? `${out}` : out;
+            out += segment;
+            width += segmentWidth;
+        }
+        index = nextEscape;
+    }
+    return styled ? `${out}` : out;
+}
+/** Pads to an exact column count, truncating when the text is already wider. */
+export function padToWidth(text, width) {
+    if (width <= 0)
+        return "";
+    const current = displayWidth(text);
+    if (current > width)
+        return truncateToWidth(text, width);
+    return text + " ".repeat(width - current);
+}
+/**
+ * A control that is present but cannot be used: the terminal own faint
+ * attribute over whatever colour it already carries, so it reads as half of what
+ * it would otherwise be in any theme.
+ */
+export function faint(text) {
+    return `${text}`;
+}

package/dist/src/foundation/ui-components/theme.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Colour as a port, so a screen can be rendered and asserted without a terminal
+ * or a theme, and so the component layer never imports a Pi adapter.
+ */
+export type UiThemeToken = "accent" | "text" | "muted" | "dim" | "border" | "error";
+export interface UiTheme {
+    fg(token: UiThemeToken, text: string): string;
+    bold(text: string): string;
+    /** Inverted styling for the active row of a floating surface. */
+    highlight(text: string): string;
+    /** A control that is present but cannot act: quieter than quiet text. */
+    disabled(text: string): string;
+    /** Background for a floating surface, so it reads as above the content. */
+    panel(text: string): string;
+}
+/** Renders every token as plain text. What tests assert against. */
+export declare const PLAIN_THEME: UiTheme;

package/dist/src/foundation/ui-components/theme.js

@@ -0,0 +1,12 @@
+/**
+ * Colour as a port, so a screen can be rendered and asserted without a terminal
+ * or a theme, and so the component layer never imports a Pi adapter.
+ */
+/** Renders every token as plain text. What tests assert against. */
+export const PLAIN_THEME = Object.freeze({
+    fg: (_token, text) => text,
+    bold: (text) => text,
+    highlight: (text) => text,
+    disabled: (text) => text,
+    panel: (text) => text,
+});

package/dist/src/foundation/ui-components/value-menu.d.ts

@@ -0,0 +1,41 @@
+import type { UiTheme } from "./theme.js";
+/**
+ * The menu a value opens: anchored to the row it was opened from, marking what
+ * is in effect, highlighting nothing until something is picked, and flipping
+ * above its anchor only when it would otherwise run off the bottom.
+ */
+export interface ValueMenuState {
+    /** Values offered, as they should read. */
+    readonly choices: readonly string[];
+    /** The value in effect, marked rather than highlighted. */
+    readonly current: string | null;
+    /** The entry picked by a key or the pointer, or -1 while none is. */
+    readonly index: number;
+}
+export interface ValueMenuAnchor {
+    /** Row the menu was opened from, which it keeps even as the selection moves. */
+    readonly screenRow: number;
+    /** Column the values start at. */
+    readonly valueColumn: number;
+}
+/** Where a menu sits on screen, for reading a pointer against it. */
+export interface ValueMenuFrame {
+    readonly top: number;
+    readonly column: number;
+    readonly width: number;
+    readonly rows: number;
+}
+export interface ValueMenuLayout {
+    /** Rows available above the footer. */
+    readonly bodyHeight: number;
+    /** Full surface width, so the menu stays inside it. */
+    readonly surfaceWidth: number;
+    /** Columns reserved at the right edge, such as a scrollbar rail. */
+    readonly reservedRight: number;
+}
+/** Where the menu is placed: below its anchor where there is room, else above. */
+export declare function valueMenuFrame(state: ValueMenuState, anchor: ValueMenuAnchor, layout: ValueMenuLayout): ValueMenuFrame;
+/** Draws the menu over the rows behind it, leaving them otherwise untouched. */
+export declare function renderValueMenu(lines: readonly string[], state: ValueMenuState, frame: ValueMenuFrame, theme: UiTheme): readonly string[];
+/** Whether a pointer report lands inside the menu rather than behind it. */
+export declare function menuRowAt(frame: ValueMenuFrame, row: number, column: number): number | null;

package/dist/src/foundation/ui-components/value-menu.js

@@ -0,0 +1,33 @@
+import { overlaySpan } from "./spans.js";
+import { displayWidth, padToWidth } from "./text.js";
+/** Where the menu is placed: below its anchor where there is room, else above. */
+export function valueMenuFrame(state, anchor, layout) {
+    const below = anchor.screenRow + 1;
+    const top = below + state.choices.length <= layout.bodyHeight
+        ? below
+        : Math.max(0, anchor.screenRow - state.choices.length);
+    const width = Math.max(...state.choices.map(choice => displayWidth(choice) + 4), 6);
+    const column = Math.min(anchor.valueColumn, Math.max(0, layout.surfaceWidth - width - layout.reservedRight));
+    return { top, column, width, rows: state.choices.length };
+}
+/** Draws the menu over the rows behind it, leaving them otherwise untouched. */
+export function renderValueMenu(lines, state, frame, theme) {
+    const output = [...lines];
+    state.choices.forEach((choice, index) => {
+        const target = frame.top + index;
+        if (target < 0 || target >= output.length)
+            return;
+        const mark = choice === state.current ? "✓ " : "  ";
+        const text = padToWidth(`${mark}${choice} `, frame.width);
+        const painted = index === state.index ? theme.highlight(text) : theme.panel(text);
+        output[target] = overlaySpan(output[target] ?? "", frame.column, frame.column + frame.width, painted);
+    });
+    return output;
+}
+/** Whether a pointer report lands inside the menu rather than behind it. */
+export function menuRowAt(frame, row, column) {
+    const at = row - frame.top;
+    if (at < 0 || at >= frame.rows)
+        return null;
+    return column > frame.column && column <= frame.column + frame.width ? at : null;
+}

package/dist/src/product-identity.d.ts

@@ -1,11 +1,11 @@
-declare const ENVIRONMENT_KEYS: readonly ["certificationTarball", "configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint", "fixture", "fixtureInput", "fixtureToken", "inputAcknowledgement", "internalPackaging", "launchArgumentsJson", "launchProfile", "nativePi", "paneId", "piParityIntentionalMutation", "piPortRoot", "piSourceLedgerPath", "piSourceScanRoot", "probeTrace", "profileHome", "protocolVersion", "releaseDigest", "releaseId", "releaseRoot", "releaseRunnerLabel", "runtimeDir", "structuredFlowLimits", "terminalArgumentsJson", "terminalExecutable", "terminalSessionId"];
+declare const ENVIRONMENT_KEYS: readonly ["certificationTarball", "configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint", "fixture", "fixtureInput", "fixtureToken", "inputAcknowledgement", "internalPackaging", "launchArgumentsJson", "launchProfile", "nativePi", "paneId", "piParityIntentionalMutation", "piPortRoot", "piSourceLedgerPath", "piSourceScanRoot", "probeTrace", "processGuardianPath", "profileHome", "protocolVersion", "releaseDigest", "releaseId", "releaseRoot", "releaseRunnerLabel", "runtimeDir", "structuredFlowLimits", "terminalArgumentsJson", "terminalExecutable", "terminalSessionId"];
 declare const FILESYSTEM_KEYS: readonly ["slug", "windowsDirectory", "unixDirectory", "temporaryPrefix"];
 declare const STATE_KEYS: readonly ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile", "piSandboxProfile"];
 declare const ENDPOINT_KEYS: readonly ["windowsPipeStem", "unixSocketFilename", "metadataFilename", "supervisorLogFilename", "databaseFilename"];
 declare const MANIFEST_KEYS: readonly ["releaseFilename", "packageFilename"];
 declare const PROTOCOL_KEYS: readonly ["namespace", "controlEnvelope", "supervisorSchema", "nativeHostSchema", "structuredAgentSchema", "controlStoreSchema", "releaseCohortSchema", "updateJournalSchema"];
 declare const EVIDENCE_KEYS: readonly ["nativeSpikeSchema", "terminalProvenanceSchema", "terminalProofSchema", "stableReleaseSchema", "previewReleaseSchema", "releaseCertificationSchema", "previewPlatformVerdictSchema", "piSourceLedgerSchema", "piComponentParitySchema", "piEventFrameParitySchema"];
-declare const ARTIFACT_KEYS: readonly ["cliEntry", "supervisorEntry", "uiEntry", "nativeExecutable", "nativeCrate", "releaseTarballStem", "diagnosticStem"];
+declare const ARTIFACT_KEYS: readonly ["cliEntry", "supervisorEntry", "guardianEntry", "uiEntry", "nativeExecutable", "nativeCrate", "processGuardianExecutable", "releaseTarballStem", "diagnosticStem"];
 type StringRecord<Keys extends readonly string[]> = {
     readonly [Key in Keys[number]]: string;
 };

package/dist/src/product-identity.js

@@ -21,6 +21,7 @@ const ENVIRONMENT_KEYS = [
     "piSourceLedgerPath",
     "piSourceScanRoot",
     "probeTrace",
+    "processGuardianPath",
     "profileHome",
     "protocolVersion",
     "releaseDigest",
@@ -39,7 +40,7 @@ const ENDPOINT_KEYS = ["windowsPipeStem", "unixSocketFilename", "metadataFilenam
 const MANIFEST_KEYS = ["releaseFilename", "packageFilename"];
 const PROTOCOL_KEYS = ["namespace", "controlEnvelope", "supervisorSchema", "nativeHostSchema", "structuredAgentSchema", "controlStoreSchema", "releaseCohortSchema", "updateJournalSchema"];
 const EVIDENCE_KEYS = ["nativeSpikeSchema", "terminalProvenanceSchema", "terminalProofSchema", "stableReleaseSchema", "previewReleaseSchema", "releaseCertificationSchema", "previewPlatformVerdictSchema", "piSourceLedgerSchema", "piComponentParitySchema", "piEventFrameParitySchema"];
-const ARTIFACT_KEYS = ["cliEntry", "supervisorEntry", "uiEntry", "nativeExecutable", "nativeCrate", "releaseTarballStem", "diagnosticStem"];
+const ARTIFACT_KEYS = ["cliEntry", "supervisorEntry", "guardianEntry", "uiEntry", "nativeExecutable", "nativeCrate", "processGuardianExecutable", "releaseTarballStem", "diagnosticStem"];
 const ROOT_KEYS = ["schema", "displayName", "commandName", "packageName", "filesystem", "environment", "state", "endpoint", "manifest", "protocol", "evidence", "artifacts"];
 export function validateProductIdentity(value) {
     const root = exactObject(value, ROOT_KEYS, "product identity");

package/dist/src/product-identity.json

@@ -31,6 +31,7 @@
         "piSourceLedgerPath": "A1_PI_SOURCE_LEDGER_PATH",
         "piSourceScanRoot": "A1_PI_SOURCE_SCAN_ROOT",
         "probeTrace": "A1_PROBE_TRACE",
+        "processGuardianPath": "A1_PROCESS_GUARDIAN_PATH",
         "profileHome": "A1_PROFILE_HOME",
         "protocolVersion": "A1_PROTOCOL_VERSION",
         "releaseDigest": "A1_RELEASE_DIGEST",
@@ -87,9 +88,11 @@
     "artifacts": {
         "cliEntry": "bin/a1.js",
         "supervisorEntry": "bin/a1-supervisor.js",
+        "guardianEntry": "bin/a1-guardian.js",
         "uiEntry": "bin/a1-ui.js",
         "nativeExecutable": "a1-terminal-host",
         "nativeCrate": "a1-terminal-host",
+        "processGuardianExecutable": "a1-process-guardian",
         "releaseTarballStem": "timurproko-a1",
         "diagnosticStem": "a1"
     }

package/docs/architecture/boundaries.md

@@ -1,37 +1,43 @@
 # Architecture boundaries
 
-## Terminal ownership
+## Terminal and launch-instance ownership
 
-The current interactive path is:
+Every interactive command uses this profile-neutral lifecycle path:
 
 ```text
 mutable a1 entry
   -> verified immutable release
-  -> foreground lease and broker
-  -> child with inherited physical terminal handles
+  -> Node launch guardian and authenticated launch-instance registration
+  -> native process guardian and per-instance containment
+  -> a1-ui runtime selection
+  -> owned UI or transparent Pi with inherited physical terminal handles
 ```
 
-After handoff, A1 does not read ordinary terminal input, parse child output, render cells, infer frames, synthesize terminal responses, or emit display control. The child and physical terminal own terminal behavior. A1 owns validated launch intent, one exclusive foreground lease, native process identity, lifecycle outcome, and bounded cleanup.
+Launch-instance ownership is plural. The supervisor tracks any number of independently authenticated `a1`, `a1 pi`, and `a1 sandbox` instances and never uses one product-wide foreground mutex. Closing one instance closes only its verified process tree. Persisted rows alone do not prove liveness, and uncertainty never authorizes terminating an unrelated process.
+
+Neither guardian reads ordinary terminal input, parses or relays runtime output, renders cells, infers frames, synthesizes terminal responses, or emits display control. Bare `a1` retains its owned UI authority. In explicit Pi profiles, Pi and the physical terminal retain direct terminal behavior. The private guardian boundary carries only bounded identity, readiness, stop, and outcome data.
 
 Transparent mode has no A1-authoritative terminal surface, internal pane, virtual scrollback, inactive resident tab, or visual reconnection. A future feature that requires those properties must introduce and certify a separate composed-terminal authority; it must not weaken or silently intercept transparent mode.
 
 ## Current module responsibilities
 
-- `domain`: dependency-free transparent launch, process identity, lifecycle, and lease contracts.
+- `lifecycle`: dependency-free launch-instance, process identity, state transition, outcome, and control-command contracts.
+- `process-containment`: artifact verification, OS-verifiable process inspection, containment adapters, and bounded graceful/forced cleanup; it owns no terminal content.
+- `launch-guardian`: one profile-neutral instance coordinator above runtime selection.
 - `workspace-contracts`: dependency-free multi-agent identity, capability, command/event/snapshot, terminal window/tab/pane/session topology, terminal-host, and recovery contracts.
 - `structured-agent-runtime`: planned typed event/command/snapshot runtime. It must not infer semantics from terminal text, own pseudoterminals, or reconstruct screens.
 - `native-host-protocol`: bounded typed local boundary for terminal-host identity, topology revisions, lifecycle, and recovery. Terminal bytes, per-event child input, and rendered cells are forbidden across it.
-- `protocol`: additive control handshake, bounded line framing, request identity, snapshots, command results, and foreground-lease messages. Terminal bytes and reconstructed display state are forbidden.
-- `storage`: SQLite migrations, old-generation reconciliation, and exclusive foreground-lease persistence. Historical schema tables remain readable for installed-state compatibility but do not authorize legacy product behavior.
-- `supervisor`: endpoint identity, cohort ownership, foreground leases, and release shutdown coordination. It owns no terminal surface.
-- `transparent`: generic command resolution, foreground broker, and native attached launchers.
-- release/update/bootstrap: package-derived immutable release identity, cohort selection, durable update transactions, rollback, and dependency-light command entry.
+- `protocol`: additive control handshake, bounded line framing, authenticated launch-instance commands, typed stop intent, snapshots, and command results.
+- `storage`: SQLite migrations, prior-boot reconciliation, and plural launch-instance persistence. Legacy foreground rows are historical migration input and never authorize current ownership.
+- `supervisor`: endpoint identity, plural cohort ownership, per-instance reconciliation, and aggregate release shutdown coordination. It owns no terminal surface.
+- `transparent-terminal`: generic command resolution and direct inherited-handle child waiting below the outer launch guardian; it owns no supervisor lease.
+- release/update/bootstrap: package-derived immutable release identity, process-guardian integrity, cohort selection, durable update transactions, rollback, and dependency-light command entry.
 
 ## Dependency direction
 
 Terminal boundaries are application-agnostic. They may not select behavior from executable names, arguments, CLI-specific environment variables, or visible text. Production code may not import private Pi distribution APIs or use a Pi-specific terminal workaround.
 
-The repository has no production PTY or terminal-emulator dependency. Reintroducing `node-pty`, xterm state, custom input encoders, mode/query trackers, cadence-derived frame inference, or renderer/projection code requires an approved capability change and cannot enter transparent mode.
+The transparent path has no PTY or terminal-emulator dependency. Reintroducing `node-pty`, xterm state, custom input encoders, mode/query trackers, cadence-derived frame inference, or renderer/projection code requires an approved capability change and cannot enter transparent mode. The Rust process guardian is a lifecycle-only native boundary and is independent from the held composed terminal host.
 
 `scripts/check-architecture.mjs` enforces the structural parts of these boundaries. Cross-cutting rationale belongs here; implementation history belongs in Git and archived OpenSpec changes.
 
@@ -39,8 +45,20 @@ The repository has no production PTY or terminal-emulator dependency. Reintroduc
 
 The workspace feature may depend on workspace contracts and the structured/terminal-host foundations. Those foundations may depend only on dependency-free workspace contracts, never on product features, launch profiles, or each other unless an approved capability adds the dependency. Explicit launch profiles and transparent fallback may not import, initialize, launch, or connect to composed terminal-host infrastructure.
 
+Default future agents and composed hosts are children of the originating bare-`a1` launch instance and terminate when it closes. A process that survives command closure requires a separately approved explicit resident capability; durable identity or state recovery never implies an implicitly surviving process.
+
 The structured-agent runtime uses a versioned adapter hello and feature negotiation before readiness. Runtime state must use typed events, commands, snapshots, cancellation, and recovery evidence. It must not infer structured semantics from terminal text, terminal timing, or visual content and must not own pseudoterminals or renderer state.
 
-The terminal-host protocol boundary may carry only bounded typed control and semantic lifecycle messages. Pseudoterminal bytes, per-event child input, rendered cells, cell grids, framebuffers, and screen buffers are forbidden across it. Console host executables and packaging live outside the current JavaScript production owners and remain unavailable until the isolated in-terminal 2×2 proof passes; replacing them with a lightweight custom parser/renderer is forbidden. A desktop-native window and GPU application shell are postponed and are not required for the terminal-hosted product.
+The terminal-host protocol boundary may carry only bounded typed control and semantic lifecycle messages. Pseudoterminal bytes, per-event child input, rendered cells, cell grids, framebuffers, and screen buffers are forbidden across it. Console host executables and packaging live outside the current JavaScript production owners and remain unavailable until the isolated in-terminal proof passes; replacing them with a lightweight custom parser/renderer is forbidden. A desktop-native window and GPU application shell are postponed and are not required for the terminal-hosted product.
 
 Resource queues, retained state, evidence, logs, and diagnostics follow `docs/architecture/resource-and-data-policy.md`. Terminal content and authentication material are never control-store records. Unknown data is potentially sensitive by default and must be rejected or redacted before persistence.
+
+## The rules every surface follows
+
+How A1 builds what a reader sees — deriving a vendor engine's data rather than
+transcribing it, failing the build by name when a vendor change has not been
+absorbed, keeping vendor knowledge behind the vendor boundary, composing screens
+from shared components, showing state rather than narrating it, taking colour
+from declared theme roles, and answering both dispatch and description from one
+declaration — is stated once in the `owned-ux-architecture` capability rather
+than restated per feature.

package/docs/architecture/process-guardian-provenance.md

@@ -0,0 +1,26 @@
+# Process guardian provenance
+
+A1 launch-instance containment uses a standalone native executable named `a1-process-guardian`. The approved implementation is a separate Rust crate at `native/process-guardian`; it is not a Node-API addon and does not reuse or resume the held composed terminal-host implementation.
+
+## Boundary
+
+The executable owns platform process containment and launches one immutable `a1-ui` runtime with inherited terminal handles. It does not create a PTY, read ordinary terminal input, capture or parse runtime output, render, or relay terminal bytes. Its private parent/child coordination is restricted to bounded lifecycle and identity data.
+
+On Windows it uses `windows-sys 0.61.2` to create a Job Object, enables `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`, assigns the runtime before resuming it, denies silent breakaway by never enabling breakaway limits, monitors the verified Node parent process, and terminates remaining job members after root or parent exit.
+
+## Artifact contract
+
+Release builds place the exact executable at:
+
+```text
+dist/native/win32-x64/a1-process-guardian.exe
+dist/native/linux-x64/a1-process-guardian
+dist/native/darwin-x64/a1-process-guardian
+dist/native/darwin-arm64/a1-process-guardian
+```
+
+Each supported artifact must be named in the release integrity manifest with target triple, crate version, guardian protocol version, SHA-256, byte size, build provenance, and signature/attestation status. A missing, altered, incompatible, or wrong-platform artifact is a concise unsupported-containment launch error; A1 never silently falls back to PID-only cleanup.
+
+## Licensing
+
+The guardian is A1-owned MIT-licensed source. Its Windows API binding is `windows-sys`, dual-licensed MIT or Apache-2.0 by its upstream project. Exact transitive notices are generated from the locked release dependency graph.

package/docs/architecture/toolchain.md

@@ -32,6 +32,12 @@ The published package contains:
 
 It contains no PTY, terminal emulator, browser/desktop GUI, custom renderer, input translator, physical automation driver, or generated runtime data.
 
+## Native launch containment
+
+Source builds require Rust/Cargo 1.85 or newer. `npm run build` compiles the standalone `native/process-guardian` crate for the host platform, places it under `dist/native/<platform>-<architecture>/`, and writes an integrity manifest. Preview and stable candidate workflows build platform artifacts on isolated Windows, Linux, and macOS runners and assemble them before packing. macOS remains explicitly unsupported until its exact containment adapter is certified; the package must fail before runtime startup rather than use PID-only cleanup.
+
+The process guardian inherits terminal handles but transports no terminal bytes. See [`process-guardian-provenance.md`](process-guardian-provenance.md).
+
 ## Gates
 
 ```sh

package/docs/architecture/ui-reference-provenance.md

@@ -0,0 +1,50 @@
+# A1 UI reference provenance
+
+The A1 UI component layer is ported from an existing A1-authored reference implementation
+rather than reinvented. Rebuilding a screen from screenshots reproduces its shape but not its
+decisions, and the decisions are where the work is: column arithmetic, sticky-header
+reservation, block-jump targets, span overlay under styling, and pointer hit regions.
+
+This file records what came from where, so a divergence can be judged against its source
+instead of argued from memory. It is the same discipline as
+[`terminal-host-provenance.md`](terminal-host-provenance.md), applied to UI source.
+
+## Source
+
+A1 UI reference implementation, local working copy. The reference is a Pi extension built on
+its own `core` facade layer; A1 is a product, so the port adapts imports and keeps behavior.
+
+## Ported units
+
+| A1 module | Reference unit | Adaptation |
+| --- | --- | --- |
+| `ui-components/line-input.ts` — word motion and word delete | `core/panes/line-input.ts` | `wordLeft`/`wordRight` and their key bindings ported verbatim, including deciding a word delete before a plain one because a raw backspace byte is ctrl+backspace on Windows Terminal. |
+| `ui-components/spans.ts` — `overlaySpan` | `core/presentation/spans.ts` | Uses A1 `displayWidth`; hyperlink and style replay kept verbatim. |
+| `ui-components/scrollbar.ts` — geometry | `core/presentation/scrollbar.ts` — `scrollbarGeom` | Same formula; A1 names the fields and returns null rather than undefined. |
+| `ui-components/scrollbar.ts` — rails | `core/presentation/scrollbar.ts` — zone and hover state | Rail identity kept; A1 holds state in an instance rather than a module global. |
+| `ui-components/list-block.ts` — block navigation | `settings/impl.ts` — `blockJumpTarget`, `blockRowSpan`, `bottomBlockTarget` | Row type generalized from settings rows to a grouped list; targets and edge behavior identical. |
+| `ui-components/list-block.ts` — sticky scroll | `settings/impl.ts` — `stickyHeaderGroup`, `topPaddingRows`, `visibleRowCountAt`, `clampScrollForView` | Same reservation arithmetic and two-pass reveal. |
+| `ui-components/mouse.ts` | `core/panes/sgr-mouse.ts` | Same SGR decoding and per-call regex reset; A1 emits its own event shape. |
+| `ui-components/mouse.ts` — tracking sequences | `core/host/pi/providers/host-bridge-surface.ts` | Mouse modes only. A1 does not take the alternate screen, because the Pi TUI owns the screen A1 renders through. |
+| `features/owned-ui/settings-app.ts` — layout | `settings/impl.ts` — `settingsValueColumn`, `renderFieldLine`, footer and search rendering | Setting discovery is A1's own section model; presentation follows the reference. |
+
+## Ported from the pinned engine
+
+| A1 module | Pinned Pi source | Adaptation |
+| --- | --- | --- |
+| `pi-engine-adapter/settings-integration.ts` — `SETTING_LABELS` | pinned Pi settings selector | Labels and descriptions transcribed so an owned screen reads as the vanilla route words it. Ids are mapped from the selector kebab-case to the exposed camelCase keys. |
+
+## Deliberate differences
+
+- **No alternate screen.** The reference owns its surface and can switch screens; A1 renders
+  through the pinned Pi TUI, so an owned screen is a full-viewport overlay instead.
+- **Colour is a port, not an import.** The reference takes a Pi `Theme` directly. A1 defines
+  `UiTheme` so the component layer never imports a Pi adapter and can be rendered plainly in
+  tests.
+- **Settings content.** The reference aggregates per-extension settings files; A1 has one
+  section for its own settings and one for the agent's, read through the engine settings port.
+
+## Keeping this honest
+
+When a ported unit is changed, either change it to match the reference or record here why it
+diverges. An undocumented divergence is the thing this file exists to prevent.