@tt-a1i/openpi 0.5.0 → 0.6.0

package/extensions/workflows/model.ts

@@ -67,6 +67,10 @@ export type WorkflowDeliveryState =
 export interface WorkflowDelivery {
   /** Stable per-run idempotency identity, never a transport-batch id. */
   id: string;
+  /** Destination transcript identity; legacy records fall back to run.sessionId. */
+  ownerSessionId?: string;
+  /** Process-local generation of the Pi SessionManager owner. */
+  ownerEpoch?: number;
   state: WorkflowDeliveryState;
   attempts: number;
   updatedAt: number;
@@ -123,7 +127,7 @@ export interface AgentRecord {
   usage: AgentUsage;
   /** Replayed from a prior run's journal instead of actually executed. */
   replayed?: boolean;
-  /** Explicit caller-supplied acceptance result; never inferred from role/task. */
+  /** Deprecated child self-attestation; never runtime-observed evidence. */
   acceptance?: AcceptanceLedger;
   /** Branch of the isolated worktree this agent ran in, when it holds commits. */
   worktreeBranch?: string;

package/extensions/workflows/prompt.ts

@@ -56,7 +56,7 @@ export const WORKFLOW_TOOL_DESCRIPTION = [
   "Interactive sessions launch in the background by default and deliver completion later. Set wait: true only when this tool call must return the final result inline.",
   "Derive fan-out from independent verifiable work items and task difficulty. Concurrency is a runtime ceiling, not a target or the total-call limit; user cost, count, model, and effort constraints take precedence.",
   "For concurrent writers use isolation: 'worktree' and tell each agent to commit. Read-only work should normally stay in the shared checkout.",
-  "Read the workflows Skill before a nontrivial script; it covers the restricted sandbox, full DSL, acceptance, result refs, replay, background lifecycle, limits, and examples.",
+  "Read the workflows Skill before a nontrivial script; it covers the restricted sandbox, full DSL, result refs, replay, background lifecycle, limits, and examples.",
 ].join("\n");
 
 /** Adds workflow orchestration primitives and background execution to the model's tool prompt. */
@@ -75,14 +75,6 @@ export function buildWorkflowAgentPrompt(prompt: string) {
   return prompt;
 }
 
-/** Instructs structured workflow children to terminate with exactly one structured_output call. */
-export const STRUCTURED_OUTPUT_SYSTEM_INSTRUCTION =
-  "When your task is complete, call the `structured_output` tool exactly once as your final action, with fields matching the required schema. Do not write any other text after it.";
-
-/** Describes the terminating structured_output tool and its final-action contract. */
-export const STRUCTURED_OUTPUT_TOOL_DESCRIPTION =
-  "Return your final result as structured data matching the required schema. Call this exactly once, as your last action; do not write any other text after it.";
-
 /** Builds the workflow completion report returned to the parent model. */
 export function buildWorkflowResultMessage(
   details: WorkflowDetails,
@@ -157,7 +149,9 @@ export function buildWorkflowResultMessage(
               : "running";
       lines.push(
         `- [${agent.label}]${agent.phase ? ` (${agent.phase})` : ""} ${status}` +
-          (agent.acceptance ? ` · acceptance ${agent.acceptance.status}` : "") +
+          (agent.acceptance
+            ? ` · deprecated model self-attestation ${agent.acceptance.status}`
+            : "") +
           (agent.error ? ` — ${agent.error}` : ""),
       );
     }

package/extensions/workflows/result-delivery.ts

@@ -1,8 +1,13 @@
-import type { WorkflowDetails } from "./model.ts";
+import {
+  type CompletionEnvelope,
+  type CompletionOwner,
+  createCompletionInbox,
+} from "../shared/completion-inbox.ts";
 import type {
   DurableResultDeliveryQueue,
   DurableResultDeliveryReceipt,
 } from "../shared/result-delivery.ts";
+import type { WorkflowDetails } from "./model.ts";
 
 export interface WorkflowCompletionEnvelope {
   deliveryId: string;
@@ -12,6 +17,7 @@ export interface WorkflowCompletionEnvelope {
 
 export interface WorkflowResultDeliveryOptions {
   isIdle: () => boolean;
+  owner?: () => CompletionOwner | undefined;
   persist: (details: WorkflowDetails) => void;
   deliver: (
     envelopes: readonly WorkflowCompletionEnvelope[],
@@ -34,7 +40,9 @@ function errorText(error: unknown) {
 export function createWorkflowResultDelivery(
   options: WorkflowResultDeliveryOptions,
 ) {
-  const pending = new Map<string, WorkflowCompletionEnvelope>();
+  const inbox = createCompletionInbox<WorkflowCompletionEnvelope>();
+  const currentOwner =
+    options.owner ?? (() => ({ sessionId: "test", epoch: 0 }));
   let flushing: Promise<void> | undefined;
   let flushRequested = false;
   let wakeRequested = false;
@@ -57,10 +65,44 @@ export function createWorkflowResultDelivery(
     options.persist(details);
   };
 
-  const enqueue = (envelope: WorkflowCompletionEnvelope) => {
-    pending.set(envelope.deliveryId, envelope);
+  const inboxEnvelope = (
+    envelope: WorkflowCompletionEnvelope,
+  ): CompletionEnvelope<WorkflowCompletionEnvelope> => {
+    const delivery = envelope.details.delivery;
+    const deliverySessionId = delivery?.ownerSessionId;
+    const detailsSessionId = envelope.details.sessionId;
+
+    // Conflicting owner fields invalidate delivery ownership fail-closed.
+    const hasConflict =
+      deliverySessionId !== undefined &&
+      detailsSessionId !== undefined &&
+      deliverySessionId !== detailsSessionId;
+
+    const ownerSessionId = hasConflict ? undefined : deliverySessionId;
+    return {
+      deliveryId: envelope.deliveryId,
+      owner: {
+        sessionId:
+          ownerSessionId && ownerSessionId !== "unowned"
+            ? ownerSessionId
+            : "unowned",
+        epoch: delivery?.ownerEpoch ?? 0,
+      },
+      producer: "workflow",
+      producerId: envelope.runId,
+      terminalRef: {
+        kind: "workflow-terminal",
+        runId: envelope.runId,
+        status: envelope.details.status,
+      },
+      wake: "producer-policy",
+      payload: envelope,
+    };
   };
 
+  const enqueue = (envelope: WorkflowCompletionEnvelope) =>
+    inbox.defer(inboxEnvelope(envelope), currentOwner());
+
   const retainPending = (
     envelope: WorkflowCompletionEnvelope,
     patch: Partial<NonNullable<WorkflowDetails["delivery"]>>,
@@ -69,7 +111,7 @@ export function createWorkflowResultDelivery(
     // Memory owns the retry before persistence is attempted. A broken disk
     // must not make this envelope, or any sibling after it, disappear from the
     // current process.
-    enqueue(envelope);
+    const admitted = enqueue(envelope);
     try {
       persistState(envelope.details, "pending", patch);
     } catch (error) {
@@ -83,6 +125,7 @@ export function createWorkflowResultDelivery(
         };
       }
     }
+    return admitted;
   };
 
   const flush = async (wake: boolean) => {
@@ -91,17 +134,16 @@ export function createWorkflowResultDelivery(
       wakeRequested ||= wake;
       return flushing;
     }
-    if (pending.size === 0) return;
+    if (inbox.size() === 0) return;
 
     flushing = (async () => {
       let passWake = wake;
-      while (pending.size > 0) {
+      while (inbox.size() > 0) {
         flushRequested = false;
         wakeRequested = false;
-        const envelopes = [...pending.values()];
-        for (const envelope of envelopes) {
-          pending.delete(envelope.deliveryId);
-        }
+        const claimed = inbox.claim(currentOwner());
+        const envelopes = claimed.map((envelope) => envelope.payload);
+        if (envelopes.length === 0) break;
 
         let receipts: readonly DurableResultDeliveryReceipt[] | undefined;
         try {
@@ -109,6 +151,7 @@ export function createWorkflowResultDelivery(
         } catch (error) {
           const message = errorText(error);
           for (const envelope of envelopes) {
+            inbox.acknowledge([envelope.deliveryId]);
             retainPending(
               envelope,
               {
@@ -127,6 +170,7 @@ export function createWorkflowResultDelivery(
           for (const envelope of envelopes) {
             const receipt = byId.get(envelope.deliveryId);
             if (receipt?.delivered) {
+              inbox.acknowledge([envelope.deliveryId]);
               try {
                 persistState(envelope.details, "delivered", {
                   attempts: (envelope.details.delivery?.attempts ?? 0) + 1,
@@ -150,6 +194,7 @@ export function createWorkflowResultDelivery(
               }
               continue;
             }
+            inbox.acknowledge([envelope.deliveryId]);
             retainPending(
               envelope,
               {
@@ -183,7 +228,7 @@ export function createWorkflowResultDelivery(
 
     /** Terminal won the wait/abort arbitration and will be returned inline. */
     consumeInline(details: WorkflowDetails) {
-      if (details.delivery) pending.delete(details.delivery.id);
+      if (details.delivery) inbox.consumeDeliveryIds([details.delivery.id]);
       persistState(details, "consumed-inline", {
         deliveredAt: Date.now(),
         lastError: undefined,
@@ -214,18 +259,46 @@ export function createWorkflowResultDelivery(
     restore(envelope: WorkflowCompletionEnvelope) {
       const state = envelope.details.delivery?.state;
       if (state !== "pending" && state !== "held-for-inline") return false;
-      // A process restart cannot still own the inline waiter. Deterministically
-      // reconstruct pending delivery from the terminal artifact.
-      if (state === "held-for-inline") {
-        retainPending(
+      const owner = currentOwner();
+      const deliverySessionId = envelope.details.delivery?.ownerSessionId;
+      const detailsSessionId = envelope.details.sessionId;
+      const hasConflict =
+        deliverySessionId !== undefined &&
+        detailsSessionId !== undefined &&
+        deliverySessionId !== detailsSessionId;
+      const storedSessionId = hasConflict
+        ? undefined
+        : (deliverySessionId ?? detailsSessionId);
+
+      // Restoring canonical producer state is the explicit owner-revival
+      // boundary. Rebind only the same transcript to this process-local
+      // SessionManager generation; a different Session still dead-letters.
+      if (
+        owner &&
+        storedSessionId !== undefined &&
+        storedSessionId === owner.sessionId
+      ) {
+        envelope.details.delivery = {
+          ...envelope.details.delivery!,
+          ownerSessionId: owner.sessionId,
+          ownerEpoch: owner.epoch,
+        };
+        return retainPending(
           envelope,
-          { lastError: "Inline waiter was not active after session restart" },
+          {
+            ownerSessionId: owner.sessionId,
+            ownerEpoch: owner.epoch,
+            lastError:
+              state === "held-for-inline"
+                ? "Inline waiter was not active after session restart"
+                : undefined,
+          },
           "Restored delivery state persistence failed",
         );
-      } else {
-        enqueue(envelope);
       }
-      return true;
+      // Keep the canonical terminal artifact pending, but record that this
+      // process is not its transcript owner instead of redirecting it.
+      return enqueue(envelope);
     },
 
     retryPending() {
@@ -242,12 +315,13 @@ export function createWorkflowResultDelivery(
     },
 
     size() {
-      return pending.size;
+      return inbox.size();
     },
 
     clear() {
-      pending.clear();
+      inbox.clear();
     },
+    inspectDeadLetters: inbox.inspectDeadLetters,
   };
   return queue satisfies DurableResultDeliveryQueue<WorkflowCompletionEnvelope>;
 }

package/extensions/workflows/retention.ts

@@ -237,6 +237,12 @@ function makeProjection(
       ? {
           delivery: {
             id: details.delivery.id,
+            ...(details.delivery.ownerSessionId
+              ? { ownerSessionId: details.delivery.ownerSessionId }
+              : {}),
+            ...(details.delivery.ownerEpoch !== undefined
+              ? { ownerEpoch: details.delivery.ownerEpoch }
+              : {}),
             state: details.delivery.state,
             attempts: details.delivery.attempts,
             updatedAt: details.delivery.updatedAt,

package/extensions/workflows/runner.ts

@@ -16,14 +16,12 @@ import {
   type AgentSessionEventListener,
   createAgentSession,
   DefaultResourceLoader,
-  defineTool,
   type ExtensionAPI,
   type ExtensionContext,
   SessionManager,
   SettingsManager,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import { type TSchema, Type } from "typebox";
 import { AgentToolRenderLedger } from "../shared/agent-tool-renderer.ts";
 import {
   bindChildSessionExtensions,
@@ -34,10 +32,11 @@ import {
 import { createToolCallTimeoutGuard } from "../shared/tool-call-timeout.ts";
 import { type AgentUsage, emptyUsage, type TranscriptEntry } from "./model.ts";
 import {
-  buildWorkflowAgentPrompt,
+  childToolsWithStructuredOutput,
+  createStructuredOutputTool,
   STRUCTURED_OUTPUT_SYSTEM_INSTRUCTION,
-  STRUCTURED_OUTPUT_TOOL_DESCRIPTION,
-} from "./prompt.ts";
+} from "../shared/structured-output.ts";
+import { buildWorkflowAgentPrompt } from "./prompt.ts";
 import {
   AgentProgressProjection,
   type ProgressAssistantMessage,
@@ -142,9 +141,7 @@ export function workflowChildTools(
   tools: readonly string[] | undefined,
   structured: boolean,
 ) {
-  return tools
-    ? [...new Set([...tools, ...(structured ? ["structured_output"] : [])])]
-    : undefined;
+  return childToolsWithStructuredOutput(tools, structured);
 }
 
 interface WorkflowToolSession {
@@ -179,68 +176,6 @@ export function guardWorkflowChildTools(
   });
 }
 
-function isJsonSchema(value: unknown): value is TSchema {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const seen = new WeakSet<object>();
-  let nodes = 0;
-  const validate = (current: unknown, depth: number): boolean => {
-    if (++nodes > 10_000 || depth > 24) return false;
-    if (
-      current === null ||
-      typeof current === "string" ||
-      typeof current === "boolean"
-    ) {
-      return true;
-    }
-    if (typeof current === "number") return Number.isFinite(current);
-    if (Array.isArray(current)) {
-      return current.every((item) => validate(item, depth + 1));
-    }
-    if (typeof current !== "object") return false;
-    if (seen.has(current)) return false;
-    seen.add(current);
-    return Object.keys(current).every((key) => {
-      if (key === "__proto__" || key === "constructor" || key === "prototype") {
-        return false;
-      }
-      return validate((current as Record<string, unknown>)[key], depth + 1);
-    });
-  };
-  return validate(value, 0);
-}
-
-/** Preserve the caller's full JSON Schema instead of lossy keyword conversion. */
-function jsonSchemaToTypebox(schema: unknown): TSchema {
-  if (!isJsonSchema(schema)) {
-    throw new Error("structured output schema must be a bounded JSON object");
-  }
-  return Type.Unsafe(schema);
-}
-
-/**
- * One-shot terminating tool injected when a schema is supplied: the subagent
- * calls it as its final action and we capture the validated object.
- */
-function makeStructuredOutputTool(
-  schema: unknown,
-  capture: (value: unknown) => void,
-): ToolDefinition {
-  return defineTool({
-    name: "structured_output",
-    label: "Structured Output",
-    description: STRUCTURED_OUTPUT_TOOL_DESCRIPTION,
-    parameters: jsonSchemaToTypebox(schema),
-    async execute(_toolCallId, params) {
-      capture(params);
-      return {
-        content: [{ type: "text", text: "Recorded structured result." }],
-        details: params,
-        terminate: true,
-      };
-    },
-  });
-}
-
 type AssistantMessage = ProgressAssistantMessage;
 
 export { transcriptFromMessages };
@@ -475,7 +410,7 @@ export async function runAgent(
     customTools =
       options.schema !== undefined
         ? [
-            makeStructuredOutputTool(options.schema, (value) => {
+            createStructuredOutputTool(options.schema, (value) => {
               if (!settled) structured = value;
             }),
           ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tt-a1i/openpi",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "OpenPI — a Pi-native multi-agent workbench with background execution, isolated subagents, replay-safe workflows, goals, tasks, and observable TUI",
   "license": "MIT",
   "author": "tt-a1i",
@@ -63,9 +63,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.8",
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-tui": "^0.84.1",
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
     "@effect/tsgo": "^0.24.2",
     "@effect/vitest": "^4.0.0-beta.99",
     "@types/node": "^26.1.1",
@@ -75,9 +75,9 @@
     "vitest": "4.1.10"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": ">=0.85.1",
+    "@earendil-works/pi-coding-agent": ">=0.85.1",
+    "@earendil-works/pi-tui": ">=0.85.1",
     "typebox": "*"
   },
   "type": "module",

package/skills/subagents/REFERENCE.md

@@ -153,8 +153,9 @@ So `tools: [read, grep, find, ls]` yields a child that genuinely has no
 `write`, `edit`, or `bash` tool to call — not one that has been asked not to.
 Parent-only names are removed before the generated roster and spawn result are
 shown, so a type that lists `subagent_spawn` never advertises it as usable.
-A structured Workflow child additionally receives only its terminating
-`structured_output` tool; this does not restore any denied repository tool.
+A Workflow child with a schema, or a Direct Subagent spawned with
+`output_schema`, additionally receives only its terminating `structured_output`
+tool; this does not restore any denied repository tool.
 
 While `/plan` is armed, `isolation: "worktree"` is rejected before Git is
 changed. A selected type whose declared tools plan mode would narrow (such as

package/skills/subagents/SKILL.md

@@ -13,6 +13,7 @@ The tool definitions are canonical for parameters, limits, model syntax, isolati
 - Prefer a matching agent type when one exists; its tool restriction is enforced. Model precedence is explicit spawn override, selected type-file model, configured built-in role model, then parent model. Reasoning precedence is explicit spawn override, selected type default, then parent effort. Types live in `~/.pi/agent/agents/*.md` and, for trusted projects, `.pi/agents/*.md`; see [Agent types](REFERENCE.md).
 - Isolate concurrent writers in worktrees according to the `subagent_spawn` schema so they cannot overwrite one checkout or git index. While Plan Mode is active, use only read-only exploration types (or no type); worktree isolation and types narrowed by Plan Mode are rejected.
 - After spawning, continue useful parent work. In an interactive session, if none remains, tell the user the child is still running and end the turn; automatic result delivery will re-invoke the parent when it settles. Do not block merely because the next step depends on the result or because there is nothing else to do. Use `subagent_wait` only when the user explicitly asks to keep the current response open for the result, or when non-interactive automation must return it in the same invocation.
+- Use optional `output_schema` when downstream work needs a machine-validated result rather than prose. The child then receives one terminating `structured_output` tool, and the run fails if it finishes without submitting a matching value. Keep schemas small and task-specific; the validated JSON is delivered to the parent and preserved in a private content-addressed artifact. Omit the option for ordinary text reports.
 
 ## Worktree isolation
 

package/skills/workflows/REFERENCE.md

@@ -12,13 +12,13 @@ The `workflow` script is an async JavaScript function body executed in a restric
 
 ## Agent calls
 
-`await agent(prompt, options)` runs one child and always resolves to `{ ok, output, structured?, ref?, acceptance?, error? }`. Check `ok` before reading output. Children receive normal trust-aware resources but cannot recursively orchestrate or ask the user.
+`await agent(prompt, options)` runs one child and always resolves to `{ ok, output, structured?, ref?, acceptance?, acceptanceWarning?, error? }`. Check `ok` before reading output. Children receive normal trust-aware resources but cannot recursively orchestrate or ask the user.
 
-Useful options include `agent_type`, `label`, `phase`, `schema`, `acceptance`, `model`, `provider`, `effort`, `isolation`, `operator`, and `inputs`.
+Useful options include `agent_type`, `label`, `phase`, `schema`, `model`, `provider`, `effort`, `isolation`, `operator`, and `inputs`. The legacy `acceptance` option remains readable only during the 0.x migration window described below.
 
 - Prefer a matching `agent_type`. Model precedence is explicit model/provider, type file, configured built-in role, then parent. Effort precedence is explicit effort, type default, then parent.
 - `schema` validates structured output. Use it whenever later workflow logic branches on fields.
-- `acceptance: { criteria: [{ id, description, requiredEvidence?: string[] }] }` requires the same child to return an evidence ledger. An invocation accepts 1–32 criteria; each criterion has a 1–500 character human-readable `description` and an optional `requiredEvidence` array of at most 16 concise string labels (up to 120 characters each). The child must return exact matching labels in `acceptance.criteria[].evidence`. A criterion without `requiredEvidence` is an attestation of its description, not an evidence-backed gate; criteria that need evidence-backed acceptance must declare the required labels. Missing, malformed, or rejected criteria make `ok:false` while preserving output and evidence.
+- `acceptance` is deprecated since OpenPI 0.5 and scheduled for removal in 1.0. Compatibility calls still return the child-authored ledger with `authority: "model-self-attestation"` and a migration warning, but it never determines `ok`. Use ordinary `schema` for findings, then let the parent evaluate them alongside runtime-observed exit codes, test receipts, file fingerprints, and tool results. Old DSL, journals, and artifacts remain readable during 0.x.
 - `operator: "name"` reuses one in-memory child Session for serialized follow-ups inside the same run. Its model, role/tools, effort, structured mode, and cwd are frozen by the first activation. Operators cannot use per-call worktrees or replay, and do not survive restarts.
 - `inputs: [ref, ...]` accepts successful opaque refs from the same workflow run only. Each conclusion is bounded to 16 KiB and total injected input to 48 KiB. The total budget is fairly distributed, so a large fan-out cannot starve later results merely because of order; partial projections are labeled. Full successful child results remain in the run's `agent-results/` artifacts. Inputs are marked as untrusted data; the resulting graph is observability, not scheduling authority.
 - Fair projection preserves the head and tail of every partial result and names its run-relative `agent-results/agent-N.json` audit artifact. That path is provenance for the parent/operator, not a child-readable handle. Fair presence is not proof of full evidence coverage: for large fan-out, group source refs into local Report agents, then pass only their refs to a global Report. The workflow script—not Runtime—must state planned, selected, covered, failed, and deferred counts.

package/skills/workflows/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflows
-description: Orchestrates multi-agent work with OpenPI's inline JavaScript Workflow DSL. Use when a task needs multi-phase fan-out, pipelines, barriers, structured handoffs, acceptance evidence, or resumable background orchestration.
+description: Orchestrates multi-agent work with OpenPI's inline JavaScript Workflow DSL. Use when a task needs multi-phase fan-out, pipelines, barriers, structured handoffs, or resumable background orchestration.
 ---
 
 # Workflows

package/web/adapter/pi-adapter.ts

@@ -490,6 +490,9 @@ export class PiWebAdapter {
         status: this.runtime.isIdle()
           ? ("idle" as const)
           : ("running" as const),
+        ...(this.runtime.getActiveTurn()
+          ? { activeTurn: this.runtime.getActiveTurn() }
+          : {}),
         capabilities: webCapabilitySnapshot(this.runtime.sessionManager),
       },
       truncation: {

package/web/host/pi-coding-agent-entry.ts

@@ -0,0 +1,162 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
+export const PI_CODING_AGENT_ENTRY_ENV = "OPENPI_PI_CODING_AGENT_ENTRY";
+const PACKAGE_ROOT_SEARCH_DEPTH = 10;
+
+type PackageManifest = {
+  name?: unknown;
+  main?: unknown;
+  exports?: Record<string, { import?: unknown } | string>;
+};
+
+export function findPackageRoot(realPath: string, packageName: string) {
+  let dir = dirname(realPath);
+  for (let depth = 0; depth < PACKAGE_ROOT_SEARCH_DEPTH; depth++) {
+    const manifestPath = join(dir, "package.json");
+    if (existsSync(manifestPath)) {
+      const manifest = readManifest(manifestPath);
+      if (manifest?.name === packageName) return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+function readManifest(manifestPath: string) {
+  try {
+    return JSON.parse(readFileSync(manifestPath, "utf8")) as PackageManifest;
+  } catch {
+    return undefined;
+  }
+}
+
+function officialEntry(root: string | undefined) {
+  if (!root) return undefined;
+  const manifest = readManifest(join(root, "package.json"));
+  const target = manifest?.exports?.["."];
+  const relative =
+    typeof target === "string"
+      ? target
+      : typeof target?.import === "string"
+        ? target.import
+        : typeof manifest?.main === "string"
+          ? manifest.main
+          : "dist/index.js";
+  const entry = join(root, relative);
+  try {
+    return existsSync(entry) && statSync(entry).isFile()
+      ? realpathSync(entry)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function walkFromFile(file: string) {
+  try {
+    const real = realpathSync(file);
+    if (!statSync(real).isFile()) return undefined;
+    return officialEntry(findPackageRoot(real, PI_CODING_AGENT_PACKAGE));
+  } catch {
+    return undefined;
+  }
+}
+
+function fileFromUrl(fromUrl: string) {
+  return fromUrl.startsWith("file:") ? fileURLToPath(fromUrl) : fromUrl;
+}
+
+function nearestPackageRoot(file: string) {
+  let dir = dirname(file);
+  for (let depth = 0; depth < PACKAGE_ROOT_SEARCH_DEPTH; depth++) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+}
+
+function peerAt(nodeModules: string) {
+  const root = join(nodeModules, ...PI_CODING_AGENT_PACKAGE.split("/"));
+  const manifest = readManifest(join(root, "package.json"));
+  return manifest?.name === PI_CODING_AGENT_PACKAGE
+    ? officialEntry(root)
+    : undefined;
+}
+
+function resolveFromInstall(fromUrl: string) {
+  let start = fileFromUrl(fromUrl);
+  try {
+    start = realpathSync(start);
+  } catch {
+    // Keep the unresolved path when the caller file is a test stub.
+  }
+  const packageRoot = nearestPackageRoot(start);
+  if (!packageRoot) return undefined;
+
+  const nested = peerAt(join(packageRoot, "node_modules"));
+  if (nested) return nested;
+
+  const parent = dirname(packageRoot);
+  const grandparent = dirname(parent);
+  const hoistedModules =
+    basename(parent).startsWith("@") && basename(grandparent) === "node_modules"
+      ? grandparent
+      : basename(parent) === "node_modules"
+        ? parent
+        : undefined;
+  return hoistedModules ? peerAt(hoistedModules) : undefined;
+}
+
+export function validatePiCodingAgentEntry(candidate: string | undefined) {
+  if (!candidate) return undefined;
+  return walkFromFile(candidate);
+}
+
+export function missingPiCodingAgentDiagnostic() {
+  return [
+    `OpenPI Web could not resolve ${PI_CODING_AGENT_PACKAGE} for this process.`,
+    "Host resolution uses only the current process argv identity and fail-closes if that path is not the official package.",
+    `${PI_CODING_AGENT_ENTRY_ENV} is an explicit standalone handoff, not a host fallback.`,
+    `Standalone openpi web uses that handoff when valid, then the installed nested or hoisted peer (npm install ${PI_CODING_AGENT_PACKAGE}).`,
+    "From a running Pi session use /web, which hands over the host Pi.",
+    "Supported package install is `pi install npm:@tt-a1i/openpi`.",
+  ].join(" ");
+}
+
+export function resolvePiCodingAgentEntry(options?: {
+  source?: "host" | "standalone";
+  env?: NodeJS.ProcessEnv;
+  argv1?: string | undefined;
+  fromUrl?: string;
+}) {
+  const source = options?.source ?? "host";
+  if (source === "standalone") {
+    const env = options?.env ?? process.env;
+    const handed = validatePiCodingAgentEntry(env[PI_CODING_AGENT_ENTRY_ENV]);
+    if (handed) return handed;
+    return resolveFromInstall(options?.fromUrl ?? import.meta.url);
+  }
+
+  const argv1 = options?.argv1 === undefined ? process.argv[1] : options.argv1;
+  return argv1 ? walkFromFile(argv1) : undefined;
+}
+
+export function resolveStandaloneJitiAliases(options?: {
+  env?: NodeJS.ProcessEnv;
+  argv1?: string | undefined;
+  fromUrl?: string;
+}) {
+  const fromUrl = options?.fromUrl ?? import.meta.url;
+  const entry = resolvePiCodingAgentEntry({
+    ...options,
+    fromUrl,
+    source: "standalone",
+  });
+  return entry ? { [PI_CODING_AGENT_PACKAGE]: entry } : {};
+}