@llblab/pi-kit 0.22.2 → 0.23.1

package/node_modules/@llblab/pi-actors/scripts/build-dist.mjs

@@ -1,47 +1,40 @@
 #!/usr/bin/env node
 
 /**
- * Build the JavaScript-only distributive tree.
- *
- * This is intentionally standalone: it is package/build glue, not reusable
- * actor-domain behavior. It cleans dist, compiles TypeScript, mirrors runtime
- * assets, and syntax-checks packaged scripts.
+ * Builds or verifies the JavaScript-only distributive tree without exposing a
+ * partial tree to Pi or destroying the previous distributive on failure.
  */
 
 import { spawnSync } from "node:child_process";
 import {
   cpSync,
+  existsSync,
   mkdirSync,
+  mkdtempSync,
+  readFileSync,
   readdirSync,
+  renameSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
+
+const DIST_DIR = "dist";
+const checkOnly = process.argv.includes("--check");
 
 function run(command, args) {
   const result = spawnSync(command, args, { stdio: "inherit" });
   if (result.error) throw result.error;
-  if (result.status !== 0) process.exit(result.status ?? 1);
+  if (result.status !== 0) {
+    throw new Error(`${command} exited with status ${result.status ?? "unknown"}.`);
+  }
 }
 
-rmSync("dist", { recursive: true, force: true });
-mkdirSync("dist", { recursive: true });
-
-run(process.execPath, [
-  join("node_modules", "typescript", "bin", "tsc"),
-  "-p",
-  "tsconfig.build.json",
-]);
-
-mkdirSync(join("dist", "pi-actors"), { recursive: true });
-writeFileSync(
-  join("dist", "pi-actors", "index.js"),
-  'export { default } from "../index.js";\n',
-  "utf8",
-);
-
-for (const dir of ["scripts", "fixtures", "skills"]) {
-  cpSync(dir, join("dist", dir), { recursive: true });
+function listFiles(root, current = root) {
+  return readdirSync(current, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(current, entry.name);
+    return entry.isDirectory() ? listFiles(root, path) : [relative(root, path)];
+  }).sort();
 }
 
 function listModuleScripts(root) {
@@ -52,9 +45,80 @@ function listModuleScripts(root) {
   });
 }
 
-const builtScripts = [
-  ...listModuleScripts(join("dist", "scripts")),
-  ...listModuleScripts(join("dist", "skills")),
-];
+function normalizeTextFiles(root) {
+  const textSuffixes = [".js", ".ts", ".mjs", ".json", ".md"];
+  for (const path of listFiles(root)) {
+    if (!textSuffixes.some((suffix) => path.endsWith(suffix))) continue;
+    const absolutePath = join(root, path);
+    const source = readFileSync(absolutePath, "utf8");
+    const normalized = source.replace(/\r\n?/g, "\n");
+    if (normalized !== source) writeFileSync(absolutePath, normalized, "utf8");
+  }
+}
+
+function assertTreesEqual(expectedRoot, actualRoot) {
+  if (!existsSync(expectedRoot)) {
+    throw new Error(`${expectedRoot} is missing; run npm run build.`);
+  }
+  const expectedFiles = listFiles(expectedRoot);
+  const actualFiles = listFiles(actualRoot);
+  if (JSON.stringify(expectedFiles) !== JSON.stringify(actualFiles)) {
+    throw new Error("dist file inventory is stale; run npm run build.");
+  }
+  for (const path of expectedFiles) {
+    if (!readFileSync(join(expectedRoot, path)).equals(readFileSync(join(actualRoot, path)))) {
+      throw new Error(`dist/${path} is stale; run npm run build.`);
+    }
+  }
+}
+
+function replaceDist(candidate) {
+  const backup = `.dist-backup-${process.pid}-${Date.now()}`;
+  const hadDist = existsSync(DIST_DIR);
+  if (hadDist) renameSync(DIST_DIR, backup);
+  try {
+    renameSync(candidate, DIST_DIR);
+    if (hadDist) rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    if (hadDist && existsSync(backup) && !existsSync(DIST_DIR)) {
+      renameSync(backup, DIST_DIR);
+    }
+    throw error;
+  }
+}
 
