@tryinget/pi-agent-registry 0.3.1 → 0.3.2

package/README.md

@@ -1,11 +1,11 @@
 ---
-summary: "Overview and operator contract for pi-agent-registry manifest inspection, immutable fleet lint, and the Phase-2 exact-task read-only dispatch contract."
+summary: "Overview and operator contract for pi-agent-registry manifest inspection, immutable fleet lint, and Phase-2 dispatch / Phase-3 visible admission contracts."
 read_when:
   - "Starting work in this package workspace."
-  - "Using agent_registry, pi-agent-registry-lint, dispatch_agent, or the agent manifest convention."
+  - "Using agent_registry, pi-agent-registry-lint, dispatch_agent, standing_agent_spawn, or the agent manifest convention."
 system4d:
-  container: "Pi extension and CLI for standing-agent manifest/fleet observation and the Phase-2 dispatch contract."
-  compass: "Make fleet contract drift visible and bind one provable read-only dispatch without owning lifecycle or spawn machinery."
+  container: "Pi extension and CLI for standing-agent manifest/fleet observation and bounded dispatch/visible admission contracts."
+  compass: "Make fleet contract drift visible and bind one provable read-only dispatch without owning lifecycle or transport machinery."
   engine: "Discover every candidate -> capture committed bytes -> lint deterministically -> authorize one exact task -> dispatch read-only through ASC."
   fog: "A green tool run can be mistaken for a healthy or authorized fleet, and one settled dispatch can be mistaken for general standing-agent enablement."
 ---
@@ -14,16 +14,16 @@ system4d:
 
 Standing-agent registry for Pi: reads `ai-society.agent/1` manifests for
 inspection, emits a bounded, immutable-observation fleet lint report, and owns
-the Fleet Phase-2 dispatch contract. It does not own agent creation,
-lifecycle, role acceptance, or execution machinery — spawn/session/capacity
-stay ASC-owned.
+the Fleet Phase-2 dispatch and Phase-3 visible admission contracts. It does not
+own agent creation, lifecycle, role acceptance, or transport machinery. Phase-2
+execution stays ASC-owned; Phase-3 Ghostty transport stays little-helpers-owned.
 
-Status: **Fleet Phase 2 (AK 5132)**. Manifest/template/profile contracts and
-fleet lint are converged (Phase 1), and `dispatch_agent` now executes exactly
-one read-only standing-agent dispatch per `(agent, exact AK task)` pair with an
-immutable receipt and one typed AK evidence row. Visible Ghostty standing
-agents, lifecycle-v2 permit binding, and orchestrator fleet integration
-remain later fleet phases.
+Status: **Fleet Phase 3 (AK 5133), locally implemented and live-dogfood verified**.
+Phase-2 (AK 5132) read-only ASC dispatch is unchanged. Phase 3 adds one clean
+visible standing-agent TUI admission for an exact claimed task, not lifecycle
+authority. The real TUI driver → real child TUI proof and passing package/release
+gates are recorded below. AK owns closeout. This is not a published-feature
+claim; AK 5134 remains separate.
 
 ## Operator surfaces
 
@@ -40,6 +40,9 @@ remain later fleet phases.
 - `dispatch_agent` — the Fleet Phase-2 exact-task read-only contract (see
   below); fails closed with `confirmed_no_effects` before any ASC identity,
   capacity, session, or spawn effect exists.
+- `standing_agent_spawn` — Fleet Phase-3 exact-task clean visible admission
+  through the little-helpers Ghostty transport; no automatic retry or AK
+  evidence recording (see below).
 - `/agents` — concise operator listing.
 
 ## Fleet layout
@@ -195,6 +198,110 @@ records AK evidence; an undetectable modify-and-restore interval is not
 claimed absent. The dispatch does not authenticate the calling session as the
 AK claimant — lifecycle-v2 permit binding (Fleet Phase 4) tightens that.
 
