@timurproko/a1 0.1.1-dev.1 → 0.1.1-dev.11

package/docs/ci-release-runbook.md

@@ -0,0 +1,67 @@
+# CI and release operations
+
+GitHub Actions is the only automation platform. Two required checks protect the branches:
+
+| Branch | Required check | Produced by |
+| --- | --- | --- |
+| `develop` | `Development validation required` | `.github/workflows/ci.yml` |
+| `master` | `Stable candidate required` | `.github/workflows/certify-stable.yml` |
+
+These are job display names. If you rename one, update the ruleset definition, this runbook, and the live ruleset together.
+
+## How much validation runs when
+
+| Change | Validation |
+| --- | --- |
+| Docs or specs only | OpenSpec strict lint, nothing else |
+| Any code PR into `develop` | Fast tier: typecheck, architecture checks, unit/contract tests |
+| Preview candidate (`next`) | Fast tier + package gates: content, clean install, dependency policy |
+| Stable candidate (`latest`) | Complete suite on Windows, Linux, and macOS + physical evidence |
+
+Need more coverage for a risky preview? Dispatch the candidate with `full: true`, or run the **Full regression** workflow on demand.
+
+## Publish a preview to npm `next`
+
+One command from a clean `develop` checkout runs the whole chain — candidate build, publish, registry verification:
+
+```sh
+npm run release:next
+```
+
+It dispatches the same trusted workflows below and never publishes local bytes. The manual steps remain the reference path:
+
+1. Make sure `Development validation required` is green on the `develop` tip.
+2. Dispatch **Build npm next candidate** with the exact commit and `confirm_candidate=build-uncertified-next-candidate`.
+3. Check the resulting `candidate-evidence.json`: gates passed, package integrity matches.
+4. Approve the `npm-publish` environment and dispatch **Publish npm next** with the candidate run id.
+
+The publisher uploads the exact validated tarball — it never rebuilds. Candidates expire after 14 days; an expired or mismatched artifact means building a new candidate, not patching the old one.
+
+## Publish a stable release to npm `latest`
+
+1. Commit the final version to `develop` (clean tree, version not yet on the registry).
+2. Dispatch **Build stable candidate** — it packs once and validates the same bytes on all three platforms.
+3. Dispatch **Certify stable physical platforms** on the dedicated isolated workers (they set `PHYSICAL_WORKER_ISOLATED=true` and run under the `stable-physical` environment). Never run physical host probes on a developer workstation.
+4. Dispatch **Certify stable candidate** with both run ids. `Stable candidate required` passes only when every verdict binds the same commit, version, and digest.
+5. Merge that exact commit to `master`, tag it `v<version>`, and dispatch **Publish npm stable**, then approve `npm-publish`.
+
+Stable artifacts expire after 30 days. The same rule as previews applies: publication still requires exact certified bytes. Never upload locally rebuilt bytes, and never route around certification by rebuilding inside a publisher.
+
+## When something fails
+
+- **PR validation fails:** fix the code and push. Do not mark a failed tier optional.
+- **Candidate validation fails:** discard the candidate and build a new one after the fix.
+- **Physical worker fails:** fix or replace the worker, then rerun the full physical evidence for the candidate.
+- **Publisher fails before npm accepted the bytes:** diagnose and retry with the same candidate while it is unexpired and the version is still unpublished.
+- **Publisher is uncertain after npm accepted the bytes:** stop. Check the registry for the version, tag, and digest. Repair a dist-tag only as a separate reviewed operation — never republish.
+
+## Why the rulesets look the way they do
+
+One person maintains this repository, and GitHub does not let a PR author approve their own PR. Requiring even one approval would therefore deadlock the authorized solo-maintainer path — no PR could ever merge. So both rulesets require a pull request, a green required check, and resolved review threads, but set required approving reviews to zero.
+
+- `develop` does not require the branch to be up to date: once a PR is approved and green, it merges even if unrelated work landed first — no re-validation loop.
+- `master` does require it: a stable promotion always validates the exact final state.
+
+If a second maintainer joins, raise the approval count. Do not add a direct-push bypass as a shortcut, and never weaken the force-push or deletion protection.
+
+Ruleset mutation is a separate administrative operation: run `node scripts/check-github-rulesets.mjs` to see the diff, and apply only when a maintainer explicitly confirms with `--apply --confirm apply-a1-ci-rulesets`.

