@fitchmultz/pi-subagents 0.49.1 → 0.50.0

package/dist/pi-intercom/tools.js

@@ -1,24 +1,71 @@
-import { validateIntercomArguments, toolError, toolText } from "./tool-arguments.js";
+import { resolveConnectedTarget } from "./connection.js";
+import { validateIntercomArguments, toolError } from "./tool-arguments.js";
 import { errorMessage } from "./validation.js";
+function lastPage(result) {
+    const identity = `${result.session.name ?? result.session.id} (${result.session.id})`;
+    const page = result.entryId === null
+        ? "No completed assistant response."
+        : `Entry: ${result.entryId}\nCharacters (UTF-16): ${result.offset}–${result.offset + result.text.length} of ${result.totalLength}`;
+    const next = result.nextOffset === undefined
+        ? ""
+        : `\nNext page: intercom(${JSON.stringify({ action: "last", to: result.session.id, entryId: result.entryId, offset: result.nextOffset })})`;
+    return {
+        content: [
+            { type: "text", text: result.text },
+            {
+                type: "text",
+                text: `Session: ${identity}\nStatus: ${result.session.status ?? "unknown"}\n${page}${next}`,
+            },
+        ],
+        details: { ...result },
+    };
+}
 export class IntercomTools {
     owners;
     constructor(owners) {
         this.owners = owners;
     }
-    async dispatch(active, params, signal, ctx) {
-        const scope = params.scope ?? "project";
+    async execute(params, signal, ctx) {
+        const invalid = validateIntercomArguments(params);
+        if (invalid) {
+            return invalid;
+        }
+        let active;
+        try {
+            active = await this.owners.connection.ensure();
+        }
+        catch (error) {
+            return toolError(`Intercom not connected: ${errorMessage(error)}`);
+        }
+        this.owners.connection.syncIdentity(ctx.sessionManager.getSessionId());
+        const scope = params.scope ?? "all";
         switch (params.action) {
-            case "subscribe":
-            case "unsubscribe":
-            case "publish":
-            case "topics":
-                return await this.owners.topicActions.execute(active, params, ctx);
             case "list":
                 return await this.owners.inspection.list(active, scope);
             case "status":
                 return await this.owners.inspection.status(active, scope, ctx);
             case "pending":
                 return this.owners.inspection.pending();
+            case "last": {
+                if (params.to === undefined || params.to === "") {
+                    return toolError("Missing 'to' parameter");
+                }
+                try {
+                    const target = (await resolveConnectedTarget(active, params.to)) ?? params.to;
+                    const result = await active.last(target, {
+                        entryId: params.entryId,
+                        offset: params.offset,
+                        limit: params.limit,
+                    });
+                    if ("error" in result) {
+                        return toolError(result.error);
+                    }
+                    return lastPage(result);
+                }
+                catch (error) {
+                    return toolError(`Failed to read last response: ${errorMessage(error)}`);
+                }
+            }
             case "send":
                 return await this.owners.outbound.send(active, params, ctx);
             case "ask":
@@ -27,25 +74,4 @@ export class IntercomTools {
                 return await this.owners.outbound.reply(active, params);
         }
     }
-    async execute(params, signal, ctx) {
-        let active;
-        try {
-            active = await this.owners.connection.ensure("tool");
-        }
-        catch (error) {
-            if (params.action === "topics") {
-                this.owners.topics.disconnected();
-                return toolText(`Broker unavailable; last saved records follow.\n${this.owners.topics.inspect(params.topic)}`, { connection: "disconnected" });
-            }
-            return toolError(`Intercom not connected: ${errorMessage(error)}`);
-        }
-        this.owners.connection.syncIdentity(ctx.sessionManager.getSessionId());
-        if (!["subscribe", "unsubscribe", "publish", "topics"].includes(params.action)) {
-            const invalid = validateIntercomArguments(params);
-            if (invalid) {
-                return invalid;
-            }
-        }
-        return await this.dispatch(active, params, signal, ctx);
-    }
 }

package/dist/pi-intercom/types.js

@@ -135,15 +135,22 @@ function validSessionTopics(session) {
         (session.topics === undefined ||
             (isUnknownArray(session.topics) && session.topics.every(isTopicUpdate))));
 }
+function validSessionLineage(value) {
+    return (optionalLabel(value.rootSessionId) &&
+        optionalLabel(value.parentSessionId) &&
+        (value.parentSessionId === undefined || value.rootSessionId === value.parentSessionId));
+}
+function validSessionProject(value) {
+    return value === undefined || (typeof value === "string" && /^[a-f0-9]{64}$/.test(value));
+}
 export function isSessionRegistration(value) {
     if (!isRecord(value) || !safeLabel(value.cwd) || !safeLabel(value.model)) {
         return false;
     }
-    const validProject = value.projectId === undefined ||
-        (typeof value.projectId === "string" && /^[a-f0-9]{64}$/.test(value.projectId));
     return (optionalLabel(value.name) &&
         optionalLabel(value.status) &&
-        validProject &&
+        validSessionLineage(value) &&
+        validSessionProject(value.projectId) &&
         validSessionHealth(value) &&
         validSessionTopics(value));
 }

package/dist/pi-intercom/ui/session-format.js

@@ -6,7 +6,7 @@ function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function localForkStartCommand() {
-    return `pi --name worker --extension ${shellQuote(path.join(PACKAGE_ROOT, "src", "pi-intercom", "index.ts"))} --skill ${shellQuote(path.join(PACKAGE_ROOT, "skills", "pi-intercom"))}`;
+    return `pi --name worker --extension ${shellQuote(path.join(PACKAGE_ROOT, "src", "index.ts"))}`;
 }
 function duplicateNames(sessions) {
     const names = sessions
@@ -101,7 +101,7 @@ function noPeers(hidden) {
     }
     return `No other sessions connected. Start another intercom-enabled session with \`pi --name worker\`, then run \`intercom({ action: "list" })\` again. If you are dogfooding this local fork without installing it, start the peer with \`${localForkStartCommand()}\`.`;
 }
-export function formatSessionListSections(allSessions, id, scope = "project") {
+export function formatSessionListSections(allSessions, id, scope = "all") {
     const current = allSessions.find((session) => session.id === id);
     if (!current) {
         throw new Error("Current session is missing from intercom session list.");
@@ -118,7 +118,7 @@ export function formatSessionListSections(allSessions, id, scope = "project") {
     const currentSection = `**Current session:**\n${row(current, { ...options, self: true })}`;
     const otherSection = `**Other sessions:**\n${others.length === 0 ? noPeers(hidden) : others.map((session) => row(session, { ...options, self: false })).join("\n")}`;
     const hint = hidden > 0
-        ? `\n\n${hidden} session${hidden === 1 ? "" : "s"} in other projects hidden. Use \`intercom({ action: "list", scope: "all" })\` to show every connected session.`
+        ? `\n\n${hidden} session${hidden === 1 ? "" : "s"} in other projects hidden. Use \`intercom({ action: "list", scope: "all" })\` to show every reachable session.`
         : "";
     return `${currentSection}\n\n${otherSection}${hint}`;
 }

package/dist/shared/journal-projections.js

@@ -1,35 +1,4 @@
 import { isUnknownArray, recordAt } from "./unknown.js";
-function resultField(path) {
-    if (path.length === 2) {
-        return path[0] === "result";
-    }
-    if (path.length === 3) {
-        return path[0] === "results" && typeof path[1] === "number";
-    }
-    return (path.length === 4 &&
-        path[0] === "children" &&
-        typeof path[1] === "number" &&
-        path[2] === "result");
-}
-function summaryField(path) {
-    return ((path.length === 1 && path[0] === "summary") ||
-        (path.length === 3 &&
-            path[0] === "children" &&
-            typeof path[1] === "number" &&
-            path[2] === "summary"));
-}
-export const ownerProjection = (path) => {
-    const field = path.at(-1);
-    if (resultField(path)) {
-        if (field === "messages") {
-            return false;
-        }
-        if (["output", "finalOutput", "initialOutput", "rawOutput"].includes(String(field))) {
-            return 8192;
-        }
-    }
-    return summaryField(path) ? 8192 : true;
-};
 const entryFields = new Set([
     "type",
     "id",

package/dist/shared/types.js

@@ -1,26 +1,5 @@
-/** Public compatibility barrel. Domain contracts depend on each other, never on implementation modules. */
 import * as os from "node:os";
 import * as path from "node:path";
-export const INTERCOM_DETACH_REQUEST_EVENT = "pi-intercom:detach-request";
-export const INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
-export const SUBAGENT_ASYNC_STARTED_EVENT = "subagent:async-started";
-export const SUBAGENT_ASYNC_COMPLETE_EVENT = "subagent:async-complete";
-export const SUBAGENT_CONTROL_EVENT = "subagent:control-event";
-export const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
-export const SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
-export const SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom-delivery";
-export const SUBAGENT_LIVE_INTERCOM_EVENT = "subagent:live-intercom";
-export const SUBAGENT_LIVE_INTERCOM_DELIVERY_EVENT = "subagent:live-intercom-delivery";
-export const SUBAGENT_INTERCOM_HEALTH_REQUEST_EVENT = "subagent:intercom-health-request";
-export const SUBAGENT_INTERCOM_HEALTH_RESPONSE_EVENT = "subagent:intercom-health-response";
-export const SUBAGENT_INTERCOM_IDENTITY_REQUEST_EVENT = "subagent:intercom-identity-request";
-export const SUBAGENT_INTERCOM_IDENTITY_RESPONSE_EVENT = "subagent:intercom-identity-response";
-// Constants
-// ============================================================================
-export const DEFAULT_MAX_OUTPUT = {
-    bytes: 200 * 1024,
-    lines: 5000,
-};
 function sanitizeTempScopeSegment(value) {
     const sanitized = value
         .trim()
@@ -65,8 +44,6 @@ function resolveHomeTempScopeId() {
     }
     return "shared";
 }
-const MAX_PARALLEL = 8;
-export const MAX_CONCURRENCY = 4;
 export function resolveTempRootDir(configured = process.env.PI_SUBAGENT_TEMP_ROOT) {
     const fallback = path.join(os.tmpdir(), `pi-subagents-${resolveTempScopeId()}`);
     if (configured === undefined || configured.trim().length === 0) {
@@ -78,175 +55,3 @@ export function resolveTempRootDir(configured = process.env.PI_SUBAGENT_TEMP_ROO
     }
     return resolved;
 }
-export const TEMP_ROOT_DIR = resolveTempRootDir();
-export const RESULTS_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-results");
-export const ASYNC_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-runs");
-export const RUNNER_ERROR_LOG_FILE = "runner-error.log";
-export const CHAIN_RUNS_DIR = path.join(TEMP_ROOT_DIR, "chain-runs");
-export const TEMP_ARTIFACTS_DIR = path.join(TEMP_ROOT_DIR, "artifacts");
-export const WIDGET_KEY = "subagent-async";
-export const SLASH_RESULT_TYPE = "subagent-slash-result";
-export const SLASH_SUBAGENT_REQUEST_EVENT = "subagent:slash:request";
-export const SLASH_SUBAGENT_STARTED_EVENT = "subagent:slash:started";
-export const SLASH_SUBAGENT_RESPONSE_EVENT = "subagent:slash:response";
-export const SLASH_SUBAGENT_UPDATE_EVENT = "subagent:slash:update";
-export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
-export const POLL_INTERVAL_MS = 1000;
-export const MAX_WIDGET_JOBS = 4;
-export const DEFAULT_SUBAGENT_MAX_DEPTH = 1;
-export const SUBAGENT_ACTIONS = [
-    "list",
-    "get",
-    "create",
-    "update",
-    "delete",
-    "status",
-    "history",
-    "search",
-    "interrupt",
-    "extend",
-    "resume",
-    "nudge",
-    "questions",
-    "answer",
-    "review",
-    "doctor",
-];
-export const DEFAULT_FORK_PREAMBLE = "You are a delegated subagent running from a fork of the parent session. " +
-    "Treat the inherited conversation as reference-only context, not a live thread to continue. " +
-    "Do not continue or answer prior messages as if they are waiting for a reply. " +
-    "Your sole job is to execute the task below and return a focused result for that task using your tools.";
-function normalizeTopLevelParallelValue(value) {
-    let parsed = NaN;
-    if (typeof value === "number") {
-        parsed = value;
-    }
-    else if (typeof value === "string") {
-        parsed = Number(value);
-    }
-    if (!Number.isInteger(parsed) || parsed < 1) {
-        return undefined;
-    }
-    return parsed;
-}
-export function resolveTopLevelParallelMaxTasks(value) {
-    return normalizeTopLevelParallelValue(value) ?? MAX_PARALLEL;
-}
-export function resolveTopLevelParallelConcurrency(override, configValue) {
-    return (normalizeTopLevelParallelValue(override) ??
-        normalizeTopLevelParallelValue(configValue) ??
-        MAX_CONCURRENCY);
-}
-export function getAsyncConfigPath(suffix) {
-    return path.join(TEMP_ROOT_DIR, `async-cfg-${suffix}.json`);
-}
-export function wrapForkTask(task, preamble) {
-    if (preamble === false) {
-        return task;
-    }
-    const effectivePreamble = preamble ?? DEFAULT_FORK_PREAMBLE;
-    const wrappedPrefix = `${effectivePreamble}\n\nTask:\n`;
-    if (task.startsWith(wrappedPrefix)) {
-        return task;
-    }
-    return `${wrappedPrefix}${task}`;
-}
-// ============================================================================
-// Recursion Depth Guard
-// ============================================================================
-export function normalizeMaxSubagentDepth(value) {
-    let parsed = NaN;
-    if (typeof value === "number") {
-        parsed = value;
-    }
-    else if (typeof value === "string") {
-        parsed = Number(value);
-    }
-    if (!Number.isInteger(parsed) || parsed < 0) {
-        return undefined;
-    }
-    return parsed;
-}
-export function resolveCurrentMaxSubagentDepth(configMaxDepth) {
-    return (normalizeMaxSubagentDepth(process.env.PI_SUBAGENT_MAX_DEPTH) ??
-        normalizeMaxSubagentDepth(configMaxDepth) ??
-        DEFAULT_SUBAGENT_MAX_DEPTH);
-}
-export function resolveChildMaxSubagentDepth(parentMaxDepth, agentMaxDepth) {
-    const normalizedParent = normalizeMaxSubagentDepth(parentMaxDepth) ?? DEFAULT_SUBAGENT_MAX_DEPTH;
-    const normalizedAgent = normalizeMaxSubagentDepth(agentMaxDepth);
-    return normalizedAgent === undefined
-        ? normalizedParent
-        : Math.min(normalizedParent, normalizedAgent);
-}
-function parseSubagentDepth(value) {
-    if (value === undefined || value === null || value === "") {
-        return 0;
-    }
-    const depth = Number(value);
-    return Number.isInteger(depth) && depth >= 0 ? depth : undefined;
-}
-export function checkSubagentDepth(configMaxDepth) {
-    const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
-    const depth = parseSubagentDepth(process.env.PI_SUBAGENT_DEPTH);
-    if (depth === undefined) {
-        return { blocked: true, depth: maxDepth, maxDepth };
-    }
-    return { blocked: depth >= maxDepth, depth, maxDepth };
-}
-export function getSubagentDepthEnv(maxDepth) {
-    const childMaxDepth = normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth();
-    const parentDepth = parseSubagentDepth(process.env.PI_SUBAGENT_DEPTH);
-    const nextDepth = parentDepth === undefined ? childMaxDepth : parentDepth + 1;
-    return {
-        PI_SUBAGENT_DEPTH: String(nextDepth),
-        PI_SUBAGENT_MAX_DEPTH: String(childMaxDepth),
-    };
-}
-// ============================================================================
-// Utility Functions
-// ============================================================================
-function formatBytes(bytes) {
-    if (bytes < 1024) {
-        return `${bytes}B`;
-    }
-    if (bytes < 1024 * 1024) {
-        return `${(bytes / 1024).toFixed(1)}KB`;
-    }
-    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-}
-export function truncateOutput(output, config, artifactPath) {
-    const lines = output.split("\n");
-    const bytes = Buffer.byteLength(output, "utf-8");
-    if (bytes <= config.bytes && lines.length <= config.lines) {
-        return { text: output, truncated: false };
-    }
-    let truncatedLines = lines;
-    if (lines.length > config.lines) {
-        truncatedLines = lines.slice(0, config.lines);
-    }
-    let result = truncatedLines.join("\n");
-    if (Buffer.byteLength(result, "utf-8") > config.bytes) {
-        let low = 0;
-        let high = result.length;
-        while (low < high) {
-            const mid = Math.floor((low + high + 1) / 2);
-            if (Buffer.byteLength(result.slice(0, mid), "utf-8") <= config.bytes) {
-                low = mid;
-            }
-            else {
-                high = mid - 1;
-            }
-        }
-        result = result.slice(0, low);
-    }
-    const keptLines = result.split("\n").length;
-    const marker = `[TRUNCATED: showing first ${keptLines} of ${lines.length} lines, ${formatBytes(Buffer.byteLength(result))} of ${formatBytes(bytes)}${artifactPath !== undefined && artifactPath.length > 0 ? ` - full output at ${artifactPath}` : ""}]\n`;
-    return {
-        text: marker + result,
-        truncated: true,
-        originalBytes: bytes,
-        originalLines: lines.length,
-        artifactPath,
-    };
-}

package/docs/code-quality.md

@@ -26,7 +26,7 @@ Tests retain complexity 15, depth 4 and parameters 6. Cohesive test suites have
 no size or statement limits.
 
 Formatting uses width 100, two spaces, LF and double quotes. npm owns lockfile
-formatting. Generated runtime schemas and build outputs keep their own bytes.
+formatting. Build outputs keep their own bytes.
 The VS Code Oxc extension uses these same lint and formatting configurations.
 
 `npm run ci` runs lint, formatting, TypeScript, package/install smokes and all
@@ -34,5 +34,6 @@ tests. CI separately qualifies the latest official Pi on GitHub-hosted Linux and
 the maintained fork on Linux and macOS. There is no custom checker build, probe
 suite or self-hosted runner requirement.
 
-CI's lint job also checks schema/validator drift against the committed dev dependencies,
-before qualification substitutes the selected host graph.
+CI's lint job also enforces the production line/byte shrink budget before
+qualification substitutes the selected host graph. The retired workflow schema
+generator and its patching dependency are not part of the new runtime.

package/docs/development.md

@@ -1,99 +1,61 @@
-# Development and validation
+# Development
 
-[Getting started](../README.md) · [Subagents reference](reference.md)
-
-## Local validation
-
-See [Code quality](code-quality.md) for the strict Oxlint/Oxfmt rules and commands. `npm run ci` runs lint and formatting before TypeScript, package checks and tests.
-
-`npm run check:compat` uses the selected host installed in this checkout, never a hidden Pi from PATH. It runs full CI with actual native editor receipts: a supplied clean `PI_EDITOR_RECEIPT_TEST_ROOT` stays read-only, otherwise the owning runner snapshots public `pi-apply-edits` main once in a temporary checkout, records its exact Git SHA, installs only its third-party runtime dependencies, and cleans its owned copy. Repository CI resolves that editor SHA once for all host/platform lanes. It checks host SDK/manifest-bin identity, typechecks, builds, and qualifies both compiled entries with a private Intercom broker through the native SDK and bundled RPC CLI. Official hosts exercise same/different-cwd resume, acceptance, structured output, native result routing/ownership and tool activation. No provider credentials or inference services are used.
-
-Repository CI resolves latest stable official Pi and maintained fork main once, then freezes that version/SHA across the Linux/macOS lanes and release qualification. Full `npm run ci`, selected-host native contracts, Git production builds and packed-install smokes remain required.
-
-Fork jobs supply `PI_COMPAT_HOST=fork`, `PI_COMPAT_EXPECTED_VERSION`, `PI_COMPAT_EXPECTED_PACKAGE_DIR`, `PI_HOST_INDEX`, and `PI_HOST_CLI` to verify the selected SDK and CLI. The official job uses the resolved latest stable cohort with `PI_COMPAT_HOST=official`. Both targets use ordinary 1.0 lifecycle and finalized tool-result accounting, without checkpoint, immediate-usage or pending-call APIs. Unsupported hosts fail qualification rather than skip native checks. See [host capabilities](reference.md#host-capabilities-and-result-delivery) and [limitations](intercom.md#limitations).
-
-For a fresh development worktree, run `npm ci` before launching Pi there: project-local `.pi/extensions` can autoload before dependencies exist. Alternatively launch from a neutral directory and use `change_dir` to enter the owned worktree after startup. Do not disable all extensions or remove project extensions to hide missing dependencies.
-
-Use an empty HOME outside your real home ancestry and a short temporary directory whose ancestors have no project/package or agent markers. Set HOME, TMPDIR, TMP, TEMP, cache and fixture cwd consistently; never create mutable fixtures beneath the real home or retained evidence directory. Child tests use local fixtures and their own broker/profile. CI runs the latest Node 24 release on Linux and macOS without claiming a full platform-by-host matrix.
-
-The completion guard recognizes verified `modifiedFiles` receipts from pi-apply-edits v1's `apply_patch`, `replace_text`, and `write_files`, including partial publication errors. Previews and unchanged results do not count as mutations. To exercise the real editor through native SDK events, use an installed v1 editor checkout:
-
-```bash
-PI_EDITOR_RECEIPT_TEST_ROOT=/absolute/path/to/pi-apply-edits \
-  node --test test/integration/native-editor-receipts.test.ts
-```
-
-`PI_EDITOR_RECEIPT_TEST_SDK` selects another installed host package root; `PI_EDITOR_RECEIPT_EVIDENCE_DIR` retains receipts and fixture files. Without an editor checkout, this optional integration test skips.
-
-### SDK embeddings of runtime-only installations
-
-Before loading a pruned package with `DefaultResourceLoader`, set `process.env.PI_PACKAGE_DIR = getPackageDir()` from the **selected SDK**. This is the existing host-location contract for native session APIs and detached runners. Alternatively the host must be discoverable through the extension's dependency graph or an actual Pi executable on PATH. CLI consumers resolve their own host normally.
-
-Detached history workers need one of those host-location sources to resolve the selected host's terminal-stripping implementation. The parent uses Pi's normal extension-loader imports without loading another runtime. Qualification covers both the explicit-host SDK path and the real bundled CLI with a production-only package.
-
-To diagnose the full suite against the locked published Pi dependencies:
+Use a dedicated worktree, the committed npm lockfile, and a ready-for-review PR.
+Never edit source or tests while checks run in that checkout. Do not modify an
+active installed copy or reload the user's sessions to test a candidate.
 
 ```bash
 npm ci
-npm run ci
-```
-
-The [host limitations](intercom.md#limitations) include historical official 0.87.1 results. Retain distinct queue and prompt-preparation checks and report their actual results for the selected host; portable qualification does not establish a full-suite pass.
-
-That command runs TypeScript no-emit checking, package shape smoke checks, an isolated single-package install smoke, and the full unit/integration suite. The bundled agent tests cover the Fitch profile set directly, so validation does not require pi-fitch-kit. `npm test` is intentionally the fast unit-test shortcut (`npm run test:unit`), not the full completion gate.
-
-For a credential-free Linux gate against committed `HEAD`, Docker and `PI_LINUX_PI_ARCHIVE` are required. Supply an absolute path to a `.tar.gz` containing one top-level `pi/`: a Pi 1.0 source checkout, its Linux `node_modules` (including workspace dependencies), and all built `dist/` output. It must include `pi/packages/coding-agent/dist/index.js` and `pi/packages/coding-agent/dist/bundle/cli.js`.
-
-Prepare that checkout in a clean Linux build environment matching the image's CPU architecture and Node version. Install locked dependencies and complete Pi's workspace build, including its generated model data, before archiving. Do not copy host `node_modules`, Pi user state, `auth.json`, secret `.env` files, or credential-bearing npm/Git configuration. From the Linux build environment:
-
-```bash
-tar -czf /absolute/path/native-pi-linux-node24.tar.gz -C /clean/linux-build pi
-```
-
-Run with an archive matching the image:
-
-```bash
-PI_LINUX_PI_ARCHIVE=/absolute/path/native-pi-linux-node24.tar.gz \
-  bash scripts/linux-smoke.sh
-```
-
-The archive is mounted read-only and extracted to `/native-pi`. The unprivileged `node` user installs locked package dependencies in `/workspace`, points the private CLI link and all SDK overrides at the supplied build, and runs the full, unchanged `npm run ci` gate. No host home, source mount, credentials, or model calls are passed into it. The gate does not patch Pi/Jiti or skip native cases.
-
-## Real Pi smoke
-
-The default local gate includes real SDK reload/reopen and native child-session ownership checks with a controlled CLI and no model calls. Other execution tests stay mock-heavy and deterministic. When you need to verify the actual local file-path Pi package boundary, run the opt-in real smoke:
-
-```bash
-export PATH="$PWD/node_modules/.bin:$PATH"
-node scripts/real-pi-smoke.mjs
-```
-
-Use direct `node` invocation with the intended `pi` first on `PATH`. npm scripts prepend `node_modules/.bin`.
-
-It installs this checkout into an isolated temporary Pi home, runs `pi list`, and loads the bundled subagent and intercom extensions. It does not install pi-fitch-kit, publish to npm, or use GitHub Actions.
-
-Live model-backed subagent paths are intentionally opt-in because they can use provider credentials and tokens:
-
-```bash
-PI_REAL_SMOKE_MODEL=openai/gpt-6-astra node scripts/real-pi-smoke.mjs --llm
-```
-
-That mode copies local `auth.json` and `models.json` into the isolated Pi agent dir, then asks a real Pi session to exercise intercom status plus subagent list, waiting execution, background launch, and background completion. Set `PI_REAL_SMOKE_AUTH_AGENT_DIR` if your auth files are not in `~/.pi/agent`.
-
-For a broader live gate, add `--llm-full`:
-
-```bash
-PI_REAL_SMOKE_MODEL=openai/gpt-6-astra node scripts/real-pi-smoke.mjs --llm-full
-```
-
-That also verifies real parallel, chain, file output, and acceptance flows. It checks actual tool calls and native settlement, and audits saved parent/child model identities. The smoke stops its own processes before removing copied credentials or artifacts, including on timeout or handled cancellation. Use `--keep-temp` to preserve noncredential evidence.
-
-## Local test watchdog
-
-`npm test`, `npm run test:unit`, `npm run test:integration`, and `npm run test:all` run through `scripts/run-tests.mjs`, which applies a per-suite local watchdog so hung child-process or worktree tests fail with the command context instead of hanging forever. The default is 300000ms for units and 1200000ms for integration. Override it when debugging slow local runs:
-
-```bash
-PI_TEST_TIMEOUT_MS=1800000 npm run test:integration
-# or
-node scripts/run-tests.mjs integration --timeout-ms 1800000
-```
+npm run lint
+npm run format:check
+npm run typecheck
+node scripts/measure-size.mjs
+```
+
+Run narrow owner-boundary tests locally through `scripts/run-tests.mjs`. Full
+`npm run ci` belongs in hosted CI and includes package/install smokes and the
+complete suites. Keep the strict Oxlint/Oxfmt rules; see [code quality](code-quality.md).
+
+## Runtime qualification
+
+Qualify the latest stable official Pi and the intended fork revision separately.
+Record the exact package root, revision/build, Node binary, and executed test
+commands. Matching versions do not establish matching runtime behavior.
+
+Production-only installs must resolve the selected host's SDK and TypeBox, not
+shadow them with this package's development graph. Exercise the packed single
+entry through the real Pi loader and an actual native child session. Native faux
+providers can test tools, receipts, journals, process lifecycle and output without
+paid model calls; they are not live-model evidence.
+
+Real-model acceptance additionally checks that full forked history preserves an
+actual earlier delegation result, and that ordinary main/child sessions discover,
+message, and read last responses across agent directories under the confirmed
+two-level topology. Never publish credentials or private transcripts as evidence.
+
+## Isolation and safety
+
+Every test/smoke broker uses a short, explicit `PI_INTERCOM_RUNTIME_DIR` owned by
+the fixture. Do not touch `/tmp/pi-intercom-<uid>` to test namespace behavior on a
+workstation with active sessions. Tests for the default path inspect it without
+starting or deleting the user's broker. Stop owned processes and remove temporary
+resources even on failure or signal cancellation.
+
+Preserve native receipt, cold-crash, shutdown, continuation and broker contracts
+at their actual SDK, journal, filesystem or process boundary. Carry distinct
+assertions into the keeper before deleting an old test. Feature retirement is not
+proof that an unrelated safety assertion can disappear. Expected values must be
+independent of production helpers; observe actual readiness/publication before
+negative assertions. A sleep does not prove an owner processed its input.
+
+## Size gate
+
+`scripts/measure-size.mjs` counts source, production scripts, generated code and
+schemas, including new untracked files. `--report` prints without enforcing.
+The ceilings are 16,000 source TypeScript lines, 20,000 total production lines,
+and 1 MiB total production bytes. Tests have no deletion quota. Moving machinery
+into generated/minified output does not evade the gate.
+
+[The rebuild evidence](single-agent-rebuild.md) records the baseline, confirmed
+design, test-transfer obligations, and exact selected host identities. Update it
+with measured final evidence; do not confuse planned gates with passed checks.