-run(process.execPath, ["--check", ...builtScripts]);
+const candidate = mkdtempSync(join(process.cwd(), ".dist-build-"));
+try {
+  run(process.execPath, [
+    join("node_modules", "typescript", "bin", "tsc"),
+    "-p",
+    "tsconfig.build.json",
+    "--outDir",
+    candidate,
+  ]);
+
+  mkdirSync(join(candidate, "pi-actors"), { recursive: true });
+  writeFileSync(
+    join(candidate, "pi-actors", "index.js"),
+    'export { default } from "../index.js";\n',
+    "utf8",
+  );
+  normalizeTextFiles(candidate);
+  for (const dir of ["scripts", "fixtures", "skills"]) {
+    cpSync(dir, join(candidate, dir), { recursive: true });
+  }
+  const builtScripts = [
+    ...listModuleScripts(join(candidate, "scripts")),
+    ...listModuleScripts(join(candidate, "skills")),
+  ];
+  run(process.execPath, ["--check", ...builtScripts]);
+
+  if (checkOnly) {
+    assertTreesEqual(DIST_DIR, candidate);
+    console.log("pi-actors: dist is current");
+  } else {
+    replaceDist(candidate);
+  }
+} finally {
+  rmSync(candidate, { recursive: true, force: true });
+}

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

@@ -33,12 +33,14 @@
 ## Topology
 
 ```text
-index.ts                  optionally delayed grow_loop tool
-skills/grow-loop/SKILL.md meta-loop protocol
-skills/while-true/SKILL.md worker-loop protocol baseline
-README.md                 human entrypoint
-BACKLOG.md                open work
-CHANGELOG.md              completed delivery history
+index.ts                       source-checkout composition root
+dist/pi-grow-loop/index.js     packaged compiled entrypoint
+dist/skills                    packaged Skill root
+skills/grow-loop/SKILL.md      meta-loop protocol
+skills/while-true/SKILL.md     worker-loop protocol baseline
+README.md                      human entrypoint
+BACKLOG.md                     open work
+CHANGELOG.md                   completed delivery history
 ```
 
 ## Evolution Path
@@ -51,6 +53,8 @@ CHANGELOG.md              completed delivery history
 
 ## Style
 
+- Manifest-loaded packages expose bundled Skills only through `pi.skills`, preserving package filters and package-owned provenance. Only a checkout auto-discovered directly below a user or project Pi `extensions/` root may contribute its source Skill root through `resources_discover`; compiled-vs-source filename shape does not determine ownership.
+- Keep `dist/` synchronized and committed after source changes because Pi git-package installation does not run the npm `prepack` lifecycle. Run `npm run build` to atomically replace it; validation uses `build:check` to reject drift without rewriting the working tree, while npm publication rebuilds the same tree.
 - Prefer small, inspectable TypeScript over framework or actor dependencies.
 - Use concise operator copy.
 - Keep prompt contracts explicit and bounded.

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

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+## 0.8.2: Filterable Skills and drift-safe Git installs
+
+- `Filterable Packaged Skills`: Manifest-loaded installs leave both bundled Skills to `pi.skills`, preserving filters and package provenance. Auto-discovered checkouts contribute source Skills even when Pi selects compiled code; filename shape no longer misclassifies ownership, and unsupported source manifest aliases are removed.
+- `Drift-Safe Distribution`: Ships the compiled entrypoint and Skill tree for npm/git installs, builds through a temporary candidate plus rollback-safe swap, and makes validation reject any committed `dist` drift without silently repairing it. Package filters that named source paths must target the new `dist/pi-grow-loop/index.js` and `dist/skills` paths.
+
 ## 0.8.1: Telegram Status Text Hotfix
 
 - `Status Text`: The Telegram Status screen now copies the compact terminal identity exactly: `Grow Loop: ∞N` for the armed or running iteration, without countdown, phase, or separator text. The row still hides whenever the terminal status is hidden.

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

@@ -22,6 +22,8 @@ Or install from git:
 pi install git:github.com/llblab/pi-grow-loop
 ```
 
+Manifest-loaded packages load the compiled extension and bundled Skills through the package manifest, so Pi resource filters and package provenance remain authoritative. A checkout auto-discovered directly under Pi's user or project extensions directory contributes its source Skills for local development even when Pi selects the checkout's compiled entrypoint. Existing package filters that name resource paths should use `dist/pi-grow-loop/index.js` and `dist/skills`; filters by Skill name remain unchanged.
+
 Then focus Pi on trustworthy open work or provide a concrete multi-slice outcome and ask for continuation:
 
 ```text

