@llblab/pi-kit 0.3.2 → 0.4.0

package/node_modules/@llblab/pi-actors/skills/music-player/scripts/playback.mjs

@@ -27,7 +27,7 @@ import {
   watch,
   writeFileSync,
 } from "node:fs";
-import { createServer } from "node:net";
+import { createConnection, createServer } from "node:net";
 import { homedir } from "node:os";
 import {
   basename,
@@ -66,7 +66,7 @@ let updateRunControlStatusInStateDir;
 let isAlive;
 let verifyRunProcessIdentity;
 let appendRunTraceEvent = () => {};
-if (actorAdapterEnabled) {
+async function loadActorAdapter() {
   ({
     appendRunControlInStateDir,
     claimRunControlByIdInStateDir,
@@ -110,8 +110,9 @@ function usage() {
   playback.mjs control <state-dir> <play|pause|toggle|next|previous|seek|volume|stop|status> [percent]
 
 Runs a foreground music player so pi-actors can own it as a controlled Run.
-Controls use canonical records in <state-dir>/controls.jsonl.
-Prefer message target=run:<run> action=<command>, or use direct control commands below.
+Actor-owned controls use canonical records in <state-dir>/controls.jsonl.
+Standalone controls use the generation-fenced playback service endpoint.
+Prefer message target=run:<run> action=<command> for Actors; external adapters use control <state-dir> <action>.
 Supported players: auto, mpv, afplay, ffplay, cvlc, play, wmp.
 `);
 }
@@ -1134,6 +1135,7 @@ function readAndClearCommand(ctx) {
 }
 
 async function playMain(args) {
+  if (actorAdapterEnabled) await loadActorAdapter();
   const [
     sourceArg,
     loopArg = "true",
@@ -1333,30 +1335,74 @@ function projectCurrentProgress(status, nowMs = Date.now()) {
   };
 }
 
-function actorControlAvailability(stateDir) {
+async function actorControlAvailability(stateDir) {
   const run = readJsonFile(join(stateDir, "run.json"), {});
   const result = readJsonFile(join(stateDir, "result.json"), {});
   const endpoint = readJsonFile(join(stateDir, "control-endpoint.json"), {});
   const playerStatus = readJsonFile(join(stateDir, "player.json"), {});
+  const runInstanceId = typeof run.run_instance_id === "string"
+    ? run.run_instance_id
+    : undefined;
+  // Inactive status must remain readable without an installed Actor runtime,
+  // including standalone state beside metadata from a rejected Actor launch.
+  if (!runInstanceId || typeof result.completedAt === "string" ||
+      endpoint.run_instance_id !== runInstanceId ||
+      !["playing", "paused"].includes(playerStatus.state)) {
+    return { available: false, runInstanceId };
+  }
+  if (!verifyRunProcessIdentity) {
+    await loadActorAdapter();
+    // Re-read authority after the asynchronous import before admitting control.
+    return actorControlAvailability(stateDir);
+  }
   const pid = Number(run.pid || 0);
   const hasProcessIdentity = pid > 0 || run.process_identity !== undefined;
   const processIdentity = pid > 0
     ? verifyRunProcessIdentity(pid, run.process_identity)
     : { valid: false };
-  const available =
-    typeof run.run_instance_id === "string" &&
-    typeof result.completedAt !== "string" &&
-    (!hasProcessIdentity || (pid > 0 && isAlive(pid) && processIdentity.valid === true)) &&
-    endpoint.run_instance_id === run.run_instance_id &&
-    ["playing", "paused"].includes(playerStatus.state);
   return {
-    available,
-    runInstanceId: typeof run.run_instance_id === "string"
-      ? run.run_instance_id
-      : undefined,
+    available: !hasProcessIdentity ||
+      (pid > 0 && isAlive(pid) && processIdentity.valid === true),
+    runInstanceId,
   };
 }
 
+async function sendPlaybackCommand(endpoint, action, input) {
+  const payload = `${JSON.stringify({
+    action,
+    ...(input !== undefined ? { input } : {}),
+    service_instance_id: endpoint.service_instance_id,
+  })}\n`;
+  const response = await new Promise((resolveResponse, rejectResponse) => {
+    const socket = createConnection(endpoint.path);
+    let content = "";
+    const timeout = setTimeout(() => {
+      socket.destroy(new Error("playback service command timed out"));
+    }, 5_000);
+    timeout.unref?.();
+    socket.setEncoding("utf8");
+    socket.on("connect", () => socket.write(payload));
+    socket.on("data", (chunk) => {
+      content += chunk;
+      if (Buffer.byteLength(content, "utf8") > 4096) {
+        socket.destroy(new Error("playback service response is too large"));
+      }
+    });
+    socket.on("close", () => clearTimeout(timeout));
+    socket.on("error", rejectResponse);
+    socket.on("end", () => {
+      try {
+        resolveResponse(JSON.parse(content.trim()));
+      } catch {
+        rejectResponse(new Error("playback service returned invalid JSON"));
+      }
+    });
+  });
+  if (response?.ok !== true) {
+    throw new Error(response?.error || "playback service rejected the command");
+  }
+}
+
 async function controlMain(args) {
   const stateDir = expandPath(args[0] || "");
   const command = args[1] || "status";
@@ -1365,13 +1411,20 @@ async function controlMain(args) {
     usage();
     process.exit(2);
   }
-  mkdirSync(stateDir, { recursive: true });
+  if (!CONTROL_COMMANDS.has(command)) fail(`unsupported command: ${command}`, 2);
+  const endpoint = readJsonFile(join(stateDir, "playback-endpoint.json"), {});
+  // A standalone service retains authority even if an unsuccessful Actor launch
+  // left Run metadata beside its endpoint. Clients never start or adopt it.
+  const actorOwned = endpoint.owner_mode !== "standalone" &&
+    existsSync(join(stateDir, "run.json"));
   if (command === "status") {
     const statusFile = join(stateDir, "player.json");
     const status = exists(statusFile)
       ? readJsonFile(statusFile, { state: "unknown" })
       : { state: "unknown" };
-    const actor = actorControlAvailability(stateDir);
+    const actor = actorOwned
+      ? await actorControlAvailability(stateDir)
+      : { available: false };
     process.stdout.write(`${JSON.stringify({
       ...projectCurrentProgress(status),
       actor_available: actor.available,
@@ -1381,7 +1434,7 @@ async function controlMain(args) {
     })}\n`);
     return;
   }
-  if (!actorControlAvailability(stateDir).available) {
+  if (actorOwned && !(await actorControlAvailability(stateDir)).available) {
     fail(`Run playback is not active: ${stateDir}`, 3);
   }
   let input;
@@ -1396,6 +1449,20 @@ async function controlMain(args) {
       fail(error instanceof Error ? error.message : String(error), 2);
     }
   }
+  if (!actorOwned) {
+    if (endpoint.owner_mode !== "standalone" ||
+        typeof endpoint.path !== "string" || !endpoint.path ||
+        typeof endpoint.service_instance_id !== "string" || !endpoint.service_instance_id) {
+      fail(`standalone playback service is not active: ${stateDir}`, 3);
+    }
+    try {
+      await sendPlaybackCommand(endpoint, command === "resume" ? "play" : command, input);
+      console.log(`music-player: command=${command} handled state_dir=${stateDir}`);
+      return;
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error), 3);
+    }
+  }
   const queued = appendControl(
     { controlsFile: join(stateDir, "controls.jsonl"), stateDir },
     command,

package/node_modules/@llblab/pi-actors/skills/swarm/SKILL.md

@@ -9,13 +9,9 @@ Use multi-actor execution only when at least two scopes or evidence lenses are m
 
 Read `actors` first for generic Recipe, spawn, Run, Trace, Control, artifact, and lifecycle operation. This Skill owns only multi-actor methodology: decomposition, scope ownership, independence, synthesis, integration, and completion proof.
 
-## Coordinator topology
+## Coordinator and participants
 
-A swarm can be coordinated without an external gateway. In this model the current host agent is the declarative control plane, the actor kernel creates explicit participant Runs, and companion transports provide ingress or presence without owning hidden agent creation. The coordinator retains user authority, global context, decomposition, shared-surface ownership, integration, and final validation; participants own bounded concrete tasks and report evidence.
-
-This resembles gateway orchestration in dependency direction but not in ownership: the coordinator is itself an agent instance with inspectable Runs, not an infrastructure service that implicitly creates sessions. Preserve that distinction in prompts, docs, recovery, and target routing.
-
-Once work is delegated, keep the coordinator available for decisions and integration instead of duplicating participant implementation. Wait for the settled completion batch by default; use meaningful attention or evidence-based timers for overdue work rather than a tight inspection loop.
+The coordinator owns decomposition, shared contracts, integration order, and final validation. Participants own bounded tasks or evidence lenses. Keep the coordinator available for decisions instead of duplicating participant implementation; use `actors` for launch, observation, and lifecycle mechanics.
 
 ## Reasoning allocation
 

package/node_modules/@llblab/pi-actors/skills/swarm/references/development-swarm.md

@@ -14,38 +14,9 @@ Use a development swarm only when all are true:
 
 Do not parallelize implementation when tasks need the same central files, semantic ordering dominates wall-clock time, or the likely conflicts would invalidate the decomposition. Use planning or review first.
 
-## Coordinator role separation
+## Roles and reasoning
 
-In a host-coordinator topology, the current Pi instance owns the declarative outcome and participant graph rather than acting as the default implementation worker. It may receive intent through Telegram or another companion extension, but transport does not become a gateway or gain hidden instance-creation authority; participant creation remains an explicit actor-kernel Run.
-
-The coordinator should:
-
-- Translate high-level intent into bounded task cards and dependency edges.
-- Keep user authority, shared contracts, integration order, and final validation local.
-- Remain available for checkpoints, permissions, conflicts, and changing evidence.
-- Consume terminal handoffs, durable artifacts, and Trace attention instead of mirroring participant work.
-- Check overdue work on an evidence-based timer; never replace event-driven completion with a rapid polling loop.
-
-A participant should:
-
-- Own one concrete execution or evidence boundary.
-- Avoid global orchestration and undeclared participant creation.
-- Return a bounded handoff that lets the coordinator decide without replaying the entire task.
-
-Use one ordinary Run under `actors` when only one worker is delegated. Activate this development-swarm protocol when two or more participants, parallel ownership, or explicit integration edges exist. Keep trivial single-boundary work inline when delegation overhead has no compensating value.
-
-## Reasoning profiles
-
-| Role | Default | Raise or fan out when |
-| --- | --- | --- |
-| Bounded implementation author | Reasoning off | The card explicitly owns unresolved diagnosis or design judgement |
-| Reviewer | Medium reasoning, clean context | Stakes require independent lenses or repeated judges |
-| Synthesizer / integrator | Medium reasoning | Evidence conflicts, shared contracts move, or merge order is semantic |
-| Coordinator | Sufficient for decomposition and decisions | Scope, authority, or architecture remains unresolved |
-
-Prefer independent review after implementation over asking one author thread to implement, retain all local assumptions, and then certify itself. When risk justifies the cost, use multiple independent reviewers: different lenses increase breadth, while repeated judges increase confidence. Preserve minority high-impact findings and merge only evidence-backed conclusions.
-
-More reviewers are not automatically better. Do not fan out when they would inspect unstable code, share contaminated context, repeat one unsupported claim, or exceed the value of the decision. Never change an already-running participant solely to enforce a newer profile; add a fresh review boundary if evidence remains open.
+Apply [Swarm's coordinator and reasoning contract](../SKILL.md#reasoning-allocation). Task cards record those profiles and the owned execution boundary; participants return evidence without undeclared orchestration. Do not fan out review over unstable code or contaminated context. The sections below specify development-only task cards, ownership transfers, conflict reports, and integration.
 
 ## Decompose by ownership
 

package/node_modules/@llblab/pi-clean-room/AGENTS.md

@@ -0,0 +1,5 @@
+# Agent Notes
+
+- `Isolation boundary`: Keep clean-room isolation process-based. Do not simulate isolation by filtering an already-loaded parent runtime because sibling extension handlers cannot be reliably unregistered.
+- `Terminal ownership`: Launch nested Pi only through `ctx.ui.custom()`, stop the parent TUI before inheriting stdio, and restart plus fully rerender it after the child exits.
+- `Zero configuration`: Keep `/clean-room <extension...>` as the complete user contract. Resolve project-local names before global names and do not add profiles or persisted configuration without a new requirement.

package/node_modules/@llblab/pi-clean-room/BACKLOG.md

@@ -0,0 +1,3 @@
+# Backlog
+
+No open implementation work.

package/node_modules/@llblab/pi-clean-room/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.1: Isolation and terminal recovery fixes
+
+- Keep unselected append-system context excluded when selected global prompt files are missing.
+- Restore the parent TUI after launch exceptions and report process startup errors, signal termination, and unsuccessful exits after terminal ownership returns.
+- Resolve every source-file suffix offered by extension-name completion while preserving project-local precedence.
+- Publish version-tag releases through GitHub Actions and npm Trusted Publisher, with provenance and post-publication identity checks.
+- Include the Clean Room banner in the package and project presentation.
+
+## 0.1.0
+
+- Added `/clean-room` to launch an isolated nested Pi TUI with optional extension allowlisting.
+- Preserved the current working directory, model, and thinking level while disabling discovered extensions, skills, prompts, themes, context files, and file-backed system prompt overrides.
+- Added installed-extension completion and deterministic project-local-over-global name resolution.

package/node_modules/@llblab/pi-clean-room/README.md

@@ -0,0 +1,61 @@
+# pi-clean-room
+
+![pi-clean-room banner](https://raw.githubusercontent.com/llblab/pi-clean-room/main/banner.jpg)
+
+Launch a fresh, isolated Pi TUI with only the extensions you explicitly select. The parent session pauses while the clean-room owns the terminal and returns unchanged when the nested Pi exits.
+
+## Installation
+
+Requirements: Pi `0.84.4–0.84.x` and Node.js `22.19.0` or newer.
+
+Install from npm:
+
+```bash
+pi install npm:@llblab/pi-clean-room
+```
+
+Or install from GitHub:
+
+```bash
+pi install git:github.com/llblab/pi-clean-room
+```
+
+Pi packages execute with full user permissions; review the source before installing, as with any extension.
+
+## Usage
+
+Install or load this extension, then run:
+
+```text
+/clean-room
+/clean-room pi-extension-name
+/clean-room skills agents system append-system
+/clean-room skills pi-extension-name pi-actors
+/clean-room skills/brain-storm
+```
+
+Arguments may be extension names or resource switches:
+
+- `skills` — enable normal Pi skill discovery, including global (`~/.pi/agent/skills`, `~/.agents/skills`), project, package, and configured skills
+- `skills/<name>` — load only that skill from known global or project skill directories (for example, `skills/brain-storm`)
+- `agents` — include `~/.pi/agent/AGENTS.md`
+- `system` — use `~/.pi/agent/SYSTEM.md`
+- `append-system` — include `~/.pi/agent/APPEND_SYSTEM.md`
+
+Extension names are resolved from the global or project-local extensions directory. Absolute and working-directory-relative extension paths are also accepted. Project-local names take precedence over global names. Source-file names resolve consistently across `.ts`, `.js`, `.mts`, `.mjs`, `.cts`, and `.cjs`.
+
+The nested Pi starts in the current working directory with the current model and thinking level. All optional resources are disabled unless named explicitly. Pi's built-in system prompt and built-in tools remain available. Missing selected global prompt files contribute no content; unselected prompt files remain excluded.
+
+Exit the nested TUI normally with `Ctrl+D` to return to the parent session. Launch failures and signal termination are reported after restoring the parent TUI.
+
+## Releases
+
+Version tags (`v*.*.*`) trigger [the release workflow](./.github/workflows/release.yml). It validates the package, publishes to npm through Trusted Publisher with provenance, verifies the published version and package inventory, and creates the GitHub Release from `CHANGELOG.md`.
+
+Configure npm Trusted Publisher for GitHub owner `llblab`, repository `pi-clean-room`, workflow filename `release.yml`, with no environment. Publication uses GitHub OIDC; no npm token secret is required. Keep the tag, manifest, root lockfile metadata, and changelog version aligned before pushing a release tag.
+
+## Limitations
+
+- Interactive terminal ownership requires Pi TUI mode. RPC, JSON, and print modes are rejected.
+- The clean-room retains Pi's built-in base system prompt and built-in tools.
+- Extension arguments cannot contain whitespace.

package/node_modules/@llblab/pi-clean-room/index.ts

@@ -0,0 +1,178 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import {
+	CONFIG_DIR_NAME,
+	getAgentDir,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+
+const EMPTY_COMPONENT = { render: () => [], invalidate: () => {} };
+const EXTENSION_SUFFIXES = [".ts", ".js", ".mts", ".mjs", ".cts", ".cjs"];
+
+export function discoverExtensionNames(cwd: string, agentDir = getAgentDir()): string[] {
+	const roots = [join(agentDir, "extensions"), join(cwd, CONFIG_DIR_NAME, "extensions")];
+	const names = new Set<string>();
+	for (const root of roots) {
+		if (!existsSync(root)) continue;
+		for (const entry of readdirSync(root, { withFileTypes: true })) {
+			if (entry.isDirectory()) names.add(entry.name);
+			const suffix = EXTENSION_SUFFIXES.find((suffix) => entry.name.endsWith(suffix));
+			if (entry.isFile() && suffix) names.add(entry.name.slice(0, -suffix.length));
+		}
+	}
+	return [...names].sort();
+}
+
+export function resolveExtension(source: string, cwd: string, agentDir = getAgentDir()): string | undefined {
+	const direct = isAbsolute(source) ? source : resolve(cwd, source);
+	if (existsSync(direct)) return direct;
+
+	const roots = [join(cwd, CONFIG_DIR_NAME, "extensions"), join(agentDir, "extensions")];
+	for (const root of roots) {
+		for (const candidate of [join(root, source), ...EXTENSION_SUFFIXES.map((suffix) => join(root, `${source}${suffix}`))]) {
+			if (existsSync(candidate)) return candidate;
+		}
+	}
+	return undefined;
+}
+
+export function resolveSkill(name: string, cwd: string, agentDir = getAgentDir()): string | undefined {
+	if (!name || name.includes("..") || isAbsolute(name)) return undefined;
+	const roots = [
+		join(cwd, CONFIG_DIR_NAME, "skills"),
+		join(cwd, ".agents", "skills"),
+		join(agentDir, "skills"),
+		join(homedir(), ".agents", "skills"),
+	];
+	for (const root of roots) {
+		for (const candidate of [join(root, name), join(root, `${name}.md`)]) {
+			if (existsSync(candidate)) return candidate;
+		}
+	}
+	return undefined;
+}
+
+export const RESOURCE_ARGUMENTS = ["skills", "agents", "system", "append-system"] as const;
+type ResourceArgument = (typeof RESOURCE_ARGUMENTS)[number];
+
+export function buildCleanRoomArgs(
+	extensions: string[],
+	model?: { provider: string; id: string },
+	thinkingLevel?: string,
+	resources: ReadonlySet<ResourceArgument> = new Set(),
+	agentDir = getAgentDir(),
+	skills: string[] = [],
+): string[] {
+	const args = ["--no-extensions"];
+	if (!resources.has("skills")) args.push("--no-skills");
+	for (const skill of skills) args.push("--skill", skill);
+	args.push("--no-prompt-templates", "--no-themes", "--no-context-files");
+
+	const systemPath = join(agentDir, "SYSTEM.md");
+	args.push("--system-prompt", resources.has("system") && existsSync(systemPath) ? readFileSync(systemPath, "utf8") : "");
+	const appendPaths: string[] = [];
+	for (const [resource, file] of [["agents", "AGENTS.md"], ["append-system", "APPEND_SYSTEM.md"]] as const) {
+		const path = join(agentDir, file);
+		if (resources.has(resource) && existsSync(path)) appendPaths.push(path);
+	}
+	for (const path of appendPaths.length > 0 ? appendPaths : [""]) args.push("--append-system-prompt", path);
+
+	if (model) args.push("--model", `${model.provider}/${model.id}`);
+	if (thinkingLevel) args.push("--thinking", thinkingLevel);
+	for (const extension of extensions) args.push("--extension", extension);
+	return args;
+}
+
+function parseNames(args: string): string[] {
+	return args.trim().split(/\s+/).filter(Boolean);
+}
+
+function launchCleanRoom(
+	ctx: ExtensionCommandContext,
+	extensionPaths: string[],
+	resources: ReadonlySet<ResourceArgument>,
+	skills: string[],
+) {
+	const args = buildCleanRoomArgs(extensionPaths, ctx.model, ctx.thinkingLevel, resources, getAgentDir(), skills);
+	const cliEntry = process.argv[1];
+	const command = cliEntry && existsSync(cliEntry) ? process.execPath : "pi";
+	const commandArgs = cliEntry && existsSync(cliEntry) ? [cliEntry, ...args] : args;
+
+	return spawnSync(command, commandArgs, {
+		cwd: ctx.cwd,
+		env: process.env,
+		stdio: "inherit",
+	});
+}
+
+export default function cleanRoomExtension(pi: ExtensionAPI) {
+	pi.registerCommand("clean-room", {
+		description: "Launch a clean Pi session with only the named extensions",
+		getArgumentCompletions(prefix) {
+			const separator = prefix.lastIndexOf(" ");
+			const head = separator === -1 ? "" : prefix.slice(0, separator + 1);
+			const needle = prefix.slice(separator + 1).toLowerCase();
+			const selected = new Set(parseNames(head));
+			const items = [...RESOURCE_ARGUMENTS, ...discoverExtensionNames(process.cwd())]
+				.filter((name) => !selected.has(name) && name.toLowerCase().startsWith(needle))
+				.map((name) => ({ value: `${head}${name}`, label: name }));
+			return items.length > 0 ? items : null;
+		},
+		async handler(rawArgs, ctx) {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("pi-clean-room requires interactive TUI mode", "error");
+				return;
+			}
+
+			const names = parseNames(rawArgs);
+			const resources = new Set(names.filter((name): name is ResourceArgument =>
+				(RESOURCE_ARGUMENTS as readonly string[]).includes(name),
+			));
+			const skillNames = names.filter((name) => name.startsWith("skills/")).map((name) => name.slice("skills/".length));
+			const extensionNames = names.filter((name) => !resources.has(name as ResourceArgument) && !name.startsWith("skills/"));
+			const missingSkills: string[] = [];
+			const skills = skillNames.map((name) => {
+				const path = resolveSkill(name, ctx.cwd);
+				if (!path) missingSkills.push(name);
+				return path;
+			}).filter((path): path is string => path !== undefined);
+			const missingExtensions: string[] = [];
+			const paths = extensionNames.map((name) => {
+				const path = resolveExtension(name, ctx.cwd);
+				if (!path) missingExtensions.push(name);
+				return path;
+			}).filter((path): path is string => path !== undefined);
+			if (missingSkills.length > 0) {
+				ctx.ui.notify(`Unknown skill${missingSkills.length > 1 ? "s" : ""}: ${missingSkills.join(", ")}`, "error");
+				return;
+			}
+			if (missingExtensions.length > 0) {
+				ctx.ui.notify(`Unknown extension${missingExtensions.length > 1 ? "s" : ""}: ${missingExtensions.join(", ")}`, "error");
+				return;
+			}
+
+			let failure: string | undefined;
+			await ctx.ui.custom<void>((tui, _theme, _keybindings, done) => {
+				tui.stop();
+				try {
+					process.stdout.write("\x1b[2J\x1b[H");
+					const result = launchCleanRoom(ctx, paths, resources, skills);
+					if (result.error) failure = `pi-clean-room failed to start: ${result.error.message}`;
+					else if (result.signal) failure = `pi-clean-room terminated by ${result.signal}`;
+					else if (result.status !== 0) failure = `pi-clean-room exited with code ${result.status ?? "unknown"}`;
+				} catch (error) {
+					failure = `pi-clean-room failed: ${error instanceof Error ? error.message : String(error)}`;
+				} finally {
+					tui.start();
+					tui.requestRender(true);
+					done();
+				}
+				return EMPTY_COMPONENT;
+			});
+			if (failure) ctx.ui.notify(failure, "error");
+		},
+	});
+}

package/node_modules/@llblab/pi-clean-room/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@llblab/pi-clean-room",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Launch an isolated Pi TUI with only explicitly selected extensions",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "clean-room",
+    "testing",
+    "isolation"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/llblab/pi-clean-room.git"
+  },
+  "homepage": "https://github.com/llblab/pi-clean-room",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "check": "node --experimental-strip-types -e \"await import('./index.ts'); console.log('pi-clean-room: extension import ok')\"",
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "audit": "npm audit --omit=peer",
+    "pack:dry": "npm pack --dry-run",
+    "validate": "npm run typecheck && npm run test && npm run check && npm run audit && npm run pack:dry"
+  },
+  "files": [
+    "index.ts",
+    "banner.jpg",
+    "README.md",
+    "AGENTS.md",
+    "BACKLOG.md",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/llblab/pi-clean-room/main/banner.jpg"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "typescript": "latest"
+  }
+}

package/node_modules/@llblab/pi-grow-loop/AGENTS.md

@@ -9,7 +9,7 @@
 - `Release-Level Changelog`: `CHANGELOG.md` records final release outcomes, not raw iteration telemetry or superseded internal steps. Keep entries linear, domain-tagged, and coherent for a release reader.
 - `Docs Directory Purpose`: Create `docs/` only when there are multiple project documentation pages that need an index. A lone extra README under `docs/` is unnecessary; the root `README.md` is the human entrypoint.
 - `Boundary Clarity`: Keep meta-loop decision, worker iteration, and runtime trigger separate.
-- `Scope-First Activation`: Grow Loop starts from a concrete user-focus task scope, not from command phrasing alone. Prefer a canonical open-work surface explicitly declared by relevant project-local delivery instructions, then project-local surfaces near the active working directory; resolve declarations relative to their owner, reject scope mismatch, and stop on unresolved competing ownership instead of selecting unrelated work.
+- `Scope-First Activation`: Grow Loop locks the concrete user-focus scope. While True alone resolves and validates its canonical open-work surface under the worker's source-of-truth protocol; Grow Loop retains that result and decides continuation from the handoff rather than repeating discovery.
 - `Lexical Intent Precedence`: An explicitly named protocol selects its exact behavior. Standalone `while-true` runs only the portable worker; standalone `grow-loop` selects the meta-protocol; `while true | grow loop` is reserved for runtime continuation.
 - `Structural Routing`: When no protocol is named, route by delegated execution shape and checkpoint topology, never by verbs, work categories, prompt length, apparent size, or internal step count. One coherent change with one natural validation/reporting boundary remains ordinary execution; a concrete outcome may select Grow Loop when it benefits from multiple independently useful validated slices and visible continuation checkpoints. Bootstrapping a canonical backlog from an explicit requested outcome is decomposition, not speculative work invention.
 - `Stop Honesty`: Exact proof-of-stop is better than simulated autonomous momentum.

package/node_modules/@llblab/pi-grow-loop/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.7.4: Worker Handoff Ownership Hotfix
+
+- `Worker Handoff`: Keeps canonical work-surface resolution and handoff fields with While True; Grow Loop locks user scope and decides whether to schedule another iteration from the returned evidence without duplicating discovery or worker analysis.
+
 ## 0.7.3: Turn-Scoped Iteration Hotfix
 
 - [Runtime] Keep repeated `grow_loop` calls within one agent turn bound to the same next iteration, replacing only the deferred delay instead of incrementing the visible loop number.

package/node_modules/@llblab/pi-grow-loop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-grow-loop",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "private": false,
   "description": "Semantic loop-engineering for agent-owned, visible, interruptible continuation in Pi",
   "keywords": [

package/node_modules/@llblab/pi-grow-loop/skills/grow-loop/SKILL.md

@@ -30,14 +30,9 @@ Natural routing into Grow Loop requires a concrete outcome or scope, a truthful
 
 ## Scope Lock
 
-Select the user-focus scope in this order:
+Lock the project, directory, file, issue, task, or scoped outcome selected by the user. Conversation context may supply it only when it identifies the next safe slice precisely.
 
-1. Explicit project, directory, file, issue, or task selected by the user.
-2. An explicit scoped outcome that can be decomposed into a truthful canonical backlog.
-3. A canonical open-work surface explicitly declared by relevant project-local delivery instructions for that scope.
-4. The actively maintained open-work surface nearest that scope: `BACKLOG.md`, `PLAN.md`, `ROADMAP.md`, `TODO.md`, task list, or release checklist.
-5. Active docs, validation failure, or repository reality that defines concrete remaining work.
-6. Conversation context only when it identifies a safe next slice precisely.
+Pass that scope to `while-true`, which alone resolves and validates the canonical open-work surface, including any `Canonical open work:` declaration. Retain the surface returned in its handoff; do not run a second discovery algorithm here.
 
 Ignore unrelated repositories, temporary or generated directories, dependencies, caches, archives, and stale plans.
 
@@ -62,16 +57,7 @@ If a queued `while true | grow loop` prompt arrives after continuation-break int
 
 ## Continuation Checkpoint
 
-After one `while-true` invocation, consume its handoff without redoing worker implementation analysis:
-
-- Locked scope and canonical work surface.
-- Artifact or evidence produced.
-- Validation result and highest completed rung.
-- Plan-state transition.
-- Highest-value remaining item and actionability class.
-- Gate, blocker, and exact unblocker.
-- Checkpoint signature: selected cohort items, changed surfaces, per-task and shared validation results, blocker, and plan transitions.
-- Latest user intent.
+After one `while-true` invocation, consume its [Handoff](../while-true/SKILL.md#handoff) and checkpoint signature without redoing worker implementation analysis. Combine that evidence with the latest user intent; `while-true` owns the handoff fields, while this Skill owns the continuation decision.
 
 A useful invocation must change an artifact, increase validation confidence, narrow a blocker, improve plan truth, or remove a risky assumption. The worker may batch independent low-coupling tasks into one validation cohort; Grow Loop evaluates the cohort handoff as one checkpoint and does not reinterpret its batching. Otherwise treat the invocation as a possible no-op.