package/docs/features/launch-profiles.md

@@ -43,7 +43,13 @@ Run Pi’s normal `/login` independently in each profile that needs stored authe
 
 Bare `a1` runs the A1-owned full-viewport TUI over public Pi engine, component, and terminal APIs. A1 owns composition, input routing, modal focus, selection behavior, scrolling, and restoration without inserting a PTY or terminal-byte relay. Its default presentation is pinned to vanilla Pi parity; structured tabs and A1-specific visual customization are not enabled.
 
-`a1 pi` and `a1 sandbox` retain transparent direct attachment. In those profiles, one untouched Pi process and the physical terminal own rendering, input, selection, clipboard, scrollback, and terminal modes; A1 owns foreground lease and lifecycle only.
+`a1 pi` and `a1 sandbox` retain transparent direct attachment. In those profiles, untouched Pi and the physical terminal own rendering, input, selection, clipboard, scrollback, and terminal modes; A1 owns only per-invocation process containment and lifecycle evidence.
+
+## Concurrent instance lifecycle
+
+Every `a1`, `a1 pi`, and `a1 sandbox` invocation receives a unique non-detachable launch instance. There is no product-wide foreground slot: the same profile or any mixture of profiles may run concurrently in separate terminals. Profile files remain shared according to the selected profile root, while process ownership, lifecycle outcome, and cleanup remain scoped to the command that launched them.
+
+Normal root exit, terminal closure, guardian failure, and verified update shutdown all close the instance's remaining process tree within bounded graceful and forced deadlines. Closing one instance never closes another. A control supervisor may remain idle afterward, but closed instances leave no UI, Pi, extension daemon, agent worker, tool, or descendant process. Ordinary recovery never asks users to kill a PID or delete the control database.
 
 ## Recovery and comparison
 

package/docs/manual-launch-instance-acceptance.md

@@ -0,0 +1,66 @@
+# Launch-instance exact-artifact acceptance
+
+Run this checklist only against a packaged candidate on a user-controlled terminal or isolated disposable Windows worker. Do not automate launching, focusing, driving, or closing terminal windows on an active workstation.
+
+## Artifact identity
+
+Record before testing:
+
+```text
+A1 release ID:
+A1 package version:
+Source commit:
+Candidate tarball SHA-256/integrity:
+Process guardian target: win32-x64
+Process guardian crate version:
+Process guardian protocol version:
+Process guardian SHA-256:
+Process guardian signature/attestation status:
+Machine/Windows/terminal versions:
+Tester or worker attestation:
+```
+
+The process guardian values must match `dist/native/win32-x64/manifest.json` inside the exact installed candidate. Stop if the file is missing, mismatched, altered, or reports an unsupported capability.
+
+## Concurrent launch matrix
+
+Open four independent terminal tabs and launch:
+
+```text
+Terminal 1: a1
+Terminal 2: a1
+Terminal 3: a1 pi
+Terminal 4: a1 sandbox
+```
+
+Confirm all four become usable without a global foreground-lease error. Record each launch-instance ID from supervisor metadata and verify all four IDs are distinct.
+
+## Isolated closure
+
+1. Exit Terminal 3 normally. Confirm only its vanilla Pi tree exits; Terminals 1, 2, and 4 remain usable.
+2. Close the Terminal 4 tab/window without exiting Pi first. Confirm its sandbox Pi, extension daemons, agent workers, tools, and descendants disappear within the bounded deadline while both bare-A1 terminals remain usable.
+3. Exit Terminal 1 normally after causing a fixture extension to create a child and grandchild. Confirm the complete tree disappears and Terminal 2 remains usable.
+4. Force the Terminal 2 launch guardian to fail on the isolated worker. Confirm Job Object kill-on-close removes its root and descendants and leaves unrelated fixture processes alive.
+
+Record root, child, and grandchild native identities before each close and the observed terminal outcome afterward. Do not substitute manual PID termination for a failed cleanup.
+
+## Stale-state recovery
+
+Using isolated control directories, install a version-4 fixture database containing one requested or active legacy foreground lease whose former PID is dead. Run `a1 sandbox` once. Confirm that the same invocation migrates the row to historical interrupted state and launches normally without restarting the supervisor, deleting state, or discovering a PID.
+
+Repeat with an ownership-uncertain fixture process. Confirm a new independent launch still starts and the uncertain unrelated process is not terminated.
+
+## Update fan-out
+
+With at least three mixed-profile instances active, run the candidate's update-shutdown fixture. Confirm every instance receives one stop intent, each complete process tree closes, and cohort replacement occurs only after all verified terminal outcomes. A delayed or uncertain instance must prevent unsafe replacement without causing another instance to be reported idle prematurely.
+
+## Verdict
+
+Record one of:
+
+```text
+ACCEPTED — exact package and guardian digests above passed every scenario
+REJECTED — include failed step, observed process identities, outcomes, and diagnostics
+```
+
+Acceptance applies only to the exact package and process-guardian bytes recorded above. It does not certify macOS, Linux, composed terminals, detached agents, or an operating-system security sandbox.