package/node_modules/@llblab/pi-grow-loop/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export interface GrowLoopTelegramProgress {
+    iteration: number;
+    state: "waiting" | "countdown" | "running";
+    remainingSeconds?: number;
+}
+export interface GrowLoopTelegramStatusLine {
+    label: string;
+    value: string;
+}
+export type GrowLoopTelegramStatusProvider = () => GrowLoopTelegramStatusLine | undefined;
+export type GrowLoopTelegramStatusRegistrar = (provider: GrowLoopTelegramStatusProvider) => (() => void) | undefined;
+type GrowLoopOptions = {
+    followUpDelayMs?: number;
+    countdownTickMs?: number;
+    /** Injection seam for the optional pi-telegram status line; defaults to the public pi-telegram membrane. */
+    registerTelegramStatusLine?: GrowLoopTelegramStatusRegistrar;
+};
+export declare function buildGrowLoopPrompt(): string;
+export declare function getAgentDir(env?: Record<string, string | undefined>): string;
+export declare function getExtensionPackageRoot(extensionUrl: string): string;
+export interface RawExtensionCheckoutOptions {
+    agentDir?: string;
+    cwd?: string;
+}
+export declare function isRawExtensionCheckout(extensionUrl: string, options?: RawExtensionCheckoutOptions): boolean;
+export declare function getExtensionSkillsDir(extensionUrl: string): string;
+export declare function getExistingExtensionSkillPaths(extensionUrl: string): string[];
+export declare function getTelegramStatusImportSpecifiers(extensionUrl: string): string[];
+export declare function registerGrowLoopSkillDiscovery(pi: Pick<ExtensionAPI, "on">, extensionUrl?: string, options?: RawExtensionCheckoutOptions): boolean;
+export declare function formatGrowLoopTelegramValue(progress: GrowLoopTelegramProgress): string;
+export default function growLoopExtension(pi: ExtensionAPI, partialOptions?: GrowLoopOptions): void;
+export {};

package/node_modules/@llblab/pi-grow-loop/dist/index.js