+## Phase-3 clean visible admission (AK 5133)
+
+`standing_agent_spawn { agent, task, objective, parentPeerTarget, reportBack?, cwd? }`
+composes one clean Pi TUI session in a Ghostty tab/window. `task` is an exact
+positive AK task id; `objective` is nonblank, bounded to 32 KiB UTF-8, and
+read-only — never an unbound standby brief. `reportBack` defaults to
+`intercom` and requires an exact `session-<UUID>` controller target, not
+`parent`/`active` aliases. `manual` and `none` may omit `parentPeerTarget`.
+`cwd` defaults to the origin repository root and must remain within that
+same Git repository.
+
+Admission gates and composition:
+
+1. Reject malformed requests, recursive standing-agent children, unavailable
+   version-1 transport, unknown agents, mutation tools, and any manifest
+   extensions. Declared tools must be a nonempty subset of `read,bash`;
+   `intercom` is an explicit added communication instrument, recorded
+   separately from declared tools.
+2. Observe the origin Git repository and authorize `ak task show`: the exact
+   task must be origin-repo-bound, claimed, and carry a live lease. This does
+   not authenticate the caller as the AK claimant.
+3. Require a clean agent repository and agreement between cached, freshly
+   parsed, committed, and current manifest/persona inputs. Compose the persona
+   plus advisory scope, selected skills, model, and manifest thinking request;
+   recheck these inputs and origin/agent stability around transport admission.
+4. Use `--offline --no-extensions --no-skills --no-prompt-templates`, then
+   explicit `--extension` paths for approved locally installed
+   `@tryinget/pi-peer-messaging` intercom and `@tryinget/pi-little-helpers`
+   session-presence entrypoints, and explicit `--skill` selections. No ambient
+   extension/skill discovery or controller conversation is inherited. Normal
+   cwd-bound AGENTS context is retained; this is not an empty-policy session.
+   `--offline` is a Pi startup flag, not network isolation: model/intercom
+   communication still occurs. Installed Pi supplies builtin `zai` (including
+   the dogfood model `zai/glm-5.3`); no ambient provider extension is needed.
+   Unsupported provider/bootstrap shapes fail closed.
+5. Persist an exclusive per-`(agent, task)` reservation before transport,
+   then reread the exact task/lease and recheck inputs, bootstrap entry bytes,
+   and origin/agent observations immediately before launch. Reservations are
+   scoped to the resolved visible-receipts directory, not fleet-global.
+6. Delegate to `@tryinget/pi-little-helpers/sidequest-launch` only when
+   `STANDING_AGENT_TRANSPORT_VERSION === 1` and `launchPiQuestSession` exists.
+   Registry owns composition/admission/receipts, not Ghostty or session machinery.
+   Publish a write-once `pi-agent-registry.visible-launch-receipt/1` receipt
+   (`0o400`, canonical self-digest, hard-link publication) after transport
+   observation; post-launch drift remains indeterminate rather than clean proof.
+
+**Never retry automatically**, including `confirmed_no_effects`, reservation
+failure, cancellation, crash, receipt-publication failure, or indeterminate
+transport. Existing, corrupt, or partial reservations block admission and are
+never automatically released. Supervise the returned run id; any further
+attempt requires explicit owner disposition. Phase-2's three-attempt policy
+is not a Phase-3 retry policy.
+
+For intercom mode, the child must send one correlated `PEER_ACK` before any
+file/context work, stop visibly with `ACK_FAILED` if sending fails, and send
+one correlated `PEER_FINAL` when the bounded objective ends, then stop.
+Admission is **not** session-start, ACK, read-only lifetime, task consumption,
+or completion proof. Receipt fields for startup/ACK/completion remain
+`unproven` even when separate live evidence exists. The launcher writes no
+AK evidence; the parent owns reality-test evidence and closeout.
+
+Limits: `bash` and scope/read-only instructions are advisory, not a sandbox.
+Launch-window Git observations exclude ignored files, .git internals, external
+surfaces, and modify-and-restore intervals. Bootstrap hashes cover approved
+package manifests and entry files only, not settings/auth/models or transitive
+import integrity. Skill selection/materialization is not whole-runtime
+immutability. Manifest thinking is the **request**, not a guarantee of the
+runtime level: Pi clamps to model-supported levels; live `medium` requested
+became `high` on `zai/glm-5.3`.
+
+### Local evidence and release boundary (2026-09-07)
+
+Real TUI driver → real child TUI proof, with immutable launch receipt,
+independent runtime assertion output and bounded session observation:
+[Phase-3 dogfood](docs/project/2026-09-07-fleet-phase3-dogfood.md).
+AK evidence/task state remains authoritative.
+
+- Run: `standingagent-mtqmbq5w-aeaf6023`; agent revision:
+  `dc354723482f0470ad287d1de3e067a72cd99a85`.
+- Receipt: `visible-agent-adoption-steward.20260907T022519Z.8fb48fd0.launch-receipt.json`;
+  SHA-256: `6a37b218e3ea7dff14ec0a13e8230920585ddcbf83598d5d949d62828adffd15`.
+- Child session: `01a079af-2ef4-762c-8bfc-228d0b411d4a`; observed PID
+  `189076`, `terminalBound` on `/dev/pts/11`, Ghostty surface
+  `0x516815b20d7e09a3`.
+- Ghostty build: `origin-main492300cad`, actual version `1.3.2-main`;
+  this does **not** prove a literal 1.4 release.
+- Correlated ACK `cce92533-53a7-49d0-bc42-0b808408aafe` and FINAL
+  `44cee2a7-9695-42f8-a76e-d4a08b000752` received; no duplicate protocol.
+  Child inspected four files read-only; no file or AK writes observed.
+- Registry check: **134/134**; little-helpers check: **430/430**; both full
+  release checks pass, including installed-tarball smoke. The stale real-fleet
+  baseline was explicitly refreshed after independent HEAD-only reproduction:
+  engineering-core docs-only revision `51fc387` → `9225dd6`, unchanged profile
+  bytes, fleet revisions, diagnostics and counts. Assertions were not weakened.
+- The new standing-agent reality assertion passes. The broader all-controller
+  observer check still detects an unrelated live process naming retired Ghostty
+  `9d8fbd15`; this task did not restart other sessions to hide that drift.
+
+The version-1 export exists in local little-helpers **0.9.0 source**, not a
+proven published release. Its next release must ship `./sidequest-launch`
+and the version marker before registry publication can claim Phase 3. A packed
+registry resolving older npm helpers fails closed `visible_transport_unavailable`.
+See [dependency posture](docs/engineering.local.md#package-local-deltas-on-the-pi-ts-lane).
+
 ## Environment
 
 | Variable | Meaning |
@@ -203,6 +310,7 @@ AK claimant — lifecycle-v2 permit binding (Fleet Phase 4) tightens that.
 | `PI_AGENT_REGISTRY_EC_PROFILES` | engineering-core `skills/profiles.json` |
 | `PI_AGENT_REGISTRY_USER_SKILLS` | mutable user fallback for runtime extras; fleet lint does not call it immutable |
 | `PI_AGENT_REGISTRY_DISPATCH_RECEIPTS_DIR` | explicit dispatch-receipts directory (default `<pi-agent-dir>/dispatch-receipts`) |
+| `PI_AGENT_REGISTRY_VISIBLE_LAUNCH_RECEIPTS_DIR` | Phase-3 receipts and persistent pair reservations (default `<pi-agent-dir>/visible-launch-receipts`) |
 
 ## Validation
 
@@ -219,7 +327,9 @@ smoke, and the Phase-2 dispatch contract: AK authorization matrix,
 write-once/tamper-evident receipts, settled-pair re-dispatch rejection, the
 three-attempt bound, ledger rename-integrity, read-only violation observation,
 recursion guard, ASC effect-receipt-first disposition derivation, and ASC
-request composition.
+request composition. Phase-3 coverage adds explicit bootstrap/argv composition,
+exact-task rechecks, drift/cancellation gates, durable pair reservation,
+transport capability gating, and immutable admission receipts.
 
 Live dogfood (2026-08-31, AK 5132): `agent-adoption-steward` dispatched for
 task 5132 through a fresh one-shot Pi session. Attempt 1 failed closed at child

package/docs/engineering.local.md

@@ -77,13 +77,22 @@ approval, Pi runtime install/reload proof, or monorepo owner authority.
 
 - Runtime baseline: Node 22+ running TypeScript sources directly; the
   package ships TS sources and has no dist build of its own.
-- Dependency posture: ASC is a semver-exact runtime dependency (`0.5.2`)
-  resolved from the npm registry. It is deliberately not bundled: npm 12
-  refuses to pack a package whose `overrides` (the `fast-xml-parser`
-  security floor) affect a bundled subtree (EBUNDLEOVERRIDE), and ASC
-  `0.5.2` itself has zero runtime dependencies, so consumers resolve it
-  from the registry while the repo's own lock pins the integrity-checked
-  tarball. The packed manifest contains no `file:` runtime dependency.
+- Dependency posture: ASC and little-helpers are local runtime links in the
+  workspace (`file:../pi-autonomous-session-control` and
+  `file:../pi-little-helpers`), not the former npm-only ASC `0.5.2` pin.
+  The shared `pi-interaction/scripts/prepare-publish-manifest.mjs` prepack /
+  postpack hooks temporarily rewrite local runtime dependencies to the linked
+  packages' exact versions for publication and restore the workspace manifest.
+  Runtime `typebox` is pinned separately; the packed manifest must contain no
+  `file:` runtime dependency. The dependencies are not bundled; the existing
+  `fast-xml-parser` security override is retained.
+- Publish capability is separate from version rewriting: Phase 2 requires
+  ASC's execution exports; Phase 3 requires little-helpers'
+  `./sidequest-launch` export with `STANDING_AGENT_TRANSPORT_VERSION === 1`.
+  That export is in current local little-helpers `0.9.0` source; the next
+  helpers release must ship it. A packed registry with older npm helpers
+  fails closed `visible_transport_unavailable`. Do not describe local tests
+  or successful packing as a published Phase-3 feature.
 - Tests intentionally read live workspace fixtures (the real steward agent
   repo and the real engineering-core `profiles.json`) to keep the
   convention honest against the fleet, not just against synthetic data.

package/docs/project/2026-08-27-agent-registry.md

@@ -1,29 +1,32 @@
 ---
-summary: "Design record for pi-agent-registry runtime inspection, Fleet Phase-1 immutable lint, and the Phase-2 exact-task read-only dispatch contract."
+summary: "Design record for pi-agent-registry runtime inspection, Fleet Phase-1 immutable lint, and Phase-2 dispatch / Phase-3 visible admission contracts."
 read_when:
-  - "Changing manifest loading, fleet discovery/lint, immutable observations, or dispatch posture."
+  - "Changing manifest loading, fleet discovery/lint, immutable observations, or dispatch/visible admission posture."
   - "Onboarding to the standing-agent fleet contract implementation."
 system4d:
   container: "Pi-side read-only registry and fleet observation package."
   compass: "Converge owner interfaces without absorbing lifecycle or execution authority."
-  engine: "Capture committed bytes -> lint every candidate -> report stable diagnostics -> keep dispatch disabled."
+  engine: "Capture committed bytes -> lint every candidate -> report stable diagnostics -> authorize bounded dispatch/admission."
   fog: "Mutable paths and a green process exit can be mistaken for immutable fleet health."
 ---
 
-# pi-agent-registry — Phase-1 design record
+# pi-agent-registry — fleet contract design record
 
 The monorepo manifest convention is the consumer contract. L0
 `tpl-agent-repo` owns birth/propagation shape, `softwareco-agents` owns
 fleet/role/lifecycle conventions, engineering-core owns profile keys/members,
-AK owns task/evidence/decision truth, and ASC owns any future execution.
+AK owns task/evidence/decision truth, ASC owns Phase-2 execution, and
+little-helpers owns Phase-3 visible Ghostty transport.
 
-This package owns two read-only Pi-side surfaces and one bounded execution
-contract:
+This package owns two read-only Pi-side surfaces and two bounded composition
+contracts:
 
 1. mutable manifest inspection for already loadable agents;
 2. aggregate immutable-observation fleet lint;
 3. the Fleet Phase-2 exact-task read-only dispatch contract (authorization,
-   receipt, evidence) with all spawn/session/capacity machinery ASC-owned.
+   receipt, evidence) with all Phase-2 spawn/session/capacity machinery ASC-owned;
+4. the Fleet Phase-3 exact-task clean visible admission contract, with
+   little-helpers-owned transport and no automatic AK evidence.
 
 None of these surfaces grants standing-agent lifecycle authority.
 