package/docs/manual-terminal-colour-check.md

@@ -0,0 +1,55 @@
+# Terminal colour check
+
+## What can go wrong
+
+Every colour the interface draws is 24-bit: the pinned dark theme's accent is
+`#8abeb7`, its border `#5f87ff`, its headings `#f0c674`. On Windows, Node decides
+once at startup whether it may send those sequences to the terminal at all. It
+asks the console to enable virtual terminal processing; when that fails it renders
+ANSI itself, and its renderer knows only the sixteen SGR colours. Each 24-bit
+colour is then replaced by the terminal's nearest palette entry, so the whole
+interface shifts at once — accent to the terminal's cyan, headings to its yellow —
+while the application still writes exactly the bytes it always wrote.
+
+That decision is made per process, from the console handle the process was given,
+and every process it launches inherits the result. It is a property of how the
+session was started, not of what is drawn.
+
+## Launching so colour survives
+
+The installed command is an npm shim — a shell script that `exec`s Node — and that
+shape keeps 24-bit colour. So does `pi`, for the same reason.
+
+- Installed: `a1`, `a1 pi`
+- From a checkout: `scripts/dev` and `scripts/dev pi`
+
+`npm start` and `npm run start:pi` build first and then launch through the same
+entry, but a package manager on Windows hands the script to `cmd.exe`, which can
+leave the launch without a terminal on its input; the launcher says so and stops
+rather than opening a session that closes as it starts. Running `scripts/dev`
+from the shell is the direct path.
+
+A directly launched `node scripts/start-local.mjs` under Git Bash does not, and
+neither does a directly launched `node …/pi/dist/cli.js`: the collapse belongs to
+the launch, not to either application.
+
+## Checking a terminal
+
+```
+node scripts/check-terminal-colour.mjs
+```
+
+It prints the same colour as 24-bit, as a 256-colour index, and as the terminal's
+own palette entry. When the first block is indistinguishable from the third, this
+launch collapses colour and any comparison made in it is a comparison of two wrong
+screens.
+
+## What the gates hold
+
+- `test/features/launch/terminal-colour-fidelity.test.ts` holds the emitted bytes:
+  the pinned palette resolves to 24-bit sequences, a 256-colour terminal stays on
+  indices, and the launch chain keeps inheriting the terminal it was started from
+  rather than opening a console of its own.
+- The reader compares `a1 pi` with pinned Pi in the same terminal. Run the colour
+  check first: a launch that collapses colour makes both sessions equally wrong, so
+  they would agree with each other and disagree with what a user sees.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.1-dev.1",
+  "version": "0.1.1-dev.11",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "packageManager": "npm@11.13.0",
   "bin": {
-    "a1": "bin/a1.js"
+    "a1": "bin/cli.js"
   },
   "files": [
     "bin",
@@ -19,30 +19,35 @@
   },
   "scripts": {
     "clean": "node scripts/clean.mjs",
-    "build": "npm run clean && tsc -p tsconfig.build.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/build-process-guardian.mjs",
+    "build:process-guardian": "node scripts/build-process-guardian.mjs",
+    "typecheck": "tsgo -p tsconfig.json --noEmit",
     "check:architecture": "node scripts/check-architecture.mjs && node scripts/product-identifier-policy.mjs --check && node scripts/check-product-identity-boundaries.mjs && node scripts/check-package-identity.mjs && node scripts/check-pinned-pi-source-ledger.mjs && node scripts/check-terminal-host-provenance.mjs",
     "check:customization-ready": "node scripts/check-owned-ui-customization-prerequisites.mjs",
     "check:deprecated": "node scripts/check-deprecated-dependencies.mjs",
-    "check": "npm run typecheck && npm run check:architecture && npm run check:customization-ready && npm run check:deprecated && npm test && npm run test:release",
-    "validate:agent": "npm run check",
+    "branches:prune": "node scripts/prune-merged-branches.mjs",
+    "check": "npm run test:fast",
     "publish:next": "tsx scripts/publish-next.ts",
-    "test": "vitest run",
-    "test:unit": "vitest run test/cli test/features test/foundation test/repository-governance --exclude '**/*.integration.test.ts'",
-    "test:integration": "vitest run test/foundation/release/update-transition.integration.test.ts test/features/launch/profile-isolation.integration.test.ts",
+    "release:next": "node scripts/release-next.mjs",
+    "test": "npm run test:fast",
+    "test:fast": "node scripts/run-validation-tier.mjs typecheck fast",
+    "test:scope": "node scripts/run-validation-tier.mjs",
+    "test:full": "node scripts/run-validation-tier.mjs full-release",
     "test:release": "node scripts/run-release-gates.mjs",
     "test:terminal-host": "node scripts/run-terminal-host-probe.mjs",
-    "test:pi-terminal-parity": "npm run build --silent && node scripts/run-pi-terminal-parity.mjs",
     "test:pi-engine-conformance": "vitest run test/foundation/pi-engine-adapter/conformance.test.ts test/foundation/pi-engine-adapter/runtime-integration.test.ts test/foundation/pi-engine-adapter/session-integration.test.ts",
     "report:pi-engine-conformance": "npm run build --silent && node scripts/run-pi-engine-conformance.mjs",
-    "sync:pi-ui": "npm run update:pi-component-parity && npm run update:pi-event-frame-parity",
+    "sync:pi-ui": "npm run update:pi-component-parity && npm run update:pi-event-frame-parity && npm run update:pi-settings-metadata",
     "update:pi-component-parity": "tsx scripts/update-pi-component-parity.ts",
     "update:pi-event-frame-parity": "tsx scripts/update-pi-event-frame-parity.ts",
     "proof:terminal-host": "node scripts/run-terminal-host.mjs",
-    "start": "npm run build && node scripts/start-local.mjs",
+    "start": "npm run build && node scripts/dev-launch.mjs",
+    "start:pi": "npm run build && node scripts/dev-launch.mjs pi",
+    "start:sandbox": "npm run build && node scripts/dev-launch.mjs sandbox",
     "prepack": "node scripts/prepack-gate.mjs",
-    "prepublishOnly": "npm run check",
-    "prepare": "npm run build"
+    "prepublishOnly": "npm run test:release",
+    "prepare": "npm run build",
+    "update:pi-settings-metadata": "node scripts/update-pi-settings-metadata.mjs"
   },
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",
@@ -55,6 +60,7 @@
     "@types/cross-spawn": "6.0.6",
     "@types/node": "24.2.1",
     "@types/semver": "7.8.0",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@xterm/headless": "6.0.0",
     "node-pty": "1.1.0",
     "tsx": "4.20.3",

