@llblab/pi-kit 0.22.1 → 0.23.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.23.0 - 2026-09-24
+
+- `Awaited State Flow Memory`: Pins State Flow to `0.19.0`. Shared patches preserve independent changes, repeats avoid extra revisions, and state acceptance precedes the next provider request. Start/Stop select workflow policy without cancelling restoration or fork copying; unfinished context and private session ownership survive mode changes. Library callers must await inspection results; six synchronous runtime methods remain supported.
+- `Compiled Grow Loop Resources`: Pins Grow Loop to `0.8.2` and loads its declared `dist/pi-grow-loop/index.js` and `dist/skills` resources. Manifest-owned Skill discovery preserves package filters and provenance, while the package supplies drift-checked compiled output.
+- `Resolver-Owned Telegram Skills`: Pins Telegram to `0.51.4`. Manifest-loaded kit resources retain Skill filters and provenance without duplicate checkout discovery; the owning package supplies a committed, drift-checked runtime and Skill distribution.
+- `Package Cohort`: Preserves all seven package members, exact pins for the other four packages, extension load order and the Pi minimum. Runtime behavior and Skill ownership remain with their independently released packages.
+
+## 0.22.2 - 2026-09-24
+
+- `Follower Registration Recovery`: Advances the exact Telegram pin to `0.51.3`. Followers whose retained target record contains a stale Workspace slot now reconcile to the authenticated canonical claim before binding commit, durably repairing their record without disturbing an unrelated binding that owns the old letter or making unnecessary Bot API calls.
+- `Filterable Packaged Skills`: Installed npm/git packages now leave Telegram Skill discovery to the manifest so Pi resource filters are honored. Raw TypeScript checkouts under Pi's extensions directory retain adjacent source-Skill discovery without creating a duplicate packaged discovery path.
+- `Package Cohort`: Keeps every other bundled package at its current exact version. Package membership, resource paths, load order, Pi minimum, and bundled Skill inventory remain unchanged.
+
 ## 0.22.1 - 2026-09-24
 
 - `In-Flight Model Switching`: Advances the exact Telegram pin to `0.51.2`. Telegram model selection can stop, switch, and continue any interruptible run in the current Pi session, including local/TUI work, while preserving the authorized chat, Thread, and reply target and deferring abort until active tools settle.

package/README.md

@@ -13,16 +13,16 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-actors`](https://github.com/llblab/pi-actors) | `0.53.0` | Inspectable local Runs, reusable Recipes, persistent tools, and delegation Skills |
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.2.0` | Isolated nested Pi TUI with named npm extensions and compatible model selection |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.10.0` | Compact Codex/Spark subscription-limit and Business credit-usage status |
-| [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.18.1` | Incremental scoped context/memory compiler with independent scope revisions, canonical file persistence, bounded and diagnosable Git backup replication, native working context within each run, and targeted historical reads |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.51.2` | Telegram companion with in-flight model switching, continuous exact-Thread typing, truthful transport status, pressure-safe Workspace rotation, files, voice, controls, and bundled Telegram interaction Skills |
+| [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.2` | Visible continuation scheduling and bounded worker Skills through compiled, manifest-owned resources |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.19.0` | Incremental scoped context/memory compiler with awaited publication, independent scope revisions, lossless mode changes, private fork memory, and optional Git backup |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.51.4` | Telegram companion with resolver-owned filterable Skills, compiled distribution, self-healing follower registration, in-flight model switching, files, voice, and controls |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
 Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.
 
 ## Install
 
-Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. State Flow 0.17 introduces a breaking storage-format boundary with no in-place predecessor converter. Preserve existing State Flow stores and review the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.18.1/docs/usage.md#moving-a-store-and-the-017-format-boundary) before upgrading from an earlier kit.
+Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. State Flow requires its canonical checkpoint/tail storage format and does not convert unsupported stores in place. Preserve existing stores and consult the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.19.0/docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing installations.
 
 From npm:
 

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.