@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.402

package/docs/openspec-archive-automation.md

@@ -0,0 +1,124 @@
+# Automatic OpenSpec archival
+
+The archive workflow handles accepted implementation merges into `develop`, a daily 90-day catch-up, and targeted retries. It creates an OpenSpec-only PR; existing documentation auto-merge remains responsible for squash integration after real current-head CI. An archive PR being open is not a completed archive.
+
+Documentation CI installs only the pinned OpenSpec archive tool into runner temporary storage, not the repository dependency tree. Candidate validation selects that installation with `--tool-root`; the override is unavailable to publication and audit modes. The documentation job has read-only contents, PR, and Actions permissions; the existing merge owner also declares Actions read access for checking source validation.
+
+## One draft PR from planning through implementation
+
+A new implementation-bound change starts as OpenSpec-only artifacts in one draft PR, not a plan merged ahead of its implementation. Planning requests authorize no code. The agent prepares the link below while opening that draft. After explicit plan approval and an implementation request, continue in the same worktree, branch, history, and PR; reconcile approved planning refinements before their code edits and include related product documentation there too.
+
+Keep the PR draft while incomplete, then make it ready for final review. Approval to implement is not final acceptance or merge authorization. The completed PR still requires required CI, actual final-head maintainer review, and explicit manual integration. The documentation merge owner holds implementation-associated PRs and new active changes even if marked ready or their marker is removed. PR body edits trigger reconciliation and disable an excluded armed merge. Ordinary docs, standalone revisions to existing merged plans, and verified archive moves remain automatic under the exact path allowlist.
+
+## Normal implementation handoff
+
+The delivery agent adds one version-2 block to the initial draft PR description. It identifies the plan and implementation in that same PR, without `specificationPr`:
+
+````markdown
+```openspec-implementation
+{
+  "version": 2,
+  "change": "example-change",
+  "archivePreparationTasks": { "recordEvidence": "7.1", "stageArchive": "7.2" }
+}
+```
+````
+
+The minimal link is `{ "version": 2, "change": "example-change" }`. Version 2 verifies that the linked artifacts are present and identical in the accepted source and implementation merge; it never invents a separate specification PR. Omit `archivePreparationTasks` when no mechanical task mapping is needed. If used, the mapped task IDs must have exactly these descriptions:
+
+```markdown
+- [ ] 7.1 Record verified implementation acceptance and merge evidence for archive preparation.
+- [ ] 7.2 Stage and verify delta synchronization and the archive move in an OpenSpec-only candidate.
+```
+
+All implementation, tests, CI, and manual-review tasks must be completed separately before acceptance. Never combine physical review or merge authorization into these mechanical tasks. An old mixed task is a blocker, not permission to tick unperformed work.
+
+After the maintainer actually accepts the final candidate, record one authorized maintainer PR comment:
+
+````markdown
+```openspec-acceptance
+{
+  "version": 1,
+  "change": "example-change",
+  "headSha": "REPLACE_WITH_FINAL_REVIEWED_40_CHARACTER_SHA",
+  "specBaseSha": "REPLACE_WITH_REVIEWED_SPEC_BASELINE_40_CHARACTER_SHA",
+  "verdict": "accepted",
+  "implementationComplete": true,
+  "manualReview": "passed",
+  "specSyncReviewed": true,
+  "evidence": "Identify the exact candidate, applicable commands, scenarios reviewed, and actual outcomes."
+}
+```
+````
+
+The placeholders intentionally fail validation. The agent fills actual identities and reports; it must never invent a positive review. The spec baseline is an ancestor commit containing the canonical requirements against which the maintainer reviewed the deltas. It is not automatically moved to a newer baseline to conceal conflicts.
+
+The comment author needs repository write/maintain/admin authority. A newer head needs renewed acceptance; missing, edited, contradictory, revoked, stale, or known-gap records block the automatic route. Acceptance records remain version 1 and require one unambiguous current-head acceptance record. Earlier-head records are retained; same-head contradictions or a later conflicting record require explicit reconciliation before retrying. Source acceptance is copied into the archived `acceptance.md` with PR, head, merge, check-run, and comment provenance.
+
+The code PR still requires explicit manual merge authorization. After that merge, no additional archive request is needed for an eligible change. Planning-only and archive PRs never count as implemented changes. Existing `acceptance.md` files require manual reconciliation rather than being silently overwritten.
+
+## Rejection, standalone docs, and legacy migration
+
+- **New draft rejected:** if `example-change` never merged, close its PR. Neither its plan nor code lands on `develop`, and no main-branch reconciliation or completed-change archive is required. Closing alone does not authorize deleting an unmerged branch or dirty worktree; follow separate cleanup approvals.
+- **Legacy merged plan rejected:** preserve its historical merge. Obtain an explicit reconciliation disposition; do not claim successful implementation or archive it as complete.
+- **Legacy implementation continues:** keep the existing PR (for example #376 following #362), or create an isolated implementation stream only if none exists and implementation is explicitly requested. Retain the original version-1 link; the historical specification merge and ancestry are still verified. Unknown versions and version-2 links containing `specificationPr` are rejected.
+- **Standalone docs/revision:** an unassociated non-draft README/docs PR or revision of an already-present active change retains the usual CI-gated automatic path. Renaming an archive into a new active plan establishes a hold; moving a completed active change into its archive does not.
+
+Legacy link example:
+
+````markdown
+```openspec-implementation
+{ "version": 1, "change": "legacy-change", "specificationPr": 123 }
+```
+````
+
+The repository-owned [change-delivery skill](../.agents/skills/change-delivery/SKILL.md) follows these boundaries without changing external or globally installed skills. This bootstrap still needs live evidence of the new draft/approval/same-PR/refinement lifecycle, a ready-but-unimplemented plan remaining held, rejection without archival, an ordinary docs control, and accepted merge through automatic archival. Unit tests are not that evidence.
+
+## One-time publication setup
+
+Provisioning is a separate maintainer-approved operation, not performed by installing or running the script.
+
+1. Create and install a repository-scoped GitHub App for this repository, without administration permissions or ruleset bypass.
+2. Grant repository contents and pull-request read/write permissions. The workflow's ordinary token reads contents, PR metadata, and Actions validation; the App token is restricted to publication and status comments.
+3. Set repository Actions secrets `OPENSPEC_ARCHIVE_APP_ID` and `OPENSPEC_ARCHIVE_APP_PRIVATE_KEY`. Do not paste keys into PRs, source, reports, or acceptance evidence.
+4. Verify trusted default-branch deployment and run a read-only audit before the isolated live lifecycle test.
+5. Record a real App-authored archive PR triggering ordinary CI, automatic protected squash integration, and exact-head branch cleanup before accepting live operation.
+
+The script mints and revokes a short-lived installation token. It does not publish with `GITHUB_TOKEN`: GitHub can suppress the resulting PR events, leaving a PR without required CI. Missing App setup blocks mutation and does not relax protection. No extra merge owner, status spoofing, or automatic repository-settings application is introduced.
+
+## Audit and retry
+
+From a dependency-installed checkout, run a read-only audit using existing GitHub CLI authentication:
+
+```bash
+GH_TOKEN="$(gh auth token)" node scripts/governance/reconcile-openspec-archive.mjs --dry-run
+```
+
+To inspect one implementation PR, including one older than the scheduled window:
+
+```bash
+GH_TOKEN="$(gh auth token)" node scripts/governance/reconcile-openspec-archive.mjs --dry-run --pr 123
+```
+
+These commands do not launch the product UI and do not require a product build. They never mutate remote refs, PRs, comments, source specs/tasks, or persistent scan checkpoints. Disposable local staging verifies the proposed archive; the audit report is written to `.artifacts/openspec-archive/report.json`.
+
+For authorized publication or retry, use the **OpenSpec archive** Actions dispatch. Keep `dry_run` enabled for inspection. Set a specific PR and `retry_closed` only when deliberately authorizing replacement of its closed/unmerged archive PR. Closing an archive PR otherwise stops automatic recreation.
+
+## Outcomes and bounds
+
+- **eligible**: evidence and isolated staging passed; dry-run did not publish.
+- **blocked**: a named evidence/task/spec/setup/ownership problem requires attention.
+- **pending**: archive PR exists; current-head CI and automatic merge are not yet complete.
+- **already-archived**: merged archive identity and retained evidence were verified.
+- **deferred**: the queue or scan budget prevented work this run.
+- **unlinked**: no explicit implementation metadata; not presumed accepted or archived.
+
+Only one automatic archive PR is outstanding at a time. Runs never wait on CI. A failing pending PR blocks the queue until fixed or explicitly closed; neither a rerun nor a successful old head bypasses its required checks. Human-edited branches and unrelated paths are preserved.
+
+Catch-up scans a fixed 90-day window, up to 500 PRs per pass, with a 10-minute workflow budget and one publication per run. A small versioned cursor resumes unfinished windows; reports and cursors are retained for 14 days. Missing/expired cursors restart a bounded scan, not an assumed complete audit. Older PRs remain targetable. Exceptionally dense search buckets or incomplete GitHub search results are explicit blockers rather than silent truncation.
+
+Known-gap archival remains a separately authorized manual path. The existing backlog is not bulk-approved when automation starts. Local worktree cleanup remains with the local agent after verified integration and a clean-tree check.
+
+## Disable or roll back
+
+Disable the **OpenSpec archive** workflow or revoke its App publication credentials. Preserve active changes and open archive PRs for review. Do not delete documents, undo synchronized specs, or modify repository rulesets merely to stop automation. Existing documentation auto-merge and remote branch cleanup remain independently governed.

package/docs/repository-governance-live-acceptance.md

@@ -0,0 +1,77 @@
+# Repository governance live acceptance
+
+## Implementation lifecycle
+
+- PR #165 was manually squash-merged by `timurproko` from validated head
+  `45aab61c5e4568d3d26dc970f76e9ec86918f323` to `develop` commit
+  `e4cdc67555e9f25d03f251be19baa8fc446ac313`.
+- Cleanup run `33185942656` used trusted `develop` policy with `contents: write` only
+  and reported `already-absent`; the implementation branch remained absent.
+- The read-only live governance report matched every declared field after merge.
+
+## Acceptance defect and correction
+
+- Initial OpenSpec probe PR #166 automatically squash-merged validated head
+  `c30c0a091a6a6a727057befcdd775422988be382` to
+  `f8d60080cfd9925b33a19a5d40c707637ac00b08`, but GitHub suppressed the recursive
+  close-event workflow because integration was authored with `GITHUB_TOKEN`.
+- Its exact unchanged branch remained, proving the first implementation incomplete.
+  The branch was manually deleted only after its expected SHA and lack of an open PR
+  were reverified.
+- Corrective PR #167 was manually squash-merged from validated head
+  `3a09042386df2501accc1eec3b424b94ae84daa4` to
+  `e8d639985a811f01cd5daeb027db5069d1724596`. Cleanup run `33188206793`
+  succeeded with `already-absent`.
+
+## Automatic OpenSpec acceptance
+
+- PR #168 contained only `openspec/**` paths.
+- Development validation run `33188285639` passed for exact head
+  `6678d9237ca7c4109beaed0d97d5fb1183fe5f97` without product tests.
+- `github-actions` automatically squash-merged it to
+  `c2fa730a4b070f9f6717329c24158def5c766f11`.
+- Trusted documentation reconciliation run `33188329123` reported `deleted` for the
+  same expected head SHA, and the remote branch was verified absent.
+
+## Automatic root README acceptance
+
+- PR #169 changed only root `README.md`.
+- Development validation run `33188400573` passed for exact head
+  `165c5159031d80059c4d93c36c6d10113ec7ba8e` without product tests.
+- `github-actions` automatically squash-merged it to
+  `0180088a42b7cdacaf84ec66ff5a87be1a697155`.
+- Trusted documentation reconciliation run `33188434277` reported `deleted` for the
+  same expected head SHA, and the remote branch was verified absent.
+
+## Mixed-path manual acceptance
+
+PR #170 combined this evidence file outside the exact automatic allowlist with an
+OpenSpec task update. Development validation run `33188542485` passed for exact head
+`b95bdbf08ad6db76c5fab2bfca254026a3c4bcc1` without product tests. Auto-merge
+remained disabled and the pull request remained open and mergeable until `timurproko`
+manually squash-merged it to `6ab1e4d29b9edec8501bac774bc755e66240ea40`.
+Close-event cleanup run `33188616709` reported `already-absent`, and the remote branch
+was verified absent after the explicit merge.
+
+## Automatic maintained-documentation acceptance
+
+- Implementation PR #180 was manually squash-merged after required validation from
+  head `8f40bfaaa5e8410e77b1c9cc0667c62bc4c62d4b` to
+  `45a59a7b696d537a4dc8fe62000a60c20e504ab2`.
+- PR #181 changes only this maintained `docs/**` file and is the live acceptance
+  probe for the expanded allowlist.
+- Acceptance requires current-head documentation validation, automatic squash
+  integration without maintainer merge action, and exact-head remote branch cleanup.
+  Exact run and merge evidence is recorded with the completed OpenSpec change.
+
+## Advanced-ref refusal and final policy state
+
+The isolated mocked-GitHub fixture executed the production shared reconciler with
+expected SHA `1111111111111111111111111111111111111111` and advanced live SHA
+`2222222222222222222222222222222222222222`. It returned `refused` with reason
+`live branch advanced after merge` and issued zero DELETE requests. The bounded
+record is archived as `evidence/advanced-ref-refusal.json`.
+
+The final read-only live report matched all declared repository settings, Actions
+policy, security capabilities, environments, protected refs, complete rulesets, and
+workflow inventory with zero differences. No policy apply was run.

package/package.json

@@ -1,17 +1,15 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.3b54f21",
+  "version": "0.1.8-dev.402",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
+  "privateLaunchContract": "neutral-launch-v1",
   "packageManager": "npm@11.13.0",
   "bin": {
     "a1": "bin/cli.js"
   },
   "imports": {
-    "#pi-tui": [
-      "./node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-tui/dist/index.js",
-      "@earendil-works/pi-tui"
-    ]
+    "#pi-tui": "./bin/pi-tui.js"
   },
   "files": [
     "bin",
@@ -24,44 +22,59 @@
     "node": ">=22.19.0 <25"
   },
   "scripts": {
+    "postinstall": "node bin/sync-pi-tui-proxy.js",
     "clean": "node scripts/clean.mjs",
-    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/build-process-guardian.mjs",
-    "build:process-guardian": "node scripts/build-process-guardian.mjs",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/development/build-process-guardian.mjs && node scripts/release/generate-runtime-payload-inventory.mjs",
+    "build:process-guardian": "node scripts/development/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:architecture": "node scripts/governance/check-architecture.mjs && node scripts/governance/check-product-identity-boundaries.mjs && node scripts/governance/check-package-identity.mjs && node scripts/governance/check-pinned-pi-source-ledger.mjs && node scripts/governance/check-terminal-host-provenance.mjs",
+    "check:names": "node scripts/governance/product-identifier-policy.mjs --check",
+    "check:names:changed": "node scripts/governance/product-identifier-policy.mjs --check --selection .artifacts/validation/impact.json",
+    "check:code-documentation": "node scripts/governance/check-code-documentation.mjs --mode full",
+    "check:code-documentation:changed": "node scripts/release/run-changed-documentation.mjs",
+    "select:validation-impact": "node scripts/release/select-validation-impact.mjs",
+    "check:customization-ready": "node scripts/governance/check-owned-ui-customization-prerequisites.mjs",
+    "check:deprecated": "node scripts/governance/check-deprecated-dependencies.mjs",
+    "check:docs-governance": "node scripts/governance/check-docs-governance.mjs",
+    "check:repository-governance": "node scripts/governance/check-github-repository-governance.mjs --check",
     "branches:prune": "node scripts/prune-merged-branches.mjs",
     "check": "npm run test:fast",
-    "release": "node scripts/release.mjs",
+    "develop": "node scripts/development/develop.mjs",
+    "release": "node scripts/release/release.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-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",
+    "test:fast": "node scripts/release/run-validation-tier.mjs typecheck documentation-changed fast",
+    "test:scope": "node scripts/release/run-validation-tier.mjs",
+    "test:full": "node scripts/release/run-validation-tier.mjs full-release",
+    "test:release": "node scripts/release/run-release-gates.mjs",
+    "test:terminal-host": "node scripts/development/run-terminal-host-probe.mjs",
+    "test:pi-engine-conformance": "vitest run test/integrations/pi/engine/conformance.test.ts test/integrations/pi/engine/runtime-integration.test.ts test/integrations/pi/engine/session-integration.test.ts",
+    "report:pi-engine-conformance": "npm run build --silent && node scripts/pi/run-pi-engine-conformance.mjs",
+    "report:rendering-stability": "tsx scripts/pi/report-rendering-stability.ts",
+    "report:input-responsiveness": "tsx scripts/pi/report-input-responsiveness.ts",
     "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/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",
+    "update:pi-component-parity": "tsx scripts/pi/update-pi-component-parity.ts",
+    "update:pi-event-frame-parity": "tsx scripts/pi/update-pi-event-frame-parity.ts",
+    "proof:terminal-host": "node scripts/development/run-terminal-host.mjs",
+    "start": "npm run build && node scripts/development/dev-launch.mjs",
+    "start:pi": "npm run build && node scripts/development/dev-launch.mjs pi",
+    "prepack": "node scripts/release/prepack-gate.mjs",
     "prepublishOnly": "npm run test:release",
     "prepare": "npm run build",
-    "update:pi-settings-metadata": "node scripts/update-pi-settings-metadata.mjs"
+    "update:pi-settings-metadata": "node scripts/pi/update-pi-settings-metadata.mjs"
   },
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",
     "@earendil-works/pi-tui": "0.84.2",
+    "@silvia-odwyer/photon-node": "0.3.4",
+    "chalk": "5.6.2",
     "cross-spawn": "7.0.6",
     "grok-mermaid": "0.2.2",
-    "semver": "7.8.5"
+    "semver": "7.8.5",
+    "undici": "8.9.0"
   },
   "devDependencies": {
+    "@fission-ai/openspec": "1.11.0",
+    "@lezer/python": "1.1.19",
     "@types/cross-spawn": "6.0.6",
     "@types/node": "24.2.1",
     "@types/semver": "7.8.0",
@@ -70,7 +83,8 @@
     "node-pty": "1.1.0",
     "tsx": "4.20.3",
     "typescript": "5.9.2",
-    "vitest": "3.2.7"
+    "vitest": "3.2.7",
+    "yaml": "2.9.1"
   },
   "keywords": [
     "cli",
@@ -87,5 +101,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard": "^0.3.9"
   }
 }

