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

package/README.md

@@ -9,6 +9,8 @@ Requirements:
 - Node.js 22.19 through 24.x
 - npm 11
 
+Published packages include the integrity-verified process guardian for supported platforms. Building A1 from source additionally requires Rust/Cargo 1.85 or newer.
+
 ```sh
 npm install --global @timurproko/a1@latest
 ```
@@ -32,6 +34,8 @@ Bare `a1` owns its Pi-compatible TUI composition and uses the public Pi engine,
 
 `a1 sandbox` is unchanged: it launches vanilla Pi with isolated Pi configuration and resources. “Sandbox” does not mean operating-system, filesystem, process, network, or credential security isolation. See [`docs/features/launch-profiles.md`](docs/features/launch-profiles.md) for first-run directories, independent `/login`, trust behavior, extension placement, and recovery.
 
+Every interactive command creates an independent, non-detachable launch instance. Any number of `a1`, `a1 pi`, and `a1 sandbox` commands may run in separate terminals at the same time. Closing one command closes only its owned UI/Pi process and all agents, extensions, tools, daemons, and descendants created by that invocation; it never requires finding PIDs, deleting control state, or restarting the supervisor. The idle supervisor may remain available for release coordination after all interactive instances close, but it owns no surviving instance runtime.
+
 ## Develop
 
 ```sh
@@ -44,18 +48,37 @@ npm start
 
 A1 control state uses `%APPDATA%\\A1` and `%LOCALAPPDATA%\\A1` on Windows, and the `a1` directory under XDG config/data/runtime roots on Unix. Override it only with declared `A1_*` variables such as `A1_CONFIG_DIR`, `A1_DATA_DIR`, `A1_RUNTIME_DIR`, `A1_DATABASE_PATH`, and `A1_ENDPOINT`. Pi profile roots remain `~/.a1/agent`, `~/.pi/agent`, and `~/.a1/sandbox`. This is a no-migration identity hard cut; see [`docs/architecture/toolchain.md`](docs/architecture/toolchain.md#identity-hard-cut-and-cleanup) before removing obsolete control state.
 
-### Branch lifecycle
+### Worktree lifecycle
+
+The primary worktree stays on `develop` and is integration-only. Each task uses a detached worktree under the repository's ignored `.worktrees/` directory, based on current `origin/develop` unless another base is selected.
+
+```sh
+git fetch origin --prune
+git worktree add --detach .worktrees/<task-id> origin/develop
+cd .worktrees/<task-id>
+```
+
+Commit and validate coherent work there. Because `develop` is protected, push the detached commit to one temporary remote branch and merge one pull request for the requested change. After merge, update the primary worktree and remove the task worktree only when its commits are reachable from `develop`:
+
+```sh
+git push origin HEAD:refs/heads/<task-id>
+gh pr create --base develop --head <task-id>
+# After the pull request is merged:
+cd <repository-root>
+git fetch origin --prune
+git merge --ff-only origin/develop
+git worktree remove .worktrees/<task-id>
+git worktree prune
+```
 
-Create every topic branch and every `milestone/<name>` work branch from `develop`; never implement directly on `develop` or `master`. A source branch is closed only after this sequence completes:
+Manual acceptance does not leave a permanent validation checkout. Once acceptance is recorded, archive the completed OpenSpec change, integrate the archive commit into `develop`, then remove and prune every task or acceptance worktree retained for that change. Never remove a worktree before all of its implementation, acceptance, and archive commits are reachable from `develop`.
 
-1. Validate the source branch with its required gates.
-2. Merge it into `develop` and push the merged `develop` commit.
-3. Switch to `develop`.
-4. Preview the exact cleanup set with `npm run branches:prune -- --branch <source>`.
-5. Safely delete the reviewed local source with `npm run branches:prune -- --apply --branch <source>`.
-6. When the non-protected remote source exists, delete it in the same cleanup with `npm run branches:prune -- --apply --branch <source> --remote origin`.
+Local package archives and ad hoc test builds belong under `.builds/`, never in the repository root. For manual package tests, use:
 
-The command defaults to a dry run against `develop`. It always retains `develop`, `master`, the checked-out branch, explicitly protected branches, and branches whose tips are not ancestors of the integration target. Apply mode uses only Git safe deletion (`git branch -d`), never force deletion. Use `--base <branch>` for another explicit integration target, `--protect <branch>` for additional protection, and `--json` for machine-readable review.
+```sh
+mkdir -p .builds
+npm pack --ignore-scripts --pack-destination .builds
+```
 
 Run the non-desktop gates with:
 

package/bin/a1-guardian.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+const { fileURLToPath } = await import("node:url");
+const { resolve } = await import("node:path");
+const { runLaunchGuardian } = await import("../dist/src/foundation/launch-guardian/index.js");
+
+const releaseRoot = process.env.A1_RELEASE_ROOT ?? fileURLToPath(new URL("..", import.meta.url));
+const profileId = process.env.A1_LAUNCH_PROFILE ?? "a1";
+
+runLaunchGuardian({
+  profileId,
+  releaseRoot,
+  uiEntry: resolve(releaseRoot, "bin", "a1-ui.js"),
+  environment: process.env,
+  cwd: process.cwd(),
+}).then(
+  code => { process.exitCode = code; },
+  error => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  },
+);

package/bin/a1-ui.js

@@ -3,13 +3,16 @@
 const { runSelectedInteractiveRuntime } = await import("../dist/src/features/launch/index.js");
 
 runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
-  ownedUi: async () => {
-    const [{ runOwnedUi }, { composeOwnedUiApplication }] = await Promise.all([
+  ownedUi: async profileId => {
+    const [{ runOwnedUi }, { composeOwnedUi }] = await Promise.all([
       import("../dist/src/features/owned-ui/index.js"),
       import("../dist/src/composition/index.js"),
     ]);
-    const application = await composeOwnedUiApplication({ cwd: process.cwd() });
-    return await runOwnedUi({ application });
+    // A1_OWNED_SURFACES=off presents pinned Pi's interface through A1's own
+    // rendering and input, which is what the parity comparison measures.
+    const ownedSurfaces = process.env.A1_OWNED_SURFACES === "off" ? "off" : "on";
+    const { application, settings } = await composeOwnedUi({ cwd: process.cwd(), profileId, ownedSurfaces });
+    return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
   },
   transparent: async profileId => {
     const { runSelectedTransparentRuntime } = await import("../dist/src/composition/transparent-runtime.js");

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

@@ -0,0 +1,20 @@
+{
+  "schema": "a1-process-guardian-artifact-v1",
+  "protocolVersion": 1,
+  "crateVersion": "0.1.0-dev",
+  "platform": "darwin",
+  "architecture": "arm64",
+  "capability": "unsupported",
+  "builtAt": "2026-08-22T13:11:56.818Z",
+  "artifact": {
+    "filename": "a1-process-guardian",
+    "sha256": "bb07d029b67a5eae4fbf3dea64f96cdf03462920949f2ea7e9e7b1bd33dbabc1",
+    "size": 356368
+  },
+  "provenance": {
+    "language": "Rust",
+    "cargoLock": "native/process-guardian/Cargo.lock",
+    "sourceRoot": "native/process-guardian",
+    "signatureStatus": "ci-attestation-required"
+  }
+}

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

@@ -0,0 +1,20 @@
+{
+  "schema": "a1-process-guardian-artifact-v1",
+  "protocolVersion": 1,
+  "crateVersion": "0.1.0-dev",
+  "platform": "linux",
+  "architecture": "x64",
+  "capability": "supported",
+  "builtAt": "2026-08-22T13:12:07.615Z",
+  "artifact": {
+    "filename": "a1-process-guardian",
+    "sha256": "f66cc7ac6d30ad424bc00992e4c5425259d36f055893d872eda9cf518bdb2ed0",
+    "size": 415696
+  },
+  "provenance": {
+    "language": "Rust",
+    "cargoLock": "native/process-guardian/Cargo.lock",
+    "sourceRoot": "native/process-guardian",
+    "signatureStatus": "ci-attestation-required"
+  }
+}

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

@@ -0,0 +1,20 @@
+{
+  "schema": "a1-process-guardian-artifact-v1",
+  "protocolVersion": 1,
+  "crateVersion": "0.1.0-dev",
+  "platform": "win32",
+  "architecture": "x64",
+  "capability": "supported",
+  "builtAt": "2026-08-22T13:12:29.999Z",
+  "artifact": {
+    "filename": "a1-process-guardian.exe",
+    "sha256": "83641a8a264dae32e57020ef1f37823ffe186b5acd28df18eae1afa80d25854c",
+    "size": 172544
+  },
+  "provenance": {
+    "language": "Rust",
+    "cargoLock": "native/process-guardian/Cargo.lock",
+    "sourceRoot": "native/process-guardian",
+    "signatureStatus": "ci-attestation-required"
+  }
+}

package/dist/src/composition/index.d.ts

@@ -1,6 +1,8 @@
 import { type AgentEnginePort } from "../foundation/agent-engine-contracts/index.js";
 import { type PiEngineAdapter } from "../foundation/pi-engine-adapter/index.js";
 import { type OwnedUiApplicationPort, type PresentationComponentPort, type PresentationRuntimePort, type PresentationTerminalPort } from "../foundation/presentation-contracts/index.js";
+import { OwnedUiSettingsSession } from "../foundation/owned-ui-settings/index.js";
+import type { UiRouteHost } from "../foundation/pi-owned-ui-integration/index.js";
 export interface ProcessCompositionOptions {
     readonly cwd?: string;
     readonly sessionId?: string;
@@ -12,11 +14,35 @@ export interface OwnedUiCompositionOptions {
     readonly cwd?: string;
     readonly terminal?: PresentationTerminalPort;
     readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
+    /**
+     * A1 profile whose settings this session reads and writes. Omitted keeps the
+     * session settings-free, which is what the pinned comparison paths use.
+     */
+    readonly profileId?: string;
+    /**
+     * Whether A1's own surfaces are reachable. Withheld for the rendering parity
+     * comparison, which measures this composition against pinned Pi and so must
+     * present Pi's interface and nothing of A1's own. It is the same composition
+     * either way: a parity run built beside the product would measure itself.
+     */
+    readonly ownedSurfaces?: "on" | "off";
+}
+export interface OwnedUiComposition {
+    readonly application: OwnedUiApplicationPort;
+    /** Present when a profile was supplied, so the caller can resolve settings before start. */
+    readonly settings: OwnedUiSettingsSession | null;
 }
 export declare function composeOwnedUiApplication(options?: OwnedUiCompositionOptions): Promise<OwnedUiApplicationPort>;
+export declare function composeOwnedUi(options?: OwnedUiCompositionOptions): Promise<OwnedUiComposition>;
 export interface ProcessComposition {
     readonly engine: AgentEnginePort;
     createPresentation(root: PresentationComponentPort, terminal: PresentationTerminalPort): PresentationRuntimePort;
     dispose(): Promise<void>;
 }
 export declare function composeProcess(options?: ProcessCompositionOptions): Promise<ProcessComposition>;
+/**
+ * Registers the A1-owned screens and adapts the app host to the shell's route
+ * seam. The shell mounts whatever surface it is handed and forwards keys; it
+ * never learns what an app is.
+ */
+export declare function createOwnedRouteHost(settings: OwnedUiSettingsSession): UiRouteHost;

package/dist/src/composition/index.js

@@ -3,6 +3,12 @@ import { createPiEngineAdapter } from "../foundation/pi-engine-adapter/index.js"
 import { createPiPresentationRuntime, createPiTerminalBridge } from "../foundation/pi-tui-runtime-adapter/index.js";
 import { assertPresentationComponent, assertPresentationRuntime, } from "../foundation/presentation-contracts/index.js";
 import { OwnedUiSessionShell } from "../foundation/pi-owned-ui-integration/index.js";
+import { OwnedUiSettingsSession, OwnedUiSettingsStore } from "../foundation/owned-ui-settings/index.js";
+import { UiAppHost, UiAppRegistry } from "../foundation/ui-apps/index.js";
+import { getAvailablePiThemes, piTheme } from "../foundation/pi-component-adapter/index.js";
+import { faint } from "../foundation/ui-components/index.js";
+import { SETTINGS_APP_ID, SETTINGS_ROUTE, SettingsApp } from "../features/owned-ui/index.js";
+import { resolveProductPaths } from "../foundation/lifecycle/index.js";
 const CAPABILITIES = {
     contractVersion: AGENT_ENGINE_CONTRACT_VERSION,
     commands: ["prompt", "steer", "follow-up", "abort", "retry", "compact", "bash", "replace-session"],
@@ -10,20 +16,34 @@ const CAPABILITIES = {
     snapshots: { supported: true, maxBytes: 1024 * 1024 },
 };
 export async function composeOwnedUiApplication(options = {}) {
+    return (await composeOwnedUi(options)).application;
+}
+export async function composeOwnedUi(options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const adapter = options.createPiAdapter ? await options.createPiAdapter() : await createPiEngineAdapter({ cwd });
+    const adapter = options.createPiAdapter
+        ? await options.createPiAdapter()
+        : await createPiEngineAdapter({ cwd, availableThemes: () => getAvailablePiThemes().map(theme => theme.name) });
+    const settings = options.profileId === undefined
+        ? null
+        : new OwnedUiSettingsSession({
+            store: new OwnedUiSettingsStore({ configDir: resolveProductPaths().configDir, profileId: options.profileId }),
+            agentProvider: () => adapter.settingsPort(),
+        });
+    const routeHost = settings === null || options.ownedSurfaces === "off" ? null : createOwnedRouteHost(settings);
     const shell = new OwnedUiSessionShell({
         backend: adapter,
         cwd,
         ...(options.terminal === undefined ? {} : { terminal: createPiTerminalBridge(options.terminal) }),
+        ...(routeHost === null ? {} : { routeHost }),
     });
-    return {
+    const application = {
         get disposed() { return adapter.disposed; },
         start: () => shell.start(),
         flush: () => adapter.flushEvents(),
         waitUntilStopped: () => shell.waitUntilStopped(),
         dispose: () => shell.dispose(),
     };
+    return { application, settings };
 }
 export async function composeProcess(options = {}) {
     let engine = options.engine;
@@ -164,3 +184,69 @@ function toMessage(block) {
     const role = block.kind === "user" ? "user" : block.kind === "system" ? "system" : block.kind === "tool-call" || block.kind === "tool-result" ? "tool" : "assistant";
     return { id: block.id, role, status: block.status === "live" ? "streaming" : "final", content: [{ kind: "text", text: block.text }] };
 }
+/**
+ * Registers the A1-owned screens and adapts the app host to the shell's route
+ * seam. The shell mounts whatever surface it is handed and forwards keys; it
+ * never learns what an app is.
+ */
+export function createOwnedRouteHost(settings) {
+    const registry = new UiAppRegistry();
+    registry.register({ id: SETTINGS_APP_ID, route: SETTINGS_ROUTE, create: () => new SettingsApp(settings) });
+    return {
+        claims: route => registry.forRoute(route) !== null,
+        open: route => {
+            const registration = registry.forRoute(route);
+            if (registration === null)
+                return null;
+            let size = { width: 80, height: 24 };
+            let frame = [];
+            let closed = false;
+            let onRender = () => undefined;
+            let onExit = () => undefined;
+            const host = new UiAppHost({
+                registry,
+                closeOnInterrupt: true,
+                theme: pinnedTheme(),
+                surface: {
+                    size: () => size,
+                    requestRender: () => onRender(),
+                    exit: () => onExit(),
+                    present: lines => {
+                        if (lines === null)
+                            closed = true;
+                        else
+                            frame = lines;
+                    },
+                },
+            });
+            host.open(registration.id);
+            const surface = {
+                id: registration.id,
+                render: (width, height) => {
+                    size = { width, height };
+                    host.render();
+                    return frame.length === height ? frame : [...frame.slice(0, height), ...Array(Math.max(0, height - frame.length)).fill("")];
+                },
+                handleInput: data => host.handleInput(data).consumed,
+                handleMouse: event => host.handleMouse(event).consumed,
+                isClosed: () => closed || !host.isPresenting,
+                close: () => host.close(),
+                onRenderRequested: listener => { onRender = listener; },
+                onExitRequested: listener => { onExit = listener; },
+            };
+            return surface;
+        },
+    };
+}
+/** Maps A1 UI tokens onto the pinned Pi theme so owned screens match the shell. */
+function pinnedTheme() {
+    return {
+        fg: (token, text) => piTheme().fg(token, text),
+        bold: (text) => piTheme().bold(text),
+        // Quiet, and quieter again: the terminal's own faint attribute over the
+        // dimmest colour the theme has.
+        disabled: (text) => faint(piTheme().fg("dim", text)),
+        highlight: (text) => `${text}`,
+        panel: (text) => `${text}`,
+    };
+}

package/dist/src/features/launch/runtime-selection.d.ts

@@ -2,12 +2,13 @@ import { type LaunchProfileId } from "../../foundation/lifecycle/index.js";
 export type TransparentInteractiveProfileId = Exclude<LaunchProfileId, "a1">;
 export type InteractiveRuntimeSelection = {
     readonly kind: "owned-ui";
+    readonly profileId: Extract<LaunchProfileId, "a1">;
 } | {
     readonly kind: "transparent";
     readonly profileId: TransparentInteractiveProfileId;
 };
 export interface InteractiveRuntimeRunners {
-    readonly ownedUi: () => Promise<number>;
+    readonly ownedUi: (profileId: Extract<LaunchProfileId, "a1">) => Promise<number>;
     readonly transparent: (profileId: TransparentInteractiveProfileId) => Promise<number>;
 }
 export declare function selectInteractiveRuntime(profileId: string): InteractiveRuntimeSelection;

package/dist/src/features/launch/runtime-selection.js

@@ -2,12 +2,12 @@ import { assertLaunchProfileId } from "../../foundation/lifecycle/index.js";
 export function selectInteractiveRuntime(profileId) {
     assertLaunchProfileId(profileId);
     return profileId === "a1"
-        ? Object.freeze({ kind: "owned-ui" })
+        ? Object.freeze({ kind: "owned-ui", profileId: "a1" })
         : Object.freeze({ kind: "transparent", profileId });
 }
 export async function runSelectedInteractiveRuntime(profileId, runners) {
     const selection = selectInteractiveRuntime(profileId);
     return selection.kind === "owned-ui"
-        ? await runners.ownedUi()
+        ? await runners.ownedUi(selection.profileId)
         : await runners.transparent(selection.profileId);
 }

package/dist/src/features/owned-ui/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./customization.js";
 export * from "./diagnostics.js";
 export * from "./run.js";
+export * from "./settings-app.js";

package/dist/src/features/owned-ui/index.js

@@ -1,3 +1,4 @@
 export * from "./customization.js";
 export * from "./diagnostics.js";
 export * from "./run.js";
+export * from "./settings-app.js";

package/dist/src/features/owned-ui/run.d.ts

@@ -1,5 +1,11 @@
 import type { OwnedUiApplicationPort } from "../../foundation/presentation-contracts/index.js";
+import type { OwnedUiSettingsSession } from "../../foundation/owned-ui-settings/index.js";
 export interface OwnedUiRunOptions {
     readonly application: OwnedUiApplicationPort;
+    /**
+     * Resolved once before the application starts, so every surface reads the same
+     * values for the life of the session. Omitted when the caller runs without settings.
+     */
+    readonly settings?: OwnedUiSettingsSession;
 }
 export declare function runOwnedUi(options: OwnedUiRunOptions): Promise<number>;

package/dist/src/features/owned-ui/run.js

@@ -1,6 +1,8 @@
 export async function runOwnedUi(options) {
-    const { application } = options;
+    const { application, settings } = options;
     try {
+        if (settings)
+            await settings.load();
         application.start();
         await application.flush();
         if (!application.disposed)

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

@@ -0,0 +1,22 @@
+import type { AppHostServices, UiApp } from "../../foundation/ui-apps/index.js";
+import { ShortcutRegistry, type PaneInputResult, type PaneMouseEvent, type PaneRect } from "../../foundation/ui-components/index.js";
+import type { OwnedUiSettingsSession } from "../../foundation/owned-ui-settings/index.js";
+export declare const SETTINGS_APP_ID = "settings";
+export declare const SETTINGS_ROUTE = "settings";
+type Action = "move-up" | "move-down" | "block-up" | "block-down" | "first" | "last" | "page-up" | "page-down" | "previous-value" | "next-value" | "activate" | "open-filter" | "close" | "part-previous" | "part-next" | "part-change";
+export declare const SETTINGS_SHORTCUTS: ShortcutRegistry<Action>;
+/**
+ * The settings screen. Rows, sticky headers, scrolling, and the keymap come from
+ * the shared component layer; what belongs to settings is which sections exist,
+ * how a value is shown, and where an accepted change is routed.
+ */
+export declare class SettingsApp implements UiApp {
+    #private;
+    readonly id = "settings";
+    constructor(session: OwnedUiSettingsSession);
+    onActivate(host: AppHostServices): void;
+    render(rect: PaneRect, host: AppHostServices): readonly string[];
+    onInput(data: string, host: AppHostServices): PaneInputResult;
+    onMouse(event: PaneMouseEvent, _host: AppHostServices): PaneInputResult;
+}
+export {};