@@ -80,6 +83,21 @@ src/dispatch-request.ts
 
 src/dispatch.ts + src/sessions-dir.ts
   Phase-2 pipeline with fail-closed gates; sessions delegated to ASC
+
+extensions/standing-agent-spawn.ts + src/visible-launch.ts
+  Phase-3 tool registration and exact-task admission/recheck pipeline
+
+src/visible-launch-contract.ts + visible-launch-compose.ts
+  clean child argv, manifest persona/model/thinking request, ACK/FINAL brief
+
+src/visible-launch-inputs.ts + visible-launch-bootstrap.ts
+  clean agent byte agreement and approved installed bootstrap entry checks
+
+src/visible-launch-admission.ts + visible-launch-receipt.ts
+  persistent exclusive agent/task reservation and write-once launch observation
+
+src/visible-launch-transport.ts
+  version-1 little-helpers sidequest-launch capability gate, not transport code
 ```
 
 ## Manifest compatibility
@@ -218,7 +236,7 @@ failure still fails closed with `confirmed_no_effects`:
   request and creates the runtime through ASC's exported
   `createAscExecutionRuntime` + `resolveSubagentSessionsDir` + model
   selection; the registry supplies only the `extraSkillProfileResolver` seam
-  (`skillProfile = agent name`). No spawn/session/capacity code lives here.
+  (`skillProfile = agent name`). No Phase-2 spawn/session/capacity code lives here.
   `src/sessions-dir.ts` now delegates to ASC instead of the Phase-0
   quarantine.
 - **One level deep**: dispatched children carry
@@ -256,11 +274,65 @@ so dash-led prompts (persona front matter) require the registry's dispatch
 header envelope — a pi/ASC transport hardening candidate for a later slice
 (first observed live 2026-08-31 as child exit `Unknown option: ---`).
 
+## Phase-3 clean visible admission (AK 5133)
+
+**Locally implemented and live-dogfood verified; not published.**
+`standing_agent_spawn { agent, task, objective, parentPeerTarget, reportBack?, cwd? }`
+adds visible TUI admission without changing Phase-2 ASC dispatch. Full operator
+contract and compact evidence identifiers live in the
+[README](../../README.md#phase-3-clean-visible-admission-ak-5133) and the
+[2026-09-07 dogfood evidence](2026-09-07-fleet-phase3-dogfood.md), including
+receipt and real-runtime assertion output. AK owns evidence and closeout.
+
+The exact task must be claimed with a live lease in the observed origin repo;
+child cwd cannot cross that repo boundary. Clean committed manifest/persona
+inputs must agree with cached, fresh, and resolved inputs. After exclusive
+persistent pair reservation, task/lease facts and origin/agent/bootstrap inputs
+are rechecked immediately before transport and inputs are observed afterward.
+An unresolved, corrupt, partial, or admitted reservation blocks another
+admission in that receipts directory. Never retry automatically — including
+no-effects, reservation failure, cancellation, crash, or publication failure;
+explicit owner disposition is required. Phase-2 attempt limits do not apply.
+
+Composition uses `--offline --no-extensions --no-skills --no-prompt-templates`
+plus approved installed intercom/presence entrypoints and explicitly selected
+skills. Normal cwd-bound AGENTS context remains; controller conversation and
+ambient extension/skill discovery do not. Builtin `zai` is supported without
+an ambient provider extension. Manifest thinking is requested via argv, then
+Pi applies its supported-level clamp (live `medium` → `high` on
+`zai/glm-5.3`). Settings/auth/models, transitive imports, and full skill/runtime
+integrity are not proven by the approved-entry hashes. Offline startup is not
+network isolation; `bash`/scope are advisory, not a sandbox.
+
+Registry composes; little-helpers' exported `sidequest-launch` owns visible
+transport and must advertise `STANDING_AGENT_TRANSPORT_VERSION === 1`.
+The export is present in local helpers 0.9.0 source but must ship in its next
+release; older npm helpers make packed registry admission fail closed. No
+claim of published availability follows from local tests.
+
+The immutable launch receipt records transport admission and bounded
+launch-window observations, never session-start/ACK/completion proof; those
+fields remain `unproven`. Intercom mode requires an exact controller
+`session-<UUID>`, one first-action `PEER_ACK`, then one closing `PEER_FINAL`
+and stop; manual/none modes may omit the target. No automatic AK evidence is
+written. Verified live proof used a real TUI driver and real child TUI,
+correlated ACK/FINAL without duplicates, and four read-only file inspections
+with no file/AK writes observed. Ghostty was `1.3.2-main`
+(`origin-main492300cad`), not a literal 1.4 release.
+
+Final package checks: registry **134/134**, helpers **430/430**, and both full
+release checks pass. The real-fleet pin was explicitly refreshed after independent
+HEAD-only reproduction of engineering-core's docs-only `51fc387` → `9225dd6`
+drift; profile bytes, fleet revisions, diagnostics and assertions are unchanged.
+The new standing-agent reality assertion passes; the broader observer test still
+reports an unrelated process on retired Ghostty `9d8fbd15`. AK5134 remains separate.
+
 ## Real fleet baseline
 
 The real `~/ai-society/agents/agent-*` walk is revision-bound in
-`tests/fixtures/real-fleet-lint-baseline.json`. The known unhealthy result is a
-successful implementation proof:
+`tests/fixtures/real-fleet-lint-baseline.json`. The original Phase-1 unhealthy
+result recorded these historical observations (not a claim about current
+external HEADs):
 
 - four canonical repositories observed;
 - three missing manifests;
@@ -283,5 +355,7 @@ slice rather than silently turning green.
 - real fleet test: exact commits, profile bytes, diagnostics, and report digest;
 - extension test: `action=lint` returns observation-only unhealthy baseline;
 - CLI test: JSON and exit taxonomy;
-- packed smoke: shipped CLI/module/action plus Phase-0 dispatch gate;
+- packed smoke: shipped CLI/module/action and fail-closed dependency capability gates;
+- Phase-3 tests: argv/bootstrap composition, exact-task and input rechecks,
+  persistent reservation, cancellation/drift, and immutable launch receipts;
 - package check, fresh Pi dogfood, root loop gates, and independent review.

package/extensions/pi-agent-registry.ts

@@ -10,6 +10,7 @@ import { Type } from "typebox";
 import { dispatchAgent } from "../src/dispatch.ts";
 import { lintAgentFleet } from "../src/fleet-lint.ts";
 import { type AgentRegistry, AgentRegistryError, createAgentRegistry } from "../src/registry.ts";
+import { registerStandingAgentSpawnTool } from "./standing-agent-spawn.ts";
 
 interface RegistryHandle {
   registry: AgentRegistry;
@@ -375,4 +376,6 @@ Phase-2 boundaries: standing-agent dispatch is one level deep (children carry PI
       };
     },
   });
+
+  registerStandingAgentSpawnTool({ pi, getRegistry });
 }

package/extensions/standing-agent-spawn.ts

@@ -0,0 +1,85 @@
+// summary: register exact-task visible admission; no transport/session machinery here.
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { AgentRegistry } from "../src/registry.ts";
+import { spawnStandingAgentVisible } from "../src/visible-launch.ts";
+
+export function registerStandingAgentSpawnTool({
+  pi,
+  getRegistry,
+}: {
+  pi: ExtensionAPI;
+  getRegistry: () => Promise<AgentRegistry>;
+}): void {
+  pi.registerTool({
+    name: "standing_agent_spawn",
+    label: "Standing Agent Visible Admission (Phase 3)",
+    description:
+      "Request ONE clean visible Pi TUI session in a Ghostty tab/window (Fleet Phase 3), composed as a read-only standing agent for an exact claimed AK task in this origin repository. Requires a nonblank bounded objective, clean committed agent inputs and trusted explicit ACK/presence/provider bootstrap. Atomically reserves the agent/task pair before transport: unresolved or admitted launches cannot be retried automatically, even after cancellation or crashes. Explicit owner disposition is required. Transport admission does NOT prove session startup, ACK, read-only lifetime behavior, task consumption or completion; no AK evidence is written. Read/bash posture is advisory, not a sandbox.",
+    promptSnippet:
+      "Request one exact-task read-only visible standing-agent admission, not task completion.",
+    promptGuidelines: [
+      "standing_agent_spawn requires agent discovery, an exact claimed AK task, a bounded read-only objective and an exact controller session id for intercom report-back.",
+      "Never retry standing_agent_spawn automatically for a reserved/admitted or indeterminate agent/task pair; supervise the returned runId.",
+    ],
+    parameters: Type.Object({
+      agent: Type.String({ pattern: "^[a-z][a-z0-9-]{0,63}$" }),
+      task: Type.Integer({
+        minimum: 1,
+        description: "Exact claimed AK task in the origin repository.",
+      }),
+      objective: Type.String({
+        minLength: 1,
+        maxLength: 32_768,
+        description:
+          "Bounded read-only inspection/report objective, maximum 32 KiB UTF-8. No standby or mutation.",
+      }),
+      reportBack: Type.Optional(
+        StringEnum(["intercom", "manual", "none"] as const, { description: "Default intercom." }),
+      ),
+      parentPeerTarget: Type.Optional(
+        Type.String({ description: "Exact controller session id; required for intercom." }),
+      ),
+      cwd: Type.Optional(
+        Type.String({
+          description:
+            "Existing directory within the exact task's origin repository; defaults to that root.",
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const registry = await getRegistry();
+      const outcome = await spawnStandingAgentVisible(
+        params,
+        { registry, pi },
+        {
+          cwd: ctx.cwd,
+          ...(ctx.model ? { model: ctx.model as { provider?: string; id?: string } } : {}),
+        },
+        signal,
+      );
+      const text = outcome.ok
+        ? `Transport admitted (${outcome.launchMode}), run ${outcome.runId}. Session start, ACK and task completion remain unproven.\nReceipt: ${outcome.receiptPath}`
+        : `${outcome.message}${outcome.runId ? `\nSupervision run: ${outcome.runId}` : ""}`;
+      return {
+        content: [{ type: "text" as const, text }],
+        details: {
+          ok: outcome.ok,
+          phase: outcome.phase,
+          ...(outcome.runId ? { runId: outcome.runId } : {}),
+          ...(outcome.ok
+            ? { admission: outcome.admission }
+            : {
+                reason: outcome.reason,
+                effectDisposition: outcome.effectDisposition,
+                spawnAttempted: outcome.spawnAttempted,
+              }),
+          ...(outcome.receiptPath ? { receiptPath: outcome.receiptPath } : {}),
+          ...(outcome.receipt ? { receiptSha256: outcome.receipt.receiptSha256 } : {}),
+        },
+        ...(!outcome.ok ? { isError: true } : {}),
+      };
+    },
+  });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tryinget/pi-agent-registry",
-  "version": "0.3.1",
-  "description": "Pi standing-agent manifest inspection, immutable fleet lint, and the Fleet Phase-2 exact-task read-only dispatch contract",
+  "version": "0.3.2",
+  "description": "Pi standing-agent manifest inspection, immutable fleet lint, the Fleet Phase-2 exact-task read-only dispatch contract, and the Fleet Phase-3 clean visible standing-agent launch",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -57,6 +57,7 @@
   },
   "files": [
     "extensions/pi-agent-registry.ts",
+    "extensions/standing-agent-spawn.ts",
     "src",
     "scripts/fleet-lint.mjs",
     "prompts",
@@ -84,9 +85,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.14",
-    "@earendil-works/pi-agent-core": "0.84.3",
-    "@earendil-works/pi-ai": "0.84.3",
-    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@earendil-works/pi-agent-core": "0.84.4",
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
     "@types/node": "^25.3.3",
     "@typescript/native-preview": "7.0.0-dev.20260417.1"
   },
@@ -100,6 +101,7 @@
   },
   "dependencies": {
     "@tryinget/pi-autonomous-session-control": "0.7.0",
-    "typebox": "1.3.7"
+    "typebox": "1.3.7",
+    "@tryinget/pi-little-helpers": "0.10.0"
   }
 }

package/src/visible-launch-admission.ts

@@ -0,0 +1,69 @@
+// summary: durable exclusive Phase-3 pair reservation; no automatic release or retry, including crashes.
+import { constants } from "node:fs";
+import { mkdir, open, readFile, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { canonicalJsonString, sha256Hex } from "./dispatch-receipt.ts";
+import {
+  resolveVisibleLaunchReceiptsDir,
+  validateVisibleLaunchIdentity,
+} from "./visible-launch-receipt.ts";
+
+export async function reserveVisibleLaunchPair(
+  input: {
+    agent: string;
+    task: number;
+    runId: string;
+    requestSha256: string;
+  },
+  dir?: string,
+): Promise<{ reserved: true; path: string } | { reserved: false; runId?: string }> {
+  validateVisibleLaunchIdentity(input.agent, input.runId);
+  if (
+    !Number.isSafeInteger(input.task) ||
+    input.task <= 0 ||
+    !/^[a-f0-9]{64}$/u.test(input.requestSha256)
+  ) {
+    throw new Error("Invalid launch reservation identity");
+  }
+  const home = resolveVisibleLaunchReceiptsDir(dir);
+  await mkdir(home, { recursive: true, mode: 0o700 });
+  const canonicalHome = await realpath(home);
+  const path = join(canonicalHome, `pair-${input.agent}.ak-${input.task}.reservation.json`);
+  let handle: Awaited<ReturnType<typeof open>>;
+  try {
+    handle = await open(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    // Corrupt/incomplete reservations also block. Never infer an expired process or retry permission.
+    try {
+      const previous = JSON.parse(await readFile(path, "utf8"));
+      validateVisibleLaunchIdentity(previous.agent, previous.runId);
+      if (previous.agent === input.agent && previous.task === input.task)
+        return { reserved: false, runId: previous.runId };
+    } catch {
+      /* fail closed */
+    }
+    return { reserved: false };
+  }
+  try {
+    const facts = {
+      schema: "pi-agent-registry.visible-launch-reservation/1",
+      ...input,
+      recordedAt: new Date().toISOString(),
+    };
+    await handle.writeFile(
+      `${canonicalJsonString({ ...facts, sha256: sha256Hex(canonicalJsonString(facts)) })}\n`,
+    );
+    await handle.sync();
+    await handle.chmod(0o400);
+  } finally {
+    await handle.close();
+  }
+  const directory = await open(canonicalHome, constants.O_RDONLY);
+  try {
+    await directory.sync();
+  } finally {
+    await directory.close();
+  }
+  return { reserved: true, path };
+}