@@ -0,0 +1,286 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Type } from "typebox";
+const STATUS_KEY = "pi-grow-loop";
+const STATUS_LABEL = "grow-loop";
+const DEFAULT_FOLLOW_UP_DELAY_MS = 3000;
+const DEFAULT_COUNTDOWN_TICK_MS = 100;
+const MIN_AFTER_SECONDS = 3;
+const MAX_AFTER_SECONDS = 3600;
+const TELEGRAM_STATUS_IMPORT_SPECIFIERS = getTelegramStatusImportSpecifiers(import.meta.url);
+export function buildGrowLoopPrompt() {
+    return "while true | grow loop";
+}
+export function getAgentDir(env = process.env) {
+    return env.PI_CODING_AGENT_DIR
+        ? resolve(env.PI_CODING_AGENT_DIR)
+        : join(homedir(), ".pi", "agent");
+}
+export function getExtensionPackageRoot(extensionUrl) {
+    let current = dirname(fileURLToPath(extensionUrl));
+    while (true) {
+        if (existsSync(join(current, "package.json")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return dirname(fileURLToPath(extensionUrl));
+        current = parent;
+    }
+}
+export function isRawExtensionCheckout(extensionUrl, options = {}) {
+    const packageRoot = resolve(getExtensionPackageRoot(extensionUrl));
+    const agentDir = resolve(options.agentDir ?? getAgentDir());
+    const cwd = resolve(options.cwd ?? process.cwd());
+    return dirname(packageRoot) === join(agentDir, "extensions") ||
+        dirname(packageRoot) === join(cwd, ".pi", "extensions");
+}
+export function getExtensionSkillsDir(extensionUrl) {
+    return join(getExtensionPackageRoot(extensionUrl), "skills");
+}
+export function getExistingExtensionSkillPaths(extensionUrl) {
+    const skillsDir = getExtensionSkillsDir(extensionUrl);
+    return existsSync(skillsDir) ? [skillsDir] : [];
+}
+export function getTelegramStatusImportSpecifiers(extensionUrl) {
+    const siblingPath = join(dirname(getExtensionPackageRoot(extensionUrl)), "pi-telegram", "api", "status.ts");
+    return [
+        "@llblab/pi-telegram/status",
+        pathToFileURL(siblingPath).href,
+    ];
+}
+export function registerGrowLoopSkillDiscovery(pi, extensionUrl = import.meta.url, options = {}) {
+    if (!isRawExtensionCheckout(extensionUrl, options))
+        return false;
+    pi.on("resources_discover", async () => {
+        const skillPaths = getExistingExtensionSkillPaths(extensionUrl);
+        if (skillPaths.length === 0)
+            return;
+        return { skillPaths };
+    });
+    return true;
+}
+export function formatGrowLoopTelegramValue(progress) {
+    return `∞${progress.iteration}`;
+}
+async function registerGrowLoopTelegramStatus(provider) {
+    for (const specifier of TELEGRAM_STATUS_IMPORT_SPECIFIERS) {
+        try {
+            const imported = (await import(__rewriteRelativeImportExtension(specifier)));
+            if (typeof imported.registerTelegramStatusLineProvider === "function") {
+                return imported.registerTelegramStatusLineProvider(provider, { id: "@llblab/pi-grow-loop" });
+            }
+        }
+        catch {
+            // pi-telegram is optional; its absence only disables the Telegram status line.
+        }
+    }
+    return undefined;
+}
+function statusCountdown(ctx, seconds) {
+    const theme = ctx.ui.theme;
+    ctx.ui.setStatus(STATUS_KEY, theme.fg("accent", STATUS_LABEL) +
+        theme.fg("dim", ` ${seconds.toFixed(1)}s`));
+}
+function statusRunning(ctx, iteration) {
+    const theme = ctx.ui.theme;
+    ctx.ui.setStatus(STATUS_KEY, theme.fg("accent", STATUS_LABEL) + theme.fg("dim", ` ∞${iteration}`));
+}
+function statusDeferred(ctx, iteration) {
+    const theme = ctx.ui.theme;
+    ctx.ui.setStatus(STATUS_KEY, theme.fg("accent", STATUS_LABEL) +
+        theme.fg("warning", ` ∞${iteration}`));
+}
+function sendIteration(pi, ctx, iteration, expectOwnPrompt) {
+    statusRunning(ctx, iteration);
+    expectOwnPrompt();
+    pi.sendUserMessage(buildGrowLoopPrompt());
+}
+function scheduleIteration(pi, ctx, iteration, clearPending, expectOwnPrompt, options) {
+    statusDeferred(ctx, iteration);
+    const pending = {};
+    pending.interval = setInterval(() => {
+        if (pending.countdownStartedAt === undefined) {
+            if (!ctx.isIdle() || ctx.hasPendingMessages())
+                return;
+            pending.countdownStartedAt = Date.now();
+            pending.countdownDelayMs = options.followUpDelayMs;
+            statusCountdown(ctx, options.followUpDelayMs / 1000);
+            pending.timeout = setTimeout(() => {
+                pending.timeout = undefined;
+                if (!ctx.isIdle() || ctx.hasPendingMessages()) {
+                    pending.countdownStartedAt = undefined;
+                    pending.countdownDelayMs = undefined;
+                    statusDeferred(ctx, iteration);
+                    return;
+                }
+                clearPending();
+                sendIteration(pi, ctx, iteration, expectOwnPrompt);
+            }, options.followUpDelayMs);
+            pending.timeout.unref?.();
+            return;
+        }
+        const elapsed = Date.now() - pending.countdownStartedAt;
+        const remainingMs = Math.max(options.followUpDelayMs - elapsed, 0);
+        if (remainingMs > 0)
+            statusCountdown(ctx, remainingMs / 1000);
+    }, options.countdownTickMs);
+    pending.interval.unref?.();
+    return pending;
+}
+export default function growLoopExtension(pi, partialOptions = {}) {
+    const options = {
+        followUpDelayMs: partialOptions.followUpDelayMs ?? DEFAULT_FOLLOW_UP_DELAY_MS,
+        countdownTickMs: partialOptions.countdownTickMs ?? DEFAULT_COUNTDOWN_TICK_MS,
+        registerTelegramStatusLine: partialOptions.registerTelegramStatusLine,
+    };
+    let iteration = 0;
+    let lastCtx;
+    let pendingIteration;
+    let ownPromptPending = false;
+    let scheduledThisTurn = false;
+    let runningIteration;
+    let unregisterTelegramStatus;
+    let telegramRegistration;
+    let telegramGeneration = 0;
+    const clearPending = () => {
+        if (!pendingIteration)
+            return;
+        if (pendingIteration.timeout)
+            clearTimeout(pendingIteration.timeout);
+        clearInterval(pendingIteration.interval);
+        pendingIteration = undefined;
+    };
+    const telegramStatusProvider = () => {
+        if (pendingIteration) {
+            const state = pendingIteration.countdownStartedAt === undefined ? "waiting" : "countdown";
+            return { label: "Grow Loop", value: formatGrowLoopTelegramValue({ iteration, state }) };
+        }
+        if (runningIteration !== undefined) {
+            return { label: "Grow Loop", value: formatGrowLoopTelegramValue({ iteration: runningIteration, state: "running" }) };
+        }
+        return undefined;
+    };
+    const ensureTelegramStatusRegistered = () => {
+        if (unregisterTelegramStatus || telegramRegistration)
+            return;
+        if (options.registerTelegramStatusLine) {
+            unregisterTelegramStatus = options.registerTelegramStatusLine(telegramStatusProvider) ?? undefined;
+            return;
+        }
+        const generation = telegramGeneration;
+        telegramRegistration = registerGrowLoopTelegramStatus(telegramStatusProvider)
+            .then((unregister) => {
+            if (generation !== telegramGeneration) {
+                unregister?.();
+                return;
+            }
+            unregisterTelegramStatus = unregister;
+        })
+            .finally(() => {
+            if (generation === telegramGeneration)
+                telegramRegistration = undefined;
+        });
+    };
+    const hideLoopStatus = (ctx) => {
+        ownPromptPending = false;
+        runningIteration = undefined;
+        clearPending();
+        ctx.ui.setStatus(STATUS_KEY, undefined);
+    };
+    ensureTelegramStatusRegistered();
+    registerGrowLoopSkillDiscovery(pi);
+    pi.on("session_shutdown", async () => {
+        ownPromptPending = false;
+        scheduledThisTurn = false;
+        runningIteration = undefined;
+        clearPending();
+        telegramGeneration += 1;
+        unregisterTelegramStatus?.();
+        unregisterTelegramStatus = undefined;
+        telegramRegistration = undefined;
+        lastCtx?.ui.setStatus(STATUS_KEY, undefined);
+    });
+    pi.on("session_start", async () => {
+        ensureTelegramStatusRegistered();
+    });
+    pi.on("agent_settled", async (_event, ctx) => {
+        lastCtx = ctx;
+        if (!pendingIteration) {
+            runningIteration = undefined;
+            ctx.ui.setStatus(STATUS_KEY, undefined);
+        }
+    });
+    pi.on("input", async (event, ctx) => {
+        lastCtx = ctx;
+        scheduledThisTurn = false;
+        const isOwnPrompt = event.source === "extension" &&
+            ownPromptPending &&
+            event.text === buildGrowLoopPrompt();
+        if (isOwnPrompt) {
+            ownPromptPending = false;
+            return { action: "continue" };
+        }
+        hideLoopStatus(ctx);
+        return { action: "continue" };
+    });
+    pi.registerTool({
+        name: "grow_loop",
+        label: "Grow Loop",
+        description: "Schedule the next visible Grow Loop iteration after an optional delay in seconds (default: 3).",
+        promptSnippet: "Schedule the next Grow Loop iteration after an optional delay.",
+        promptGuidelines: [
+            "Use grow_loop when the Grow Loop skill decides another while-true iteration should run; omit after_seconds for the default 3-second delay.",
+            "Increase grow_loop after_seconds from 3 up to 3600 when continuation should wait for asynchronous work; never shorten the 3-second operator-interrupt window.",
+            "Choose grow_loop after_seconds from evidence about the expected remaining wait, then reassess after each wake instead of repeating the previous delay mechanically.",
+            "To stop, do not call grow_loop; finish with a concise stop proof.",
+        ],
+        parameters: Type.Object({
+            after_seconds: Type.Optional(Type.Number({
+                minimum: MIN_AFTER_SECONDS,
+                maximum: MAX_AFTER_SECONDS,
+                default: 3,
+                description: "Seconds to wait after Pi becomes idle before starting the next iteration (maximum: 3600)",
+            })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            lastCtx = ctx;
+            ownPromptPending = false;
+            runningIteration = undefined;
+            clearPending();
+            const isReschedule = scheduledThisTurn;
+            if (!isReschedule) {
+                iteration += 1;
+                scheduledThisTurn = true;
+            }
+            const nextIteration = iteration;
+            const delayMs = params.after_seconds === undefined
+                ? options.followUpDelayMs
+                : params.after_seconds * 1000;
+            pendingIteration = scheduleIteration(pi, ctx, nextIteration, clearPending, () => {
+                ownPromptPending = true;
+                runningIteration = nextIteration;
+            }, { followUpDelayMs: delayMs, countdownTickMs: options.countdownTickMs });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: isReschedule
+                            ? `\nTool grow_loop was already called this turn. Iteration #${nextIteration} remains scheduled; delay updated to ${delayMs / 1000}s`
+                            : `\nGrow Loop iteration #${nextIteration} deferred until idle, then scheduled after ${delayMs / 1000}s delay`,
+                    },
+                ],
+                details: { iteration: nextIteration, delayMs },
+            };
+        },
+    });
+}

package/node_modules/@llblab/pi-grow-loop/dist/pi-grow-loop/index.d.ts

@@ -0,0 +1 @@
+export { default } from "../index.js";

package/node_modules/@llblab/pi-grow-loop/dist/pi-grow-loop/index.js

@@ -0,0 +1 @@
+export { default } from "../index.js";

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

@@ -0,0 +1,117 @@
+---
+name: grow-loop
+description: Meta-protocol for autonomous, scope-locked continuation through visible bounded worker iterations. Use when the user explicitly names `grow-loop`, or when no protocol is named and a concrete scoped outcome benefits from multiple independently useful, validated slices with operator-visible continuation checkpoints. Existing plans are optional, and an explicit scoped outcome may bootstrap a canonical backlog. Do not activate for an explicit standalone `while-true` request, ordinary one-shot work with one natural validation boundary, informational answers, unrelated plans, or work with no safe actionable or preparable slice.
+---
+
+# Grow Loop
+
+Own one decision: after a bounded `while-true` worker invocation, either schedule exactly one next visible invocation with `grow_loop` or stop with proof.
+
+```text
+lock scope → run one worker invocation → consume handoff → decide once
+  ├─ continue: call grow_loop once, then end the turn
+  └─ stop: do not call grow_loop; return proof
+```
+
+Do not own implementation details. `while-true` owns one portable worker pass; `grow_loop` owns only idle-deferred runtime scheduling.
+
+There is no goal object, budget, cycle count, hidden process, background agent, or slash-command control surface. For generic prompts such as `go`, `continue`, or `do it`, infer intent from context; explicit protocol names remain exact overrides.
+
+## Entrypoint Routing
+
+Apply lexical intent before execution-shape inference:
+
+- Explicit standalone `while-true` selects only the portable worker. Do not activate Grow Loop or call `grow_loop` from its handoff unless the user later requests Grow Loop continuation.
+- Explicit `grow-loop` selects this meta-protocol.
+- The combined `while true | grow loop` prompt is reserved for internal continuation of an already selected Grow Loop sequence.
+- When no protocol is named, use ordinary one-shot execution for a coherent change even when it needs multiple internal steps. Use Grow Loop for a concrete outcome that benefits from multiple independently validated slices, plan reconciliation, and operator-visible checkpoints.
+
+Natural routing into Grow Loop requires a concrete outcome or scope, a truthful backlog that exists or can be bootstrapped, safe actionable or preparable work, and no one-shot instruction. The distinction is the value of independent checkpoint boundaries, not task size, keyword matching, or a confirmation ritual. Routing happens before invoking `while-true`; the worker never escalates itself.
+
+## Scope Lock
+
+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.
+
+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.
+
+Keep the selected scope and declared work-surface ownership stable across iterations. Re-select only when the user redirects the work or verified reality proves another surface governs the same scope. A stale or moved declaration requires repair or an explicit ambiguity stop, not harvesting other available work to preserve momentum.
+
+If no trustworthy scope exists, do not invoke the worker or call `grow_loop`; request the smallest missing input.
+
+## Intent Precedence
+
+Interpret the latest context in this order:
+
+1. Latest user direction or change of scope.
+2. Explicit continuation-break intent or durable stop marker.
+3. Worker evidence, safety gates, and blockers.
+4. Remaining backlog availability.
+
+Any user prompt except the runtime's exact expected continuation prompt exits the runtime rhythm and is authoritative context, including operator input injected through another extension. Decide whether it means answer, stop, restart, continue, or change direction; do not infer continuation from backlog availability alone.
+
+Escape remains baseline Pi behavior, not a Grow Loop control. Treat it as a continuation break only when session context exposes that intent or a durable stop marker.
+
+If a queued `while true | grow loop` prompt arrives after continuation-break intent, do no repository work, run no validation for momentum, and do not call `grow_loop`. Acknowledge the break and provide the current stop proof when useful. Resume only after explicit restart intent clears the stop context.
+
+## Continuation Checkpoint
+
+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.
+
+Compare the checkpoint signature with the previous invocation. A repeated signature with only unchanged reads, checks, or blocker restatement is terminal no-op evidence.
+
+## Decide Once
+
+### Continue
+
+Continue only when every condition holds:
+
+- Latest user intent permits continuation and no stop marker is active.
+- The locked scope and canonical work surface remain trustworthy.
+- The previous invocation produced useful evidence.
+- A high-value `local-actionable` or useful `gated-but-preparable` slice remains.
+- Continuing crosses no destructive, publishing, credential, account, external, or approval gate.
+- The checkpoint signature is not a repeated no-op.
+- Validation has not regressed enough to require a strategy change or human decision.
+
+Approval- or externally gated scopes may continue only through safe preparation that materially reduces future risk. Stop when preparation is exhausted; never cross the gate.
+
+When all conditions hold, call `grow_loop` exactly once, then end the turn. Omit `after_seconds` for the default 3-second operator-interrupt delay, or increase it from 3 up to 3600 when continuation should wait for known asynchronous work. Never shorten the 3-second minimum because it preserves the operator's chance to redirect the next iteration. Choose a longer delay from concrete evidence about expected remaining duration, use the one-hour limit only for genuinely long-running work, and reassess after every wake so the next delay tracks the latest state rather than mechanically repeating the previous value. The tool waits until Pi is idle with no pending messages, shows the configured countdown, and sends the next visible `while true | grow loop` prompt only if the session remains idle.
+
+### Stop
+
+Stop and do not call `grow_loop` when any condition holds:
+
+- User intent means stop, answer, wait, or change direction.
+- Scope is missing, ambiguous, redirected, or untrustworthy.
+- Work is complete or no high-value actionable or preparable slice remains.
+- Remaining work is gated and useful preparation is complete.
+- The checkpoint signature repeats.
+- Validation requires a strategy change or human decision.
+- Continuing would be unsafe, destructive, speculative, or outside scope.
+
+Stopping with exact evidence is progress. Do not schedule speculatively and do not call `grow_loop` more than once per decision.
+
+## Stop Proof
+
+Return a compact terminal handoff:
+
+- Locked scope and what was closed or narrowed.
+- Validation or evidence proving the state.
+- Terminal checkpoint signature in concise form.
+- What remains done, gated, or non-actionable.
+- Exact input or state change that would make restart useful, if any.
+
+## Invariants
+
+1. Scope remains locked until user intent or verified reality changes it.
+2. `while-true` owns worker execution; Grow Loop consumes its handoff and owns continuation only.
+3. User intent outranks repository availability.
+4. Each checkpoint produces one decision and at most one `grow_loop` call.
+5. Safe preparation may approach a gate but never cross it.
+6. Repeated no-op evidence stops the loop.
+7. No trustworthy scope or evidence means no continuation.
+8. Explicit protocol naming overrides automatic routing; the worker never self-escalates.