package/dist/src/composition/transparent-runtime.d.ts

@@ -1,6 +0,0 @@
-import type { LaunchProfileId } from "../foundation/lifecycle/index.js";
-export declare function selectTransparentChild(environment?: NodeJS.ProcessEnv, executable?: string, compositionUrl?: string): {
-    readonly executable: string;
-    readonly arguments: readonly string[];
-};
-export declare function runSelectedTransparentRuntime(profileId: Exclude<LaunchProfileId, "a1">, environment?: NodeJS.ProcessEnv): Promise<number>;

package/dist/src/composition/transparent-runtime.js

@@ -1,19 +0,0 @@
-import { fileURLToPath } from "node:url";
-import { runTransparentForeground } from "../foundation/transparent-terminal/index.js";
-export function selectTransparentChild(environment = process.env, executable = process.execPath, compositionUrl = import.meta.url) {
-    const entry = fileURLToPath(new URL("../foundation/pi-engine-adapter/public-main-entry.js", compositionUrl));
-    return { executable, arguments: [entry, ...parseSelectedArguments(environment.A1_LAUNCH_ARGUMENTS_JSON)] };
-}
-export async function runSelectedTransparentRuntime(profileId, environment = process.env) {
-    const child = selectTransparentChild(environment);
-    return await runTransparentForeground({ profileId, environment, ...child });
-}
-function parseSelectedArguments(source) {
-    if (!source)
-        return [];
-    const value = JSON.parse(source);
-    if (!Array.isArray(value) || value.some(item => typeof item !== "string")) {
-        throw new TypeError("A1_LAUNCH_ARGUMENTS_JSON must be a JSON array of strings");
-    }
-    return value;
-}

