@llblab/pi-kit 0.5.2 → 0.7.0

package/node_modules/@llblab/pi-actors/lib/run-ui-runtime.ts

@@ -10,6 +10,7 @@ import * as Observability from "./observability.ts";
 import * as Paths from "./paths.ts";
 import * as Pi from "./pi.ts";
 import * as RunDelivery from "./run-delivery.ts";
+import * as RunDeliveryLineage from "./run-delivery-lineage.ts";
 
 export interface RunUiRuntime {
   close(): void;
@@ -43,12 +44,11 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   let animationInterval: NodeJS.Timeout | undefined;
   let deliveryTimeout: NodeJS.Timeout | undefined;
   let notifyTimeout: NodeJS.Timeout | undefined;
-  let recoverQueuedBatch = false;
   let recoverQueuedSteers = false;
   let running = false;
   let lastWatcherDiagnosticId = 0;
   const observation = Observability.createRunUiObservationState();
-  const deliveryRecoveryDiagnostics = new Set<string>();
+  const deliveryObservation = Observability.createRunUiObservationState();
   const retirementAttempts = new Set<string>();
   const steerDiagnostics = new Set<string>();
 
@@ -70,9 +70,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     notifyTimeout = undefined;
     if (deliveryTimeout) clearTimeout(deliveryTimeout);
     deliveryTimeout = undefined;
-    recoverQueuedBatch = false;
     recoverQueuedSteers = false;
-    deliveryRecoveryDiagnostics.clear();
     steerDiagnostics.clear();
     if (animationInterval) clearInterval(animationInterval);
     animationInterval = undefined;
@@ -228,12 +226,14 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   };
   const admitCompletionTransitions = (
     ownerId: string,
-    transitions: Observability.RunTransition[],
+    snapshot: Observability.RunUiSnapshot,
   ): boolean => {
     const existing = journal(ownerId).completion_batch;
     if (existing) return true;
-    const members = Observability.collectRunCompletionBatchMembers(transitions)
-      .slice(0, Limits.RUN_DELIVERY_BATCH_MAX_MEMBERS);
+    const members = Observability.collectRunCompletionBatchMembers(
+      snapshot.transitions,
+      snapshot.summary.runs,
+    ).slice(0, Limits.RUN_DELIVERY_BATCH_MAX_MEMBERS);
     if (members.length === 0) return false;
     RunDelivery.admitRunCompletionBatch({
       members,
@@ -244,6 +244,10 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   };
   const isIdle = (ctx: Pi.ExtensionContext): boolean =>
     typeof ctx.isIdle !== "function" || ctx.isIdle();
+  const isDeliveryRoot = (ownerId: string): boolean => {
+    const inheritedOwner = RunDeliveryLineage.getProcessDeliveryOwnerId();
+    return inheritedOwner === undefined || inheritedOwner === ownerId;
+  };
   let flushCompletionBatch = (_ctx: Pi.ExtensionContext): boolean => false;
   const flushSteers = (ctx: Pi.ExtensionContext, ownerId: string): boolean => {
     const recovering = recoverQueuedSteers;
@@ -334,11 +338,25 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     if (!notify) return false;
     const sink = Pi.createNotificationSink(deps.pi, ctx);
     retireCandidateRuns(ctx, snapshot.summary);
-    const hasCompletionCandidates =
-      Observability.collectRunCompletionBatchMembers(snapshot.transitions).length > 0;
-    const hasCompletionBatch = Boolean(journal(ownerId).completion_batch);
+    const deliverySnapshot = isDeliveryRoot(ownerId)
+      ? Observability.readRunDeliverySnapshot(deliveryObservation, ownerId)
+      : undefined;
+    const hasCompletionCandidates = deliverySnapshot
+      ? Observability.collectRunCompletionBatchMembers(
+          deliverySnapshot.transitions,
+          deliverySnapshot.summary.runs,
+        ).length > 0
+      : false;
+    const hasCompletionBatch = isDeliveryRoot(ownerId) &&
+      Boolean(journal(ownerId).completion_batch);
     admitSteerEvents(ctx, ownerId, snapshot.attentionEvents);
     Observability.pruneRunUiObservationState(observation, snapshot);
+    if (deliverySnapshot) {
+      Observability.pruneRunUiObservationState(
+        deliveryObservation,
+        deliverySnapshot,
+      );
+    }
     if (!terminalOnly) {
       Observability.deliverRunAttentionNotifications(
         snapshot.attentionEvents.filter((event) =>
@@ -403,54 +421,48 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   });
 
   flushCompletionBatch = (ctx: Pi.ExtensionContext): boolean => {
-    if (!running || activeContext !== ctx || deps.getActiveContext() !== ctx) return false;
     const ownerId = activeOwnerId;
-    if (!ownerId) return false;
+    if (!running || !ownerId) return false;
+    try {
+      if (Pi.getSessionId(ctx) !== ownerId) return false;
+    } catch {
+      return false;
+    }
     if (flushSteers(ctx, ownerId)) return true;
+    if (!isDeliveryRoot(ownerId)) return false;
     let batch = journal(ownerId).completion_batch;
     if (!batch) {
-      const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
-      admitCompletionTransitions(ownerId, snapshot.transitions);
-      Observability.pruneRunUiObservationState(observation, snapshot);
+      const snapshot = Observability.readRunDeliverySnapshot(
+        deliveryObservation,
+        ownerId,
+      );
+      admitCompletionTransitions(ownerId, snapshot);
+      Observability.pruneRunUiObservationState(deliveryObservation, snapshot);
       batch = journal(ownerId).completion_batch;
     }
     if (!batch) return false;
     if (batch.phase === "presented") {
       finishPresentedBatch(ownerId, batch);
-      const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
-      admitCompletionTransitions(ownerId, snapshot.transitions);
-      Observability.pruneRunUiObservationState(observation, snapshot);
+      const snapshot = Observability.readRunDeliverySnapshot(
+        deliveryObservation,
+        ownerId,
+      );
+      admitCompletionTransitions(ownerId, snapshot);
+      Observability.pruneRunUiObservationState(deliveryObservation, snapshot);
       batch = journal(ownerId).completion_batch;
       if (!batch) return false;
     }
     if (!isIdle(ctx)) return true;
     const content = RunDelivery.formatRunCompletionBatchMessage(batch);
     if (batch.phase === "queued") {
-      if (!recoverQueuedBatch) return true;
-      recoverQueuedBatch = false;
-      const evidence = Pi.inspectRunCompletionBatchSessionEvidence(
-        ctx,
-        batch.batch_id,
-        content,
-      );
-      if (evidence.status === "present") return true;
-      if (evidence.status !== "absent") {
-        const diagnosticKey = `${batch.batch_id}:${evidence.status}:${evidence.reason ?? ""}`;
-        if (!deliveryRecoveryDiagnostics.has(diagnosticKey)) {
-          deliveryRecoveryDiagnostics.add(diagnosticKey);
-          ctx.ui.notify(
-            `Actor completion recovery is ${evidence.status}: ${evidence.reason ?? "conflicting session evidence"}. Batch ${batch.batch_id} remains queued.`,
-            "warning",
-          );
-        }
-        return true;
-      }
-      if (!RunDelivery.resetRunCompletionBatchPending({
+      if (!RunDelivery.markRunCompletionBatchPresented({
         batchId: batch.batch_id,
         ownerId,
         tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
       })) return true;
-      batch = journal(ownerId).completion_batch!;
+      const accepted = journal(ownerId).completion_batch;
+      if (accepted) finishPresentedBatch(ownerId, accepted);
+      return flushCompletionBatch(ctx);
     }
     if (!isIdle(ctx)) return true;
     try {
@@ -471,7 +483,19 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     })) {
       throw new Error("Completion batch changed before queue acknowledgment");
     }
-    recoverQueuedBatch = false;
+    if (!RunDelivery.markRunCompletionBatchPresented({
+      batchId: batch.batch_id,
+      ownerId,
+      tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+    })) {
+      throw new Error("Completion batch changed before durable acceptance");
+    }
+    const accepted = journal(ownerId).completion_batch;
+    if (accepted) finishPresentedBatch(ownerId, accepted);
+    ctx.ui.notify(
+      `Actor completions ready: ${batch.members.length}`,
+      "info",
+    );
     return true;
   };
 
@@ -479,11 +503,13 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     close,
     flushCompletionBatch,
     projectContext(messages, ctx) {
-      if (!running || activeContext !== ctx || deps.getActiveContext() !== ctx) {
+      const ownerId = activeOwnerId;
+      if (!running || !ownerId) return messages;
+      try {
+        if (Pi.getSessionId(ctx) !== ownerId) return messages;
+      } catch {
         return messages;
       }
-      const ownerId = activeOwnerId;
-      if (!ownerId) return messages;
       const steerContext = Pi.dedupeRunSteerContext(messages);
       let contextMessages = steerContext.messages;
       for (const steer of journal(ownerId).steers) {
@@ -560,7 +586,6 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
       close();
       activeContext = ctx;
       activeOwnerId = ownerId;
-      recoverQueuedBatch = true;
       recoverQueuedSteers = true;
       running = true;
       try {

package/node_modules/@llblab/pi-actors/lib/runtime.ts

@@ -325,6 +325,7 @@ export function createRecipeToolReloadWatcher(
   let rootWatcher: FSWatcher | undefined;
   let parentWatcher: FSWatcher | undefined;
   let failureNotified = false;
+  let notifyAfterReload = false;
   const setWatchStatus = (watchStatus: RecipeRegistryStatus["watch_status"]): void =>
     runtime.setWatchStatus?.(watchStatus);
   const close = (): void => {
@@ -336,6 +337,7 @@ export function createRecipeToolReloadWatcher(
     closingParent?.close();
     if (reloadTimeout) clearTimeout(reloadTimeout);
     reloadTimeout = undefined;
+    notifyAfterReload = false;
     setWatchStatus("closed");
   };
   const reportCallbackError = (error: unknown): void => {
@@ -358,14 +360,21 @@ export function createRecipeToolReloadWatcher(
       reportCallbackError(error);
     }
   };
-  const scheduleReload = (ctx: RuntimeContext): void => {
+  const scheduleReload = (
+    ctx: RuntimeContext,
+    notifyActiveChange = false,
+  ): void => {
     failureNotified = false;
+    notifyAfterReload ||= notifyActiveChange;
     if (reloadTimeout) clearTimeout(reloadTimeout);
     reloadTimeout = setTimeout(() => {
       reloadTimeout = undefined;
       try {
         runtime.loadTools(ctx, deps.getResolutionContext?.());
-        ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+        if (notifyAfterReload) {
+          ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+        }
+        notifyAfterReload = false;
       } catch (error) {
         notifyFailure(ctx);
         reportCallbackError(error);
@@ -394,7 +403,7 @@ export function createRecipeToolReloadWatcher(
         parentWatcher = undefined;
         watcher.close();
         watchRoot(ctx, recipeRoot);
-        scheduleReload(ctx);
+        scheduleReload(ctx, true);
       });
       parentWatcher = watcher;
       setWatchStatus("watching_parent");
@@ -415,16 +424,18 @@ export function createRecipeToolReloadWatcher(
       return;
     }
     try {
-      const watcher = watchPath(recipeRoot, () => {
+      const watcher = watchPath(recipeRoot, (_event, changedFile) => {
         if (rootWatcher !== watcher) return;
         if (!pathExists(recipeRoot)) {
           rootWatcher = undefined;
           watcher.close();
-          scheduleReload(ctx);
+          scheduleReload(ctx, true);
           watchParent(ctx, recipeRoot);
           return;
         }
-        scheduleReload(ctx);
+        const relativeChange = changedFile ? String(changedFile) : "";
+        const firstSegment = relativeChange.split(/[\\/]/u)[0];
+        scheduleReload(ctx, Boolean(relativeChange) && firstSegment !== "drafts");
       });
       rootWatcher = watcher;
       setWatchStatus("watching_root");

package/node_modules/@llblab/pi-actors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

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

@@ -107,7 +107,7 @@ Run = Recipe + Trace + Control
 ```
 
 1. Spawn with the exact logical Recipe identity and caller-owned values.
-2. Retain the returned `run:<id>` and normally wait for its settled completion batch instead of polling.
+2. Retain the returned `run:<id>` and normally wait for the root coordinator's settled completion batch instead of polling. Nested actor completions accumulate under their containing top-level Run and arrive in that one tree-compressed batch; descendant sessions do not need notification options.
 3. Inspect `view=trace` when retained observations or attention matter.
 4. Inspect `view=control` before diagnosing service readiness, stale work, or saturation.
 5. Send `message` only for an action declared and consumed by that controlled Recipe.

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

@@ -23,10 +23,10 @@
 - `grow-loop` skill owns continuation semantics: continue or stop.
 - Routing selects the protocol before worker execution: explicit names override inference; otherwise concrete iterative tasks may select Grow Loop when multiple validated slices and visible checkpoints are useful.
 - `while-true` skill owns only one portable worker pass: discover one canonical work surface, including neutral `Canonical open work: <path>` declarations from relevant project-local delivery instructions, assess reality, reconcile the plan, assemble one bounded validation cohort, execute independent low-coupling tasks with per-task falsification, run shared validation, and hand off. It batches by default when diagnosis remains clear and falls back to a single task for coupled, ordered, large, high-risk, or ambiguous work. A standalone invocation must not activate or call a continuation scheduler. It must not own continuation, user-stop semantics, command phrases, runtime tools, status text, or extension-specific controls; `grow-loop` plus `grow_loop` own sequential continuation only after Grow Loop was selected.
-- `grow_loop` tool only schedules the next visible iteration; its optional `after_seconds` argument accepts `3` through `3600` and defaults to `3`; the minimum preserves an operator-interrupt window before every continuation. Scheduling is idle-deferred: the tool first waits until Pi is idle and no user messages are pending, then starts the configured countdown and sends the compact trigger `while true | grow loop` only if Pi is still idle and no user messages are pending. A longer delay may serve as a continuation timer while asynchronous work finishes. The agent chooses it from evidence about expected remaining duration and reassesses after every wake; the one-hour maximum is exceptional rather than a polling default. If the runtime becomes busy during the countdown, the tool returns to deferred waiting instead of queueing a hidden follow-up. Status shows deferred scheduling as `loop ∞N` with the iteration number in warning color, countdown as `loop Ns`, and active iterations as `loop ∞N` with the iteration number dimmed; `N` is monotonic within the extension instance and advances once per turn that arms a deferred iteration; repeated tool calls in that turn only replace the delay while retaining the same iteration number.
+- `grow_loop` tool only schedules the next visible iteration; its optional `after_seconds` argument accepts `3` through `3600` and defaults to `3`; the minimum preserves an operator-interrupt window before every continuation. Scheduling is idle-deferred: the tool first waits until Pi is idle and no user messages are pending, then starts the configured countdown and sends the compact trigger `while true | grow loop` only if Pi is still idle and no user messages are pending. A longer delay may serve as a continuation timer while asynchronous work finishes. The agent chooses it from evidence about expected remaining duration and reassesses after every wake; the one-hour maximum is exceptional rather than a polling default. If the runtime becomes busy during the countdown, the tool returns to deferred waiting instead of queueing a hidden follow-up. Status shows deferred scheduling as `grow-loop ∞N` with the iteration number in warning color, countdown as `grow-loop Ns`, and active iterations as `grow-loop ∞N` with the iteration number dimmed; `N` is monotonic within the extension instance and advances once per turn that arms a deferred iteration; repeated tool calls in that turn only replace the delay while retaining the same iteration number.
 - There is no slash-command control surface. Any ordinary user prompt exits the active runtime rhythm by clearing pending scheduling and hiding loop status; restart/continuation intent belongs to the agent and Grow Loop skill, not to a runtime latch or regex.
 - No start slash commands, budgets, cycle counts, hidden processes, or background agents.
-- Loop status is dynamic: show warning-colored `loop ∞N` only while the next iteration is deferred until idle, `loop Ns` only during the configured countdown, and dim `loop ∞N` only while a loop-scheduled turn is active. Clear active status only after Pi fully settles without an armed successor; low-level run endings may still lead to retry or compaction recovery. Any user input except the runtime's exact expected continuation prompt clears pending loop scheduling and hides loop status, including operator input injected through another extension.
+- Loop status is dynamic: show warning-colored `grow-loop ∞N` only while the next iteration is deferred until idle, `grow-loop Ns` only during the configured countdown, and dim `grow-loop ∞N` only while a loop-scheduled turn is active. Clear active status only after Pi fully settles without an armed successor; low-level run endings may still lead to retry or compaction recovery. Any user input except the runtime's exact expected continuation prompt clears pending loop scheduling and hides loop status, including operator input injected through another extension.
 - Grow Loop does not own Escape/abort semantics; Escape remains baseline Pi behavior for active agent turns. The runtime does not block future `grow_loop` tool calls; the skill contract owns whether recent user context means continue, stop, restart, or change direction.
 
 ## Topology

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

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.7.5: Status Identity Hotfix
+
+- `Status Identity`: Labels deferred, countdown, and active runtime status as `grow-loop` instead of the ambiguous `loop`, matching the extension's public identity and the neighboring State Flow status convention.
+
 ## 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.

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

@@ -144,18 +144,18 @@ The tool never blocks future calls. Whether to continue belongs to the agent and
 ## Runtime Statuses
 
 - No status — no active loop rhythm, or the operator took the turn.
-- `loop ∞N` warning — the next loop prompt is armed and waiting for idle/no pending messages.
-- `loop Ns` countdown — Pi is idle and the configured delay is running.
-- `loop ∞N` dim — the compact loop prompt was sent for this iteration.
+- `grow-loop ∞N` warning — the next loop prompt is armed and waiting for idle/no pending messages.
+- `grow-loop Ns` countdown — Pi is idle and the configured delay is running.
+- `grow-loop ∞N` dim — the compact loop prompt was sent for this iteration.
 
-`N` is monotonic within the current extension instance and advances only once when a turn arms its deferred successor. Repeated `grow_loop` calls before that turn ends retain `N`, replace the pending delay, and report that the iteration was already scheduled. Active status clears when the scheduled agent run fully settles without arming a successor, so automatic retry or compaction recovery does not produce a false idle state. There is no `loop stopped` or `loop paused` status; absence of loop status means the runtime rhythm is no longer active.
+`N` is monotonic within the current extension instance and advances only once when a turn arms its deferred successor. Repeated `grow_loop` calls before that turn ends retain `N`, replace the pending delay, and report that the iteration was already scheduled. Active status clears when the scheduled agent run fully settles without arming a successor, so automatic retry or compaction recovery does not produce a false idle state. There is no `grow-loop stopped` or `grow-loop paused` status; absence of Grow Loop status means the runtime rhythm is no longer active.
 
 ## Interruption Model
 
 Any user prompt except the scheduler's exact expected continuation prompt exits the active runtime rhythm. This includes operator input delivered through Telegram, RPC bridges, or other extensions:
 
 ```text
-Runtime: loop 3.0s or loop ∞2
+Runtime: grow-loop 3.0s or grow-loop ∞2
 User: What changed?
 Runtime: hides loop status and cancels pending scheduling
 Agent: answers, stops, changes direction, or later continues based on intent and context
@@ -193,7 +193,7 @@ Normal continuation:
 ```text
 User: grow loop
 Agent: closes one backlog slice, validates, reports evidence, calls grow_loop
-Runtime: loop ∞1 → loop 3.0s → while true | grow loop
+Runtime: grow-loop ∞1 → grow-loop 3.0s → while true | grow loop
 ```
 
 Terminal stop proof:

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

@@ -9,6 +9,7 @@ import type {
 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;
@@ -42,7 +43,8 @@ function statusCountdown(ctx: ExtensionContext, seconds: number) {
   const theme = ctx.ui.theme;
   ctx.ui.setStatus(
     STATUS_KEY,
-    theme.fg("accent", "loop") + theme.fg("dim", ` ${seconds.toFixed(1)}s`),
+    theme.fg("accent", STATUS_LABEL) +
+      theme.fg("dim", ` ${seconds.toFixed(1)}s`),
   );
 }
 
@@ -50,7 +52,7 @@ function statusRunning(ctx: ExtensionContext, iteration: number) {
   const theme = ctx.ui.theme;
   ctx.ui.setStatus(
     STATUS_KEY,
-    theme.fg("accent", "loop") + theme.fg("dim", ` ∞${iteration}`),
+    theme.fg("accent", STATUS_LABEL) + theme.fg("dim", ` ∞${iteration}`),
   );
 }
 
@@ -58,7 +60,8 @@ function statusDeferred(ctx: ExtensionContext, iteration: number) {
   const theme = ctx.ui.theme;
   ctx.ui.setStatus(
     STATUS_KEY,
-    theme.fg("accent", "loop") + theme.fg("warning", ` ∞${iteration}`),
+    theme.fg("accent", STATUS_LABEL) +
+      theme.fg("warning", ` ∞${iteration}`),
   );
 }
 

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

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

package/node_modules/@llblab/pi-state-flow/AGENTS.md

@@ -3,26 +3,47 @@
 - Keep independent domain modules under `lib/`, mirror every domain with a same-named file under `tests/`, place cross-domain architecture checks in `tests/invariants.test.ts`, and keep `index.ts` as a minimal composition/public-export boundary.
 - Keep the extension opt-in and preserve clear attribution to SKILL.state wherever the inherited explicit-state approach is described.
 - Preserve Pi's native tool loop and complete inspectable session trace; project completed-run history only at user-run boundaries. Retain persistent and current-run context-bearing custom messages from other extensions, plus the complete current-run trajectory, except State Flow's own validation feedback when it is represented separately.
-- Expose one fully materialized state with exactly `contract`, `working`, and `response`; the first two are flexible memory objects and the third is the latest complete user-facing answer string.
-- Require no State Flow patch on tool-bearing assistant responses; retain the current run's user message, assistant tool calls, and tool results until one terminal response commits state.
-- Accept a non-empty ordinary terminal answer without a State Flow comment as an empty memory patch: preserve `contract` and `working`, replace `response`, and use the same staging, Skill-compilation validation, and commit lifecycle. Explicit comment markers (including malformed or embedded ones) must not silently fall back to ordinary text. When a patch is present, require one top-level transcript-private `<!-- state_flow … -->` comment containing only `contract` and `working`, one separating blank line, then the user-facing answer exactly once. At `message_end`, remove the comment and stage the transition; at `turn_end`, reconcile `response` with Pi's finalized assistant message after all chained handlers by concatenating finalized text blocks without inserted characters, then commit. Route missing text or a tool call added after terminal validation through the same bounded regeneration chain. Transcript-private does not mean confidential during streaming.
-- Treat terminal state as a decision-relevant handoff, not narration: compile stable requirements, decisions, rejected approaches, interface commitments, and reusable operational knowledge into `contract`; retain verified facts, artifacts, validation, failures, current domain state, unresolved work, and exact continuation in `working`.
+- Expose one canonical materialized state shape across global, CWD, and session scopes with exactly `artifacts`, `contract`, `working`, and `response`; the first three are flexible semantic objects and the fourth is the latest complete user-facing answer string where applicable.
+- Key artifacts directly by their source path. Require every artifact to have a non-empty `description`, a canonical lowercase `sha256:<64 hex>` source hash, and a non-empty compiler revision; permit forward-compatible metadata without requiring `kind`.
+- At session initialization, discover regular lowercase `*.md` files recursively beneath the configured Knowledge repository root; use canonical absolute paths, hash opaque source bytes and retain their byte counts without decoding or retaining bodies, skip symlinks, and never traverse outside that canonical root. Treat the current candidate set plus explicit removals as generic global artifact input without invoking Knowledge validators. Materialize removals deterministically as runtime-owned global transitions without rereading missing bodies or requesting model compiler output. Never reserve Knowledge document names, provide built-in Knowledge templates, or implement `save_knowledge`.
+- Determine artifact freshness from source hash plus compiler revision. Require compilation for new sources, changed hashes, compiler revision changes, missing or invalid metadata, and explicit refreshes; do not use `compiled_at` as the correctness signal. Plan acquisition from path/hash identity without source bodies, project stale global candidates as runtime-owned `artifact_invalidations`, and apply validated compilation/removal cohorts immutably so artifact metadata and its materialized scope advance atomically.
+- Correlate successful exact-path reads with the current ordinary global invalidation plan. Require each acquired stale source to have a compact compiler output at the same path in a global transition, reject model-authored hash/compiler fields, and attach the runtime-observed source hash plus current ordinary compiler revision before publication. Compile routing descriptions by default, never raw Markdown or a full-file summary; preserve uncertainty and reserve richer compilations for reusable operational semantics.
+- Apply one materialized-first acquisition policy to every source: read only for a concrete relevant gap not covered by a sufficient compilation, an exact-source operation including edits, evidenced invalidation, contradiction/failure reconciliation, explicit request, or selection by bounded maintenance. New sessions, routine recall or activation, reassurance, and an index or description alone are not reasons to read. Changed hashes require rereading; prefer the smallest sufficient read.
+- Keep artifact maintenance opt-in, low-frequency, and side-effect free until a selected source is acquired. Select only otherwise-fresh artifacts old enough for maintenance, rank missing/unparseable `compiled_at` first then oldest timestamp and path, and enforce strict per-cycle read-count and source-byte ceilings. Treat source bytes as the conservative source-token upper bound. Never let maintenance displace correctness invalidation; use explicit invalidation refresh for full rebuilds and never mutate source files.
+- Load optional agent-level `state-flow.json` once per extension load/reload. Its `directory` selects the state store, `autoStart` defaults false for genuinely new sessions, and `remotePublication` selects `off`, `turn-end`, or compatibility `transition`. State Flow always owns durable memory while enabled and global semantic memory is always available; these are invariants, not configuration switches. Keep runtime configuration and provenance outside model-patchable semantic state.
+- Keep runtime configuration and provenance separate from model-patchable semantic state. Persist session `config.json` for enablement/projection settings and `meta.json` for lineage, counters, branch identity, durable base, publication, and migration metadata. Neither participates in scope overlay. New Pi checkpoints contain only a durable revision pointer, or `{disabled:true}` when no durable runtime exists on that branch. Preserve exact Git hashes for Git-backed revisions and give file-only current-cohort references an unambiguous distinct identity; file references use `file:<64 lowercase hex>`, bind the store root and complete scoped/runtime cohort, and must not pretend to provide arbitrary cold or branch history. Operationally unavailable references (including expired file cohorts, missing Git, and publication exclusion) retain selection rather than falling through to older disabled markers; malformed immutable targets remain a distinct recovery case; they are not a parallel authoritative semantic or config/meta store. Emit a disabled marker only from proven pre-runtime branch provenance; missing/invalid revisions and failed restoration do not establish that permission. Predecessor checkpoint formats are read-only migration input. Validate immutable pointer targets before acquiring the live publication basis; transient publication failures preserve the selected retry reference rather than choosing older semantic state. In Git mode, runtime `revision: "self"` resolves to the commit owning the config/meta pair, not an unrelated later repository commit. File publication uses explicit `publication: "files"` provenance and resolves the exact complete live cohort instead of claiming a Git owner. Use a distinct `meta.temporalRevision` when a runtime-only write selects older semantic scopes, so stop or lifecycle persistence does not rewind another branch's live files. Persist publication intent as unconfirmed before pushing; reconcile that exact existing commit after restart rather than embedding an impossible self-hash or inventing semantic history.
+- Overlay materialized state recursively in `global → cwd → session` order. Scope-local deletion removes only that scope's key so a lower-scope value becomes visible again; scope never changes instruction authority. Route branch/run-local continuation to session, project-local reusable state and Skill artifacts to CWD, and cross-project reusable state to global.
+- Reserve `state` for the runtime materialized semantic view. For each scope, current state is exactly `materialize(checkpoint.json, patches.jsonl)`: an older anchored checkpoint plus its ordered tail of at most seven materially effective semantic patches. On overflow, apply the oldest patch into the checkpoint, advance its `through` boundary, remove it, and append the new patch. Never truncate unapplied replay records or replay patches over an already-current snapshot.
+- Give every accepted semantic transition one opaque identity shared by all affected scope records, with explicit active causal lineage. A branch-local position can order identities but never acts as a global counter, substitutes for identity, or merges forks. Unchanged scopes contribute no record and remain unchanged at that boundary. Adopt revision-proven inherited streams at a new session origin without rewriting their checkpoints/tails; pre-origin coordinates are not one shared clock. True semantic no-ops and origin adoption do not advance semantic history.
+- Define `state[n]` and `state.global[n]`, `state.cwd[n]`, `state.session[n]` at the same nth previous accepted transition boundary in the active lineage, never the nth local patch of each scope. Guarantee offsets zero through seven once the lineage has seven proven transitions; report earlier-than-origin history as unavailable for new/migrated lineages and reject offsets beyond seven on the hot interface. Reconstruct scopes at one target before overlaying them.
+- Keep historical reads lazy through the smallest runtime/model read interface. Normal inference gets only current effective state and useful bounded compact transition context, never eight full snapshots. `patch_state` is the sole semantic mutation tool. `read_state` exposes one cached effective/global/CWD/session projection at offset 0–7, defaulting to effective/0; it returns the exact boundary with semantic state and never publishes, appends a checkpoint, or advances history. Both tools follow branch enablement and host tool restrictions; the patch barrier blocks reader siblings too. Live/cached checkpoint plus tails own the hot path; use Git for branch restoration and explicit cold inspection, not to rebuild current state on every inference.
+- Store runtime state in its own directory with optional Git durability, defaulting to `state-flow/` beneath Pi's configured agent directory (`~/.pi/agent/state-flow/` normally), independently from the Knowledge Markdown source root. Use exactly these owned paths: `checkpoint.json` and `patches.jsonl` for global; `<cwd-key>/checkpoint.json` and `<cwd-key>/patches.jsonl` for CWD; `<cwd-key>/<session-key>/checkpoint.json`, `patches.jsonl`, `config.json`, and `meta.json` for session. Do not create `.state-flow`, `scopes`, or another storage/history namespace. Mirror Pi's native CWD session-directory encoding and JSONL-basename session key (deriving `<header timestamp>_<UUID>` for in-memory sessions), while retaining separately verifiable canonical identity provenance in owned state. Keep the UUID authoritative, reject unsafe segments and mismatches rather than selecting another scope, and use CWD checkpoint ownership to fail closed on Pi-name collisions.
+- Migrate legacy current `state.json` losslessly into an initial anchored checkpoint with an empty tail; current snapshots are the sole semantic recovery basis, independent of the presence or validity of explanatory journals, including historical revision reads. Preserve only proven history, remove obsolete files within the successful scoped migration, and never retain two authoritative formats. Exercise migrations in temporary repositories rather than modifying the user's active Knowledge data during development.
+- Read and write only regular non-symlink State Flow-owned files at those exact paths, publish each file by same-directory atomic rename, preserve arbitrary repository contents, and classify ownership exactly; never use repository-wide staging. Retain opaque source bytes for file identity and rollback, not decoded-text reconstructions. Use validated structural JSON equality for in-process semantic comparisons; reserve cryptographic hashes for compact identities that cross inference, persistence, process, or source-freshness boundaries. Serialize cooperating Git publications through a common-Git-directory publication lock; low-level file helpers require caller exclusion. Recheck prepared bases before each replacement/deletion and restore only bytes still matching the publisher's own output. Preserve detected concurrent changes and report unresolved rollback conflicts; do not claim kernel-atomic multi-file CAS against nonparticipating writers. Markdown discovery uses its independently configured source root, defaulting to `knowledge/` beneath Pi's agent directory; a storage-root override must not redirect source discovery.
+- At instance initialization resolve the repository, CWD key, and session key; load each scope's anchored checkpoint and tail, materialize at the selected temporal boundary, then overlay `global → cwd → session`. Install cached view and publication basis atomically only after successful restoration/initialization; unavailable publication is an error, not a semantic no-op. Preserve the selected revision across transient restore failure so an explicit start can retry it. A genuinely new session gets an empty session layer and inherits only global/CWD values; it must never reuse another same-CWD session layer.
+- Bind every loaded scope and active Pi branch/checkpoint to the corresponding State Flow Git revision. Resume and tree restoration must recover branch-correct runtime config and semantic layers from that revision without blindly importing Git `HEAD`; reading an older revision must use object-level Git reads and never reset or check out the shared repository worktree.
+- Every accepted semantic change, including session-only and response-only changes, atomically updates affected checkpoint/tail pairs and temporal metadata and creates one immediate local Git commit when Git is available. `remotePublication` is branch runtime policy: `turn-end` queues only the newest accepted target for asynchronous non-interactive push, `off` remains local-only, and `transition` preserves synchronous legacy behavior. Queue state is operational metadata beneath the Git common directory, not semantic history; use exact targets, destination identity, symlink-safe atomic CAS, descendant-only coalescing, cross-process worker leases, restart recovery, and truthful failure diagnostics. Remote failure never rolls back accepted state or regenerates an answer. A repository with no remote is intentionally local-only; only Git executable `ENOENT` authorizes file-only mode.
+- Register `patch_state` as the sole semantic mutation tool. It applies one validated `session`, `cwd`, or `global` semantic patch immediately through temporal folding/publication, records the accepted lineage and durable revision, returns a compact acknowledgement, and makes the next inference receive the new `state[0]`; the previous state becomes `state[1]`. Use it for established future-relevant state whose delayed materialization creates meaningful loss or recovery risk, or for a necessary write-and-verify step in explicitly requested curation; never use it for scratchpad, narration, routine progress, or speculative churn.
+- Treat `patch_state` as a strict inference barrier. Give it sequential execution mode, inspect Pi's synchronized current assistant message during tool preflight, require exactly one `patch_state` call in that response, and block every sibling tool call before execution. After success, retain the tool call/result as current-run causality and let the model choose all subsequent actions from rematerialized context.
+- Require exactly one terminal reconciliation after zero or more intermediate barriers in every successful enabled run. Accept a non-empty ordinary terminal answer without a State Flow comment as an empty model patch: preserve `artifacts`, `contract`, and `working`, replace session `response`, and persist that session semantic change through the same Git lifecycle. Explicit comment markers (including malformed or embedded ones) must not silently fall back to ordinary text. When a patch is present, require one top-level transcript-private `<!-- state_flow … -->` comment containing exactly a `transitions` array, one separating blank line, then the user-facing answer exactly once. Each transition must contain one unique known `scope` and an object `patch` limited to `artifacts`, `contract`, and `working`; reject model-authored `response`, runtime `config`, or provenance. Retain pre-scoped three-field envelopes only as session compatibility shorthand. At `message_end`, remove the comment and stage every affected scope against semantic hashes and the actual active causal-boundary identity, so equal values cannot authorize crossing to another lineage; at `turn_end`, reconcile session `response` with Pi's finalized assistant message after all chained handlers, atomically publish every affected checkpoint/tail pair and temporal metadata in one commit, and record its revision in the branch checkpoint. Do not write materially unchanged non-session scopes. Route missing text or a tool call added after terminal validation through the same bounded regeneration chain. Transcript-private does not mean confidential during streaming.
+- Treat terminal state as a decision-relevant handoff, not narration: retain source-addressed reusable operational knowledge in `artifacts`; compile stable requirements, confirmed decisions, rejected approaches, and interface commitments into `contract`; retain observations, validation, failures, current domain state, unresolved work, interaction consequences, and exact continuation in `working`. Preserve relevant completed prerequisites and verified outcomes while removing obsolete progress narration; reconcile only information affected by the run and relevant existing commitments, not every scope or repository surface.
 - Preserve active constraints, unresolved questions, consequential negative results, and the next discriminating check before compression. Distinguish observations, user requirements, assistant decisions, and hypotheses; do not promote assistant conclusions to user requirements. Retain useful source locators and validity conditions for consequential facts without mandatory per-value metadata. Keep rejection reasons and reconsideration conditions. Reconcile contradictions through evidence or user clarification instead of silently overwriting established constraints or observations; retain unresolved conflicts and decision-relevant hypotheses as uncertain. These are protocol obligations, not deterministic semantic validation gates.
-- Treat `working` as last observations, not a live workspace. Revalidate volatile facts before consequential actions; after interruption or branch navigation inspect relevant external effects before repeating operations. Failed state commits and restored memory do not undo tool effects. Missing evidence proves neither success nor absence of effects: retain uncertainty and the next check. Keep revalidation targeted, without routine Skill rereads, action ledgers, or runtime freshness/rollback guarantees.
-- Treat each successful `SKILL.md` read as episode-level acquisition using the finalized tool-execution arguments after mutable interception: require a non-empty `contract.compiled_skills[exactReadPath]`, keep its nested representation fully flexible without `coverage`/`rules` schema, reject the terminal commit when missing, treat complete matching compilations as authoritative, and forbid routine rereads without an uncovered detail, incomplete compilation, concrete source-change evidence, reconciliation failure, or explicit user request.
+- Treat `working` as last observations, not a live workspace. Revalidate volatile facts before consequential actions; after interruption or branch navigation inspect relevant external effects before repeating operations. Failed state commits and restored memory do not undo tool effects. Missing evidence proves neither success nor absence of effects: retain uncertainty and the next check. Keep revalidation targeted, without action ledgers or runtime freshness/rollback guarantees.
+- Treat each successful `SKILL.md` read as CWD artifact acquisition using the finalized tool-execution arguments after mutable interception: require a non-empty compiler output at the next intermediate or terminal CWD transition under `patch.artifacts[exactReadPath]` with `description`, `kind: "skill"`, and a flexible non-empty `compilation` object; hash the executed source bytes and attach runtime-owned `hash` plus `skill-artifact-v1` compiler metadata; reject missing, unhashable, malformed, or forged freshness data; replace the complete prior Skill artifact on refresh so obsolete metadata cannot survive. `contract.compiled_skills` is retired and rejected; migrate useful legacy entries into artifacts while preserving behavior and marking fallback hashes unverified when the source is unavailable.
 - Make the model audit and optimize complete state at every handoff: reorganize inefficient structure, merge fragmented facts, compress history into conclusions, and delete stale, completed, redundant, or low-value keys while preserving active commitments and evidence.
-- Accept empty `contract` and `working` patches when nothing future-relevant changed and memory is already efficient; never force invented bookkeeping. The comment may be omitted for a no-op memory patch. Always require `response`. Semantic usefulness and optimization remain protocol-owned because deterministic validation cannot prove them.
+- Accept omitted fields and empty scope patches when nothing future-relevant changed and memory is already efficient; never force invented bookkeeping. The comment may be omitted when no model patch is needed. Always require a finalized non-empty answer, which the runtime owns as session `response`. A changed response is a semantic transition; identical complete semantic state finalizes the runtime lifecycle without a patch, identity, or temporal step. Semantic usefulness and optimization remain protocol-owned because deterministic validation cannot prove them.
 - Keep validation retries hidden from finalized user-facing messages; expose diagnostic detail only through transcript-private feedback and persisted runtime state, while documenting that streaming observers can still see generated terminal envelopes. Tool-bearing retry turns must preserve cumulative validation-attempt accounting. If retries are exhausted, aborted, or cannot continue before the agent settles, keep State Flow enabled and the last committed state intact; abandon only the transient validation chain so the next user run rotates normally.
-- Recursively materialize patches immediately; empty objects preserve, nested object-key `null` deletes, and `null` anywhere in materialized state including arrays is invalid.
+- Recursively materialize patches immediately; empty objects preserve, nested object-key `null` deletes, and `null` anywhere in semantic state including arrays is invalid. This prohibition does not apply to runtime envelopes such as an origin's null parent. Persist runtime-normalized replay patches that exactly reproduce accepted state, including complete artifact replacement and trusted freshness metadata.
 - Do not impose project schemas, state or patch byte caps, dynamic growth pressure, observation envelopes, action authorization, action ledgers, or state-size limits.
 - Rotate the turn-stable specification on every non-retry user run, but not during its tool or terminal-validation retry chain. Keep user-controlled specification text at user authority: never interpolate it into the system prompt; repeat it only in synthetic user runtime context. Treat materialized state in that message as fallible assistant-produced data whose transport role does not elevate it into user instructions.
 - When enabled inside an existing session, retain Pi's active context for exactly one complete bootstrap run and require its terminal handoff to migrate all future-relevant context.
-- Restore extension state from the active session branch, not the full session entry list, on both session startup and successful in-session tree navigation.
-- Render compact status as accent `state-flow` plus dim `#<iteration>`; `/state-flow-status` must expose the complete materialized JSON state after a blank line separating it from summary metadata.
-- `/state-flow-stop` must disable and clear the complete episode; no separate reset commands exist.
+- Restore extension state from the active Pi session branch's checkpoint and recorded State Flow revision, not the full session entry list or current Git `HEAD`, on both startup and successful in-session tree navigation.
+- Render compact status as accent `state-flow` plus dim `#<step>`. `/state-flow-status` must distinguish session config/meta from semantic temporal materialization; show the CWD and session keys, step, active temporal head and State Flow revision, available hot-history depth, per-scope artifact/tail counts, discovered global Markdown stale reasons, pending push and terminal-retry state; and label global, CWD, session, and effective materializations without reading or dumping source bodies beyond the path/hash discovery needed for freshness diagnostics. Distinguish selected retained tail counts from active history depth; inherited tails may predate the origin. When temporal materialization is unavailable, report unknown counts/freshness and unavailable state rather than inventing empty projections.
+- Explicit `/state-flow-start` creates the State Flow directory when missing. If Git is installed, initialize an exact-root Git repository when needed, including a populated file-only store, preserving all existing bytes and unrelated files; an ancestor repository is not a valid substitute. If Git is absent, use file persistence. Manual-mode startup/status/restore do not initialize Git; configured automatic start of a genuinely new session uses the same initialization as explicit start. Never create external accounts, remote repositories, credentials, or remote configuration; those remain operator-owned. Never auto-import, delete, or reset files/history in a previous Knowledge-backed store; old branch revisions require their original Git history to remain available in the selected store. `/state-flow-start` must initialize missing global, CWD, and current-session checkpoint/tail pairs plus session config/meta through compare-and-swap publication when required, enable only the current session branch, and bootstrap prior conversation when needed. Explicit start on a proven pre-runtime branch (no checkpoint or an ordinary-disabled marker) establishes an empty session origin rather than importing a later same-session layer; validate existing runtime identity, retain shared streams unchanged, and preserve later branch data in cold Git history. Ordinary new sessions remain manual unless agent-level `autoStart` is true; CWD materialization alone grants no automatic activation. Configured new sessions may initialize missing CWD state and receive distinct empty session layers while inheriting global/CWD values. Resumed and tree-selected branches restore their own config and temporal lineage, regardless of the global flag.
+- `/state-flow-stop` must persist only the current session/branch's `config.enabled = false` and necessary runtime provenance, preserving all semantic checkpoints/tails and creating no semantic transition. It does not rewrite agent-level `autoStart` or change its policy for future new sessions.
 - Keep the injected runtime protocol compact and normative; put rationale and extended explanation in README rather than the model prompt. Strip accidental State Flow comments from tool-bearing output only when a complete structurally valid envelope (valid JSON fields, exact separator, and non-empty response) leads the first text block; never delete malformed, quoted, or embedded examples.
 - Do not claim strict boundedness for state, the current run trajectory, the turn specification, or the external full trace.
 - Remain extension-agnostic: do not import, name, special-case, or encode policy for any other extension or transport.
-- Register no model tools.
+- Activate State Flow model tools only while enabled on the selected branch; preserve every unrelated active tool when toggling them. Keep mutation confined to `patch_state` and historical observation read-only.
 - Keep `.github/workflows/release.yml` as the sole version-tag release owner: it validates immutable tag identity, publishes through npm Trusted Publisher with provenance, verifies the public package, and only then creates the GitHub Release. Keep package, lockfile, tag, and changelog versions aligned; never add a long-lived npm token fallback.
 - Run `npm run validate` after retained code changes.