package/dist/src/cli/capabilities.d.ts

@@ -1,15 +0,0 @@
-/**
- * `pi` and `sandbox` exist to compare A1 against pinned Pi and to try resources
- * against an isolated profile. Both are development instruments rather than
- * product, so a stable release does not carry them: what a released `a1` exposes
- * is the product plus its maintenance and package commands.
- *
- * Which build this is comes from its own version. A prerelease version is a
- * `next`-channel build, which is where that work happens; a release version is
- * not. Nothing to configure, and no way for a released build to be talked into it.
- */
-export interface CliCapabilities {
-    readonly developmentProfiles: boolean;
-}
-export declare function cliCapabilities(version: string): CliCapabilities;
-export declare function isPrereleaseVersion(version: string): boolean;

package/dist/src/cli/dispatch.js

@@ -1,142 +0,0 @@
-import { interactiveLaunchIntent } from "../features/launch/index.js";
-import { PRODUCT_TEXT } from "../product-identity.js";
-export function cliUsage(capabilities) {
-    return PRODUCT_TEXT.usage([
-        "",
-        ...(capabilities.developmentProfiles ? ["pi", "sandbox"] : []),
-        "version",
-        "update [self|<source>|--extensions|--models]",
-        "update:next",
-        "update:<commit>",
-        "install <source>",
-        "remove <source>",
-        "list",
-    ]);
-}
-const PROFILE_WORDS = new Set(["pi", "sandbox"]);
-export async function dispatchCli(arguments_, handlers, output, capabilities) {
-    const command = parseCliCommand(arguments_, capabilities);
-    if (command.kind === "error") {
-        output.stderr(`${command.message}\n${cliUsage(capabilities)}\n`);
-        return 2;
-    }
-    if (command.kind === "launch")
-        return await handlers.launch(interactiveLaunchIntent(command.profileId));
-    if (command.kind === "version")
-        return await handlers.version();
-    if (command.kind === "packages")
-        return await handlers.packages(command.request);
-    return await handlers.update(command.channel, command.target);
-}
-export function parseCliCommand(arguments_, capabilities) {
-    if (arguments_.length === 0)
-        return { kind: "launch", profileId: "a1" };
-    const [command, ...rest] = arguments_;
-    if (capabilities.developmentProfiles && (command === "pi" || command === "sandbox")) {
-        return withoutArguments(rest, { kind: "launch", profileId: command });
-    }
-    if (command === "version")
-        return withoutArguments(rest, { kind: "version" });
-    if (command !== undefined && command.startsWith("update:"))
-        return parseColonUpdate(command.slice("update:".length), rest);
-    if (command === "update")
-        return parseUpdate(rest);
-    if (command === "install" || command === "remove" || command === "uninstall") {
-        return parseSourceCommand(command === "install" ? "install" : "remove", rest);
-    }
-    if (command === "list")
-        return withoutArguments(rest, { kind: "packages", request: { verb: "list", source: null } });
-    if (command === "ui")
-        return { kind: "error", message: `The ui subcommand was removed; run bare ${PRODUCT_TEXT.commandName} for the owned UI.` };
-    if (command === "agent")
-        return { kind: "error", message: `Bare ${PRODUCT_TEXT.commandName} is the ${PRODUCT_TEXT.displayName} agent experience; there is no agent subcommand.` };
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown command: ${command ?? ""}`) };
-}
-/**
- * What follows the colon says which build to move to. `next` is the newest
- * preview; anything else names one outright, by the commit it was built from or by
- * its full version — a preview is published as `<version>-dev.<commit>`, so the
- * commit alone is enough to find it.
- */
-function parseColonUpdate(suffix, rest) {
-    if (rest.length > 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update takes what to move to after the colon, and nothing else.") };
-    if (suffix === "next")
-        return { kind: "update", channel: "next" };
-    if (suffix.length === 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`update: needs a preview after the colon, as in ${PRODUCT_TEXT.commandName} update:next.`) };
-    if (!/^[0-9a-z][0-9a-z.+-]*$/i.test(suffix)) {
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unusable preview: ${suffix}`) };
-    }
-    return { kind: "update", channel: "next", target: suffix };
-}
-/**
- * `update` carries both meanings pinned Pi gives it: itself by default, and the
- * profile's packages when a target says so. Pi is refused as a target because A1
- * certifies each release against one pinned Pi, so moving Pi underneath it would
- * invalidate what was certified.
- */
-function parseUpdate(rest) {
-    if (rest.length === 0)
-        return { kind: "update", channel: "stable" };
-    if (rest.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update accepts one target.") };
-    const [target] = rest;
-    if (target === "self")
-        return { kind: "update", channel: "stable" };
-    if (target === "pi") {
-        return {
-            kind: "error",
-            message: PRODUCT_TEXT.diagnostic(`pins the Pi version it was certified against; run ${PRODUCT_TEXT.commandName} update to move ${PRODUCT_TEXT.displayName} itself.`),
-        };
-    }
-    // A release channel is spelled with the colon. Taking the bare word as a package
-    // source would turn a near miss into a confident search for a package nobody has.
-    if (target === "next" || target === "stable") {
-        const form = target === "next" ? `${PRODUCT_TEXT.commandName} update:next` : `${PRODUCT_TEXT.commandName} update`;
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`selects a release channel with a colon; run ${form}.`) };
-    }
-    if (target === "--extensions")
-        return { kind: "packages", request: { verb: "update", source: null } };
-    if (target === "--models")
-        return { kind: "packages", request: { verb: "refresh-models", source: null } };
-    if (target === undefined || target.startsWith("-"))
-        return unknownOption(target ?? "", "update");
-    if (PROFILE_WORDS.has(target))
-        return profileRejection("update");
-    return { kind: "packages", request: { verb: "update", source: target } };
-}
-function parseSourceCommand(verb, rest) {
-    const flag = rest.find(argument => argument.startsWith("-"));
-    if (flag !== undefined)
-        return unknownOption(flag, verb);
-    if (rest.length === 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
-    if (rest.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} accepts one package source.`) };
-    const [source] = rest;
-    if (source === undefined)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
-    if (PROFILE_WORDS.has(source))
-        return profileRejection(verb);
-    return { kind: "packages", request: { verb, source } };
-}
-function withoutArguments(rest, command) {
-    if (rest.length === 0)
-        return command;
-    const [argument] = rest;
-    if (argument !== undefined && (PROFILE_WORDS.has(argument) || argument.startsWith("--profile")))
-        return profileRejection("list");
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic("commands do not accept additional arguments.") };
-}
-function profileRejection(verb) {
-    return {
-        kind: "error",
-        message: PRODUCT_TEXT.diagnostic(`manages packages in its own profile, so ${verb} takes no profile; Pi manages Pi's own profile.`),
-    };
-}
-function unknownOption(option, verb) {
-    if (option.startsWith("--profile"))
-        return profileRejection(verb);
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown option for ${verb}: ${option}`) };
-}

package/dist/src/cli/version-stats.js

@@ -1,72 +0,0 @@
-import { spawn } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import crossSpawn from "cross-spawn";
-import { valid as validSemver } from "semver";
-import { PRODUCT_TEXT } from "../product-identity.js";
-const defaultOutput = {
-    stdout(message) { process.stdout.write(message); },
-    stderr(message) { process.stderr.write(message); },
-};
-export async function runVersionStats(options) {
-    const output = options.output ?? defaultOutput;
-    const runner = options.runner ?? createVersionProcessRunner();
-    let installed;
-    try {
-        const manifest = JSON.parse(await readFile(resolve(options.packageRoot, "package.json"), "utf8"));
-        installed = parseVersion(manifest.version, "installed package");
-    }
-    catch (error) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its installed version: ${message(error)}`)}\n`);
-        return 1;
-    }
-    const remote = await queryDistTags(runner);
-    output.stdout(`Installed: ${installed}\nRelease:   ${remote.release ?? "unavailable"}\nNext:      ${remote.next ?? "unavailable"}\n`);
-    if (remote.error)
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not resolve npm dist-tags: ${remote.error}`)}\n`);
-    return 0;
-}
-async function queryDistTags(runner) {
-    let result;
-    try {
-        result = await runner("npm", ["view", PRODUCT_TEXT.packageName, "dist-tags", "--json"]);
-    }
-    catch (error) {
-        return unavailable(message(error));
-    }
-    if (result.code !== 0)
-        return unavailable(`npm exited with status ${result.code ?? "unknown"}`);
-    try {
-        const metadata = JSON.parse(result.stdout);
-        if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata))
-            throw new TypeError("npm returned a non-object dist-tags value");
-        const tags = metadata;
-        const release = parseVersion(tags.latest, "npm latest");
-        const next = tags.next === undefined ? null : parseVersion(tags.next, "npm next");
-        return { release, next, error: null };
-    }
-    catch (error) {
-        return unavailable(message(error));
-    }
-}
-function unavailable(error) {
-    return { release: null, next: null, error };
-}
-function createVersionProcessRunner() {
-    return async (command, arguments_) => await new Promise((resolvePromise, rejectPromise) => {
-        const child = process.platform === "win32"
-            ? crossSpawn(command, [...arguments_], { stdio: ["ignore", "pipe", "ignore"] })
-            : spawn(command, [...arguments_], { stdio: ["ignore", "pipe", "ignore"] });
-        const stdout = [];
-        child.stdout?.on("data", chunk => stdout.push(Buffer.from(chunk)));
-        child.once("error", rejectPromise);
-        child.once("close", code => resolvePromise({ code, stdout: Buffer.concat(stdout).toString("utf8") }));
-    });
-}
-function parseVersion(value, source) {
-    const parsed = typeof value === "string" ? validSemver(value) : null;
-    if (!parsed)
-        throw new Error(`${source} did not provide a valid semantic version`);
-    return parsed;
-}
-function message(error) { return error instanceof Error ? error.message : String(error); }

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

@@ -1,48 +0,0 @@
-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;
-    readonly engine?: AgentEnginePort;
-    readonly presentationFactory?: (root: PresentationComponentPort, terminal: PresentationTerminalPort) => PresentationRuntimePort;
-    readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
-}
-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;