package/dist/src/foundation/transparent-terminal/command-resolution.d.ts

@@ -1,13 +0,0 @@
-export interface ResolvedTransparentCommand {
-    readonly executable: string;
-    readonly arguments: readonly string[];
-    readonly source: "exact" | "path" | "npm-windows-shim";
-}
-export interface TransparentCommandResolutionOptions {
-    readonly platform?: NodeJS.Platform;
-    readonly cwd: string;
-    readonly environment: Readonly<Record<string, string>>;
-    readonly nodeExecutable?: string;
-}
-/** Resolve a command without invoking a command interpreter. */
-export declare function resolveTransparentCommand(executable: string, arguments_: readonly string[], options: TransparentCommandResolutionOptions): Promise<ResolvedTransparentCommand>;

package/dist/src/foundation/transparent-terminal/command-resolution.js

@@ -1,69 +0,0 @@
-import { access, readFile } from "node:fs/promises";
-import { delimiter, extname, isAbsolute, resolve } from "node:path";
-/** Resolve a command without invoking a command interpreter. */
-export async function resolveTransparentCommand(executable, arguments_, options) {
-    const platform = options.platform ?? process.platform;
-    return platform === "win32"
-        ? await resolveWindowsCommand(executable, arguments_, options)
-        : { executable, arguments: [...arguments_], source: "exact" };
-}
-async function resolveWindowsCommand(command, commandArguments, options) {
-    const resolved = await resolveWindowsPathCommand(command, options.cwd, options.environment);
-    const selected = resolved ?? throwCommandNotFound(command);
-    if (extname(selected).toLowerCase() !== ".cmd") {
-        return { executable: selected, arguments: [...commandArguments], source: "path" };
-    }
-    return await unwrapNpmWindowsShim(selected, commandArguments, options.nodeExecutable ?? process.execPath);
-}
-async function resolveWindowsPathCommand(executable, cwd, environment) {
-    const hasPath = isAbsolute(executable) || executable.includes("/") || executable.includes("\\");
-    const roots = hasPath ? [cwd] : windowsPath(environment).split(delimiter).filter(Boolean);
-    const extension = extname(executable);
-    const extensions = extension ? [""] : windowsExecutableExtensions(environment);
-    for (const root of roots) {
-        const base = hasPath ? resolve(cwd, executable) : resolve(root.replace(/^"|"$/g, ""), executable);
-        for (const suffix of extensions) {
-            const candidate = `${base}${suffix}`;
-            if (await isFile(candidate))
-                return candidate;
-        }
-    }
-    return null;
-}
-async function unwrapNpmWindowsShim(shimPath, arguments_, fallbackNodeExecutable) {
-    const source = (await readFile(shimPath, "utf8")).replace(/^\uFEFF/, "");
-    const targetMatch = source.match(/"%_prog%"\s+"%dp0%\\([^"\r\n]+)"\s+%\*/i);
-    if (!targetMatch?.[1]) {
-        throw Object.assign(new Error(`transparent launch refuses arbitrary Windows command script ${shimPath}; configure an executable binary instead`), { code: "UNSUPPORTED_WINDOWS_COMMAND_SHIM" });
-    }
-    const shimRoot = resolve(shimPath, "..");
-    const target = resolve(shimRoot, targetMatch[1].replaceAll("\\", "/"));
-    if (!await isFile(target))
-        throw Object.assign(new Error(`npm command shim target is missing: ${target}`), { code: "ENOENT" });
-    const localNode = resolve(shimRoot, "node.exe");
-    const nodeExecutable = await isFile(localNode) ? localNode : fallbackNodeExecutable;
-    return {
-        executable: nodeExecutable,
-        arguments: [target, ...arguments_],
-        source: "npm-windows-shim",
-    };
-}
-function throwCommandNotFound(command) {
-    throw Object.assign(new Error(`spawn ${command} ENOENT`), { code: "ENOENT" });
-}
-function windowsPath(environment) {
-    return environment.Path ?? environment.PATH ?? "";
-}
-function windowsExecutableExtensions(environment) {
-    const source = environment.PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
-    return source.split(";").filter(Boolean).map(value => value.startsWith(".") ? value : `.${value}`);
-}
-async function isFile(path) {
-    try {
-        await access(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

package/dist/src/foundation/transparent-terminal/foreground-broker.d.ts

@@ -1,32 +0,0 @@
-import type { CommandResult, ForegroundTerminalLeaseId, GenerationId, NativeProcessIdentity, RequestId, SupervisorCommand, TransparentTerminalLaunchProfile, TransparentTerminalLifecycleOutcome } from "../lifecycle/index.js";
-export interface ForegroundLeaseControl {
-    command(command: SupervisorCommand): Promise<CommandResult>;
-}
-export type TransparentStopReason = "owner-disconnect" | "user-request" | "update";
-export interface TransparentChildHandle {
-    readonly processIdentity: NativeProcessIdentity;
-    readonly outcome: Promise<TransparentTerminalLifecycleOutcome>;
-    stop(reason: TransparentStopReason): Promise<TransparentTerminalLifecycleOutcome>;
-}
-export interface TransparentNativeLauncher {
-    launch(profile: TransparentTerminalLaunchProfile): Promise<TransparentChildHandle>;
-}
-export interface ForegroundBrokerRequest {
-    readonly leaseId: ForegroundTerminalLeaseId;
-    readonly generationId: GenerationId;
-    readonly ownerId: string;
-    readonly profile: TransparentTerminalLaunchProfile;
-    readonly stopRequested?: Promise<TransparentStopReason>;
-}
-export interface ForegroundBrokerResult {
-    readonly leaseId: ForegroundTerminalLeaseId;
-    readonly generationId: GenerationId;
-    readonly processIdentity: NativeProcessIdentity | null;
-    readonly outcome: TransparentTerminalLifecycleOutcome;
-}
-/**
- * Coordinates ownership around one natively attached child. Ordinary terminal
- * data never enters this object: the launcher owns native attachment and this
- * broker observes only process identity and the final lifecycle outcome.
- */
-export declare function runForegroundBroker(request: ForegroundBrokerRequest, control: ForegroundLeaseControl, launcher: TransparentNativeLauncher, createRequestId: () => RequestId): Promise<ForegroundBrokerResult>;

package/dist/src/foundation/transparent-terminal/foreground-broker.js

@@ -1,87 +0,0 @@
-import { assertNativeProcessIdentity, assertTransparentTerminalLaunchProfile } from "../lifecycle/index.js";
-/**
- * Coordinates ownership around one natively attached child. Ordinary terminal
- * data never enters this object: the launcher owns native attachment and this
- * broker observes only process identity and the final lifecycle outcome.
- */
-export async function runForegroundBroker(request, control, launcher, createRequestId) {
-    assertRequest(request);
-    await requireAccepted(control, {
-        type: "acquire-foreground-terminal-lease",
-        requestId: createRequestId(),
-        leaseId: request.leaseId,
-        ownerId: request.ownerId,
-        profile: request.profile,
-    });
-    let handle;
-    try {
-        handle = await launcher.launch(request.profile);
-        assertNativeProcessIdentity(handle.processIdentity);
-    }
-    catch (error) {
-        const outcome = {
-            kind: "spawn-error",
-            message: errorMessage(error),
-            code: errorCode(error),
-        };
-        await requireAccepted(control, {
-            type: "release-foreground-terminal-lease",
-            requestId: createRequestId(),
-            leaseId: request.leaseId,
-            processIdentity: null,
-            outcome,
-        });
-        return { leaseId: request.leaseId, generationId: request.generationId, processIdentity: null, outcome };
-    }
-    try {
-        await requireAccepted(control, {
-            type: "activate-foreground-terminal-lease",
-            requestId: createRequestId(),
-            leaseId: request.leaseId,
-            generationId: request.generationId,
-            processIdentity: handle.processIdentity,
-        });
-        const outcome = request.stopRequested
-            ? await Promise.race([handle.outcome, request.stopRequested.then(async (reason) => await handle.stop(reason))])
-            : await handle.outcome;
-        await requireAccepted(control, {
-            type: "release-foreground-terminal-lease",
-            requestId: createRequestId(),
-            leaseId: request.leaseId,
-            processIdentity: handle.processIdentity,
-            outcome,
-        });
-        return { leaseId: request.leaseId, generationId: request.generationId, processIdentity: handle.processIdentity, outcome };
-    }
-    catch (error) {
-        const outcome = {
-            kind: "broker-error",
-            message: errorMessage(error),
-            code: errorCode(error),
-        };
-        await control.command({
-            type: "release-foreground-terminal-lease",
-            requestId: createRequestId(),
-            leaseId: request.leaseId,
-            processIdentity: handle.processIdentity,
-            outcome,
-        }).catch(() => undefined);
-        throw error;
-    }
-}
-function assertRequest(request) {
-    if (!request.leaseId || !request.generationId || !request.ownerId)
-        throw new TypeError("foreground broker identities are required");
-    assertTransparentTerminalLaunchProfile(request.profile);
-}
-async function requireAccepted(control, command) {
-    const result = await control.command(command);
-    if (!result.ok)
-        throw new Error(result.error?.message ?? `supervisor rejected ${command.type}`);
-}
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function errorCode(error) {
-    return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : null;
-}

package/dist/src/foundation/transparent-terminal/index.d.ts

@@ -1,4 +0,0 @@
-export * from "./command-resolution.js";
-export * from "./foreground-broker.js";
-export * from "./main.js";
-export * from "./native-launcher.js";

package/dist/src/foundation/transparent-terminal/index.js

@@ -1,4 +0,0 @@
-export * from "./command-resolution.js";
-export * from "./foreground-broker.js";
-export * from "./main.js";
-export * from "./native-launcher.js";

package/dist/src/foundation/transparent-terminal/main.d.ts

@@ -1,9 +0,0 @@
-import { type LaunchProfileId } from "../lifecycle/index.js";
-export interface TransparentForegroundOptions {
-    readonly environment?: NodeJS.ProcessEnv;
-    readonly profileId?: LaunchProfileId;
-    readonly cwd?: string;
-    readonly executable: string;
-    readonly arguments: readonly string[];
-}
-export declare function runTransparentForeground(options: TransparentForegroundOptions): Promise<number>;

package/dist/src/foundation/transparent-terminal/main.js

@@ -1,94 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { realpath } from "node:fs/promises";
-import { resolve } from "node:path";
-import { assertLaunchProfileId } from "../lifecycle/index.js";
-import { SupervisorClient } from "../protocol/index.js";
-import { resolveProductPaths } from "../supervision/index.js";
-import { runForegroundBroker } from "./foreground-broker.js";
-import { createPlatformTransparentLauncher } from "./native-launcher.js";
-export async function runTransparentForeground(options) {
-    const environment = { ...(options.environment ?? process.env) };
-    const profileId = options.profileId ?? environment.A1_LAUNCH_PROFILE ?? "a1";
-    assertLaunchProfileId(profileId);
-    const paths = resolveProductPaths(environment);
-    const client = new SupervisorClient(environment.A1_RELEASE_ID);
-    await client.connect(paths.endpoint);
-    const ownerId = `foreground-broker-${randomUUID()}`;
-    const profile = await launchProfile(environment, options, profileId);
-    const stop = stopSignal();
-    try {
-        const result = await runForegroundBroker({ leaseId: randomUUID(), generationId: randomUUID(), ownerId, profile, stopRequested: stop.requested }, client, createPlatformTransparentLauncher(), randomUUID);
-        if (result.outcome.kind === "exited")
-            return result.outcome.exitCode;
-        if (result.outcome.kind === "signaled")
-            return 1;
-        if (result.outcome.kind === "stopped" || result.outcome.kind === "detached")
-            return 0;
-        throw Object.assign(new Error(result.outcome.message), { code: result.outcome.code ?? undefined });
-    }
-    finally {
-        stop.dispose();
-        client.close();
-    }
-}
-async function launchProfile(environment, options, profileId) {
-    const executable = options.executable;
-    const arguments_ = options.arguments;
-    const cwd = await realpath(options.cwd ?? process.cwd());
-    const terminalType = environment.TERM?.trim() || "xterm-256color";
-    return {
-        id: `${profileId}-transparent-${randomUUID()}`,
-        terminalCapability: "transparent",
-        executable,
-        arguments: arguments_,
-        cwd,
-        environment: selectedChildEnvironment(environment),
-        terminalType,
-        dimensions: terminalDimensions(environment),
-        ownerDisconnect: "stop",
-        recovery: "none",
-        surface: "none",
-        visualReconnection: "none",
-    };
-}
-function selectedChildEnvironment(environment) {
-    const selected = {};
-    for (const [name, value] of Object.entries(environment)) {
-        if (value !== undefined && !name.startsWith("A1_"))
-            selected[name] = value;
-    }
-    return selected;
-}
-function terminalDimensions(environment) {
-    const columns = positiveInteger(environment.COLUMNS) ?? 80;
-    const rows = positiveInteger(environment.LINES) ?? 24;
-    return { columns: Math.min(500, Math.max(2, columns)), rows: Math.min(300, Math.max(1, rows)) };
-}
-function positiveInteger(value) {
-    const parsed = Number(value);
-    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
-}
-function stopSignal() {
-    let resolveStop;
-    let settled = false;
-    const requested = new Promise(resolve => { resolveStop = resolve; });
-    const request = (reason) => {
-        if (settled)
-            return;
-        settled = true;
-        resolveStop(reason);
-    };
-    const onSigterm = () => request("user-request");
-    // The attached child shares foreground signal delivery. Keep the broker alive
-    // without translating or forwarding Ctrl+C.
-    const onSigint = () => undefined;
-    process.once("SIGTERM", onSigterm);
-    process.on("SIGINT", onSigint);
-    return {
-        requested,
-        dispose() {
-            process.off("SIGTERM", onSigterm);
-            process.off("SIGINT", onSigint);
-        },
-    };
-}