@llblab/pi-kit 0.26.0 → 0.27.0

package/node_modules/@llblab/pi-state-flow/lib/git.ts

@@ -295,3 +295,66 @@ export function pushCurrentStateFlowBackup(repositoryRoot: string, signal?: Abor
 		if (signal?.aborted) cancelled();
 	});
 }
+
+/**
+ * Settled-turn backup obligation owned by one extension instance: an accepted
+ * publication makes a backup due, an accepted turn permits it at settlement,
+ * and one lifetime cancels owned captures/pushes without touching accepted state.
+ */
+export class SettledTurnBackup {
+	#turnAccepted = false;
+	#pending = false;
+	#lifetime = new AbortController();
+	#pushFailureNotified = false;
+	readonly #operations = new Set<Promise<unknown>>();
+
+	/** An accepted canonical publication makes the next settled-turn backup due. */
+	markPublished(): void { this.#pending = true; }
+
+	/** An accepted turn permits the due backup at its settlement. */
+	markTurnAccepted(): void { this.#turnAccepted = true; }
+
+	/** Forget the current turn's permission without dropping a due backup. */
+	clearTurn(): void { this.#turnAccepted = false; }
+
+	/** Consume the accepted-turn permission; true only when a backup is also due. */
+	takeSettledTurn(): boolean {
+		if (!this.#turnAccepted) return false;
+		this.#turnAccepted = false;
+		if (!this.#pending) return false;
+		this.#pending = false;
+		return true;
+	}
+
+	/** Lifetime signal for owned captures and pushes. */
+	get lifetime(): AbortSignal { return this.#lifetime.signal; }
+
+	/** Cancel owned work and the due backup, then open a fresh lifetime. */
+	cancel(): void {
+		this.#lifetime.abort();
+		this.#lifetime = new AbortController();
+		this.#pending = false;
+	}
+
+	/** Cancel owned work for shutdown without opening a new lifetime. */
+	abort(): void { this.#lifetime.abort(); }
+
+	/** Track one owned capture until it settles. */
+	async track<T>(operation: Promise<T>): Promise<T> {
+		this.#operations.add(operation);
+		try { return await operation; }
+		finally { this.#operations.delete(operation); }
+	}
+
+	/** Owned captures still in flight. */
+	get operations(): Promise<unknown>[] { return [...this.#operations]; }
+
+	/** True once per failure streak; a successful push resets it. */
+	claimPushFailureNotice(): boolean {
+		if (this.#pushFailureNotified) return false;
+		this.#pushFailureNotified = true;
+		return true;
+	}
+
+	resetPushFailureNotice(): void { this.#pushFailureNotified = false; }
+}

package/node_modules/@llblab/pi-state-flow/lib/operation.ts

@@ -0,0 +1,75 @@
+// Domain: one cancellable lifecycle owner slot shared by Start, inactive-mode persistence,
+// branch restoration, inference preparation and response reconciliation.
+
+/** Minimal shape of a cancellable owned lifecycle operation. */
+export interface OwnedOperation {
+	readonly controller: AbortController;
+	operation?: Promise<unknown>;
+}
+
+/**
+ * At most one current owner per lifecycle concern. A newer claim supersedes by
+ * explicit cancellation, and identity-guarded release prevents a late
+ * completion from clearing newer work.
+ */
+export class OwnedOperationSlot<E extends OwnedOperation> {
+	#current: E | undefined;
+	readonly #inflight = new Set<Promise<unknown>>();
+
+	/** The current owner, if any. */
+	get current(): E | undefined { return this.#current; }
+
+	/** True while `entry` still owns the slot. */
+	owns(entry: E): boolean { return this.#current === entry; }
+
+	/** Install a new owner; callers cancel a previous owner explicitly when supersession requires it. */
+	claim(entry: E): E {
+		this.#current = entry;
+		return entry;
+	}
+
+	/** Abort and forget the current owner; returns its operation for optional awaiting. */
+	cancel(): E["operation"] | undefined {
+		const entry = this.#current;
+		entry?.controller.abort();
+		this.#current = undefined;
+		return entry?.operation;
+	}
+
+	/** Forget `entry` only if it still owns the slot. */
+	release(entry: E): void {
+		if (this.#current === entry) this.#current = undefined;
+	}
+
+	/** Attach `operation` to `entry` and remember it until it settles, optionally releasing ownership then. */
+	track<P extends NonNullable<E["operation"]>>(entry: E, operation: P, releaseOnSettle = true): P {
+		entry.operation = operation;
+		this.#inflight.add(operation);
+		const settle = () => {
+			this.#inflight.delete(operation);
+			if (releaseOnSettle) this.release(entry);
+		};
+		void operation.then(settle, settle);
+		return operation;
+	}
+
+	/** Tracked operations not yet settled, including superseded ones. */
+	get inflight(): Promise<unknown>[] { return [...this.#inflight]; }
+}
+
+/** A renewable cancellation lifetime: ending it aborts every holder of the current signal. */
+export class RenewableLifetime {
+	#controller = new AbortController();
+
+	/** Signal of the current lifetime. */
+	get signal(): AbortSignal { return this.#controller.signal; }
+
+	/** Abort current holders and open a fresh lifetime. */
+	renew(reason?: unknown): void {
+		this.#controller.abort(reason);
+		this.#controller = new AbortController();
+	}
+
+	/** Abort current holders without opening a new lifetime (shutdown). */
+	end(reason?: unknown): void { this.#controller.abort(reason); }
+}

package/node_modules/@llblab/pi-state-flow/lib/ownership.ts

@@ -0,0 +1,120 @@
+import { isObject, type JsonObject, type JsonValue } from "./json.ts";
+import type { SemanticState, StateScope } from "./state.ts";
+
+/** Planes whose object keys an intent may own by structured reference. */
+export type OwnedPlane = "working" | "lazy";
+
+/** One same-scope object-key target of an intent ownership reference. */
+export interface OwnedPath {
+	plane: OwnedPlane;
+	keys: string[];
+}
+
+const OWNED_PLANES = new Set<string>(["working", "lazy"]);
+// Same key grammar as read_state value paths; array selectors never parse.
+const OBJECT_KEY = /^[A-Za-z_$][A-Za-z0-9_$-]*$/;
+
+/**
+ * Parse one structured `$ref` target as an ownership path of `scope`.
+ * Cross-scope, unscoped, `effective`, historical, plane-root, array-element
+ * and non-`working`/`lazy` targets are not ownership targets.
+ */
+export function parseOwnedPath(scope: StateScope, ref: string): OwnedPath | undefined {
+	const parts = ref.split(".");
+	if (parts.length < 3 || parts[0] !== scope || !OWNED_PLANES.has(parts[1]!)) return undefined;
+	const keys = parts.slice(2);
+	if (!keys.every((key) => OBJECT_KEY.test(key))) return undefined;
+	return { plane: parts[1] as OwnedPlane, keys };
+}
+
+function pathId(path: OwnedPath): string {
+	return JSON.stringify([path.plane, ...path.keys]);
+}
+
+/** Extract unique ownership targets from structured references anywhere inside one intent value. */
+export function extractOwnedPaths(scope: StateScope, value: JsonValue): OwnedPath[] {
+	const found = new Map<string, OwnedPath>();
+	const visit = (node: JsonValue): void => {
+		if (Array.isArray(node)) {
+			for (const item of node) visit(item);
+			return;
+		}
+		if (!isObject(node)) return;
+		if (typeof node.$ref === "string") {
+			const path = parseOwnedPath(scope, node.$ref);
+			if (path) found.set(pathId(path), path);
+		}
+		for (const key of Object.keys(node)) if (key !== "$ref" || typeof node[key] !== "string") visit(node[key]!);
+	};
+	visit(value);
+	return [...found.values()];
+}
+
+function related(left: OwnedPath, right: OwnedPath): boolean {
+	if (left.plane !== right.plane) return false;
+	const length = Math.min(left.keys.length, right.keys.length);
+	for (let index = 0; index < length; index++) if (left.keys[index] !== right.keys[index]) return false;
+	return true;
+}
+
+function exists(state: SemanticState, path: OwnedPath): boolean {
+	let node: JsonValue | undefined = state[path.plane];
+	for (const key of path.keys) {
+		if (!isObject(node) || !Object.hasOwn(node, key)) return false;
+		node = node[key];
+	}
+	return true;
+}
+
+/**
+ * Compute the same-scope ownership cascade for intent keys removed between
+ * `before` and `after` (the state after authored operations). A target is
+ * kept while any remaining intent references it, an ancestor or a descendant;
+ * missing targets are skipped. The result is minimal (no target below
+ * another) and deterministically ordered.
+ */
+export function computeIntentCascade(scope: StateScope, before: SemanticState, after: SemanticState): OwnedPath[] {
+	const previous = isObject(before.intents) ? before.intents : {};
+	const remaining = isObject(after.intents) ? after.intents : {};
+	const deleted = Object.keys(previous).filter((key) => !Object.hasOwn(remaining, key));
+	if (deleted.length === 0) return [];
+	const candidates = new Map<string, OwnedPath>();
+	for (const key of deleted) for (const path of extractOwnedPaths(scope, previous[key]!)) candidates.set(pathId(path), path);
+	if (candidates.size === 0) return [];
+	const retained = Object.values(remaining).flatMap((value) => extractOwnedPaths(scope, value));
+	const owned = [...candidates.values()].filter((path) =>
+		!retained.some((other) => related(path, other)) && exists(after, path));
+	return owned
+		.filter((path) => !owned.some((other) => other.keys.length < path.keys.length && related(path, other)))
+		.sort((left, right) => pathId(left).localeCompare(pathId(right)));
+}
+
+/** Express cascade targets as explicit nested object-key deletions. */
+export function cascadeDeletionPatch(paths: readonly OwnedPath[]): JsonObject {
+	const patch: JsonObject = {};
+	const define = (target: JsonObject, key: string, value: JsonValue) =>
+		Object.defineProperty(target, key, { value, enumerable: true, configurable: true, writable: true });
+	for (const path of paths) {
+		if (!Object.hasOwn(patch, path.plane)) define(patch, path.plane, {});
+		let node = patch[path.plane] as JsonObject;
+		for (const key of path.keys.slice(0, -1)) {
+			if (!Object.hasOwn(node, key)) define(node, key, {});
+			node = node[key] as JsonObject;
+		}
+		define(node, path.keys.at(-1)!, null);
+	}
+	return patch;
+}
+
+/** Render an ownership target as its scoped `read_state` path. */
+export function formatOwnedPath(scope: StateScope, path: OwnedPath): string {
+	return [scope, path.plane, ...path.keys].join(".");
+}
+
+/** Top-level `working`/`lazy` keys that at least one current intent of `scope` owns. */
+export function ownedTopLevelKeys(scope: StateScope, state: SemanticState): Record<OwnedPlane, Set<string>> {
+	const owned: Record<OwnedPlane, Set<string>> = { working: new Set(), lazy: new Set() };
+	const intents = isObject(state.intents) ? state.intents : {};
+	for (const value of Object.values(intents)) for (const path of extractOwnedPaths(scope, value)) owned[path.plane].add(path.keys[0]!);
+	return owned;
+}

package/node_modules/@llblab/pi-state-flow/lib/protocol.ts

@@ -1,5 +1,4 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { isObject } from "./json.ts";
 
 export type { StateDocument } from "./state.ts";
 
@@ -89,24 +88,24 @@ export function stateFlowProtocol(bootstrap: boolean): string {
 	return `State Flow is enabled. It owns durable memory.
 
 ${bootstrapProtocol}STATE:
-- intents: chosen active commitments; detail may stay lazy; remove when fulfilled, abandoned, superseded, or impossible.
-- contract: durable requirements, decisions, rejections, interfaces, compiled knowledge.
-- working: facts, validation, failures, domain state, unresolved work, continuation.
+- intents: queue of chosen actions; work from them; remove when fulfilled, abandoned, superseded, or impossible.
+- contract: durable requirements, decisions, rejections, interfaces.
+- working: temporary context of intents: facts, validation, failures, domain state.
 - artifacts: source-path routing metadata; descriptions do not imply body acquisition.
-- response: previous answer; runtime stores the exact accepted answer at turn_end (empty=""). Ordinary assistant completion needs no finalization patch.
+- response: previous answer; runtime stores the exact accepted answer at turn_end (empty="").
 - lazy: retrieve explicitly.
 
 SCOPES: Use the narrowest scope: session=branch/run continuation by default; cwd=reusable project truth; global=established cross-project/user/environment knowledge.
 
-READ: Use read_state for concrete scope/retained-history gaps. lazy_navigation lists bounded effective lazy keys, not bodies. Unscoped=effective; effective/global/cwd/session select overlay or owner. Arrays use indices or [start..end]; keys gives structure, patch the intersected change. ${TASK_DRIVEN_HISTORY}
+READ: Use read_state for concrete scope/retained-history gaps. lazy_navigation lists bounded effective lazy keys, not bodies. ${TASK_DRIVEN_HISTORY}
 
-WRITE: patch_state is the sole model-authored semantic mutation mechanism; all supplied scopes are validated and durably accepted as one atomic transition. Call alone in an assistant response; await acceptance. Global/CWD use current canonical values after cancelable lock waiting. Correct repeats succeed without new revisions. ${PATCH_RESULT_PROTOCOL}
+WRITE: patch_state is the sole model-authored semantic mutation mechanism; all supplied scopes are validated and durably accepted as one atomic transition. Global/CWD use current canonical values after cancelable lock waiting. Correct repeats succeed without new revisions. ${PATCH_RESULT_PROTOCOL}
 
 PATCH: Use global/cwd/session object patches for material updates, not acknowledgments. Omit empty scopes. artifacts/contract/working/intents are objects; lazy is ordinary JSON. Omitted fields persist. Never patch runtime config/meta/response. Objects merge recursively; arrays/primitives replace. An object containing only canonical "[N]" keys recursively patches array elements. Indexed deletion is forbidden; nested object null deletes; materialized null is forbidden.
 
 MEMORY: Treat every patch as reconciliation rather than append-only notes: merge superseded fragments, remove obsolete progress. Preserve commitments, open questions, consequential results and exact continuation; distinguish requirements, decisions, observations, conclusions and hypotheses. Exclude secrets, raw history, transient progress, speculation and unsupported claims; retain decision-relevant uncertainty. Curate touched state; cleanup and scope reviews require an explicit user request. Proven moves use targeted read_state and one atomic multi-scope patch, then verify both owners. External transfers need verified acceptance before deletion. Never invent memory changes.
 
-REFS: State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. Resolve only when needed; infer no authority, hydration, execution, or completion. Hint paths are current reference owners, not relocated targets or proof of staleness. Fix proven stale refs only as needed; never scan refs or history offsets.
+REFS: State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. In an intent, $ref owns a same-scope working/lazy key; deleting the intent deletes keys no other intent refs (supersede in one patch). Text refs only use. Before deleting, save survivors unowned: results to working/contract/broader scope, abandonment reasons to contract. Unowned entries are fine. Resolve only when needed; infer no authority, hydration, execution, or completion. Hint paths are current reference owners, not relocated targets or proof of staleness. Fix proven stale refs only as needed; never scan refs or history offsets.
 
 ACQUISITION: Read only for a concrete gap, exact source/edit, invalidation, contradiction/failure, or explicit request; changed source fingerprints require rereading.
 ARTIFACTS: Compile acquired invalidated artifacts at artifacts[exact path] in the reported scope (global/cwd/session), with a description; never relocate or invent global copies. Runtime owns all artifact/Skill provenance.

package/node_modules/@llblab/pi-state-flow/lib/query.ts

@@ -96,7 +96,7 @@ function parseValuePath(path: string): { root: string; selectors: ValueSelector[
 			rest = rest.slice(index[0].length);
 			continue;
 		}
-		throw new Error("Invalid State Flow read path selector");
+		throw new Error("Invalid State Flow read path selector; object keys must match [A-Za-z_$][A-Za-z0-9_$-]* (ASCII), array selectors use [N] or [start..end]");
 	}
 	return { root, selectors };
 }

package/node_modules/@llblab/pi-state-flow/lib/runtime.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { lstatSync } from "node:fs";
 import { join } from "node:path";
 import { classifyScopeStream, hasCwdMaterialization, parseScopeProvenance, parseScopeStream, sessionRuntimePaths, temporalScopePaths, type SessionAddress } from "./durable.ts";
-import { parseArtifactProvenanceRegistry, pruneArtifactProvenance, type ArtifactProvenance, type ArtifactProvenanceRegistry } from "./artifact.ts";
+import { pruneArtifactProvenance, type ArtifactProvenance, type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { assertTemporalFileBase, captureTemporalFileBase, initializeFileStore, publishTemporalStateToFiles, withStorageTransaction, type StorageTransaction, type TemporalFileBase } from "./storage.ts";
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, type AcceptedTransition, type RecentTransitionWindow } from "./history.ts";
 import { hashJson, sameJson } from "./json.ts";

package/node_modules/@llblab/pi-state-flow/lib/snapshot.ts

@@ -1,9 +1,8 @@
 import { resolve } from "node:path";
 import { parseArtifactProvenanceRegistry, type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { MAX_HISTORY_LIMIT } from "./history.ts";
-import { applyPatch, canonicalJson, containsNull, isJsonValue, isObject, type JsonObject } from "./json.ts";
+import { canonicalJson, isJsonValue, isObject, type JsonObject } from "./json.ts";
 import { validateTemporalLineage, type TransitionBoundary } from "./temporal.ts";
-import { isMaterializedState, type MaterializedState } from "./state.ts";
 const MAX_RESTORED_STEP = Number.MAX_SAFE_INTEGER - 1;
 const MAX_LEGACY_VALIDATION_ATTEMPT = 7;
 

package/node_modules/@llblab/pi-state-flow/lib/status.ts

@@ -1,5 +1,6 @@
 import type { ArtifactInvalidationReason } from "./artifact.ts";
 import type { RecentTransitionWindow } from "./history.ts";
+import { ownedTopLevelKeys } from "./ownership.ts";
 import { conciseDiagnostic } from "./protocol.ts";
 import type { Snapshot } from "./snapshot.ts";
 import { overlayStates, projectSemanticState, type SemanticState, type ScopedStates, type StateScope } from "./state.ts";
@@ -46,6 +47,33 @@ function countArtifacts(states: ScopedStates, scope: StateScope): number {
 	return Object.keys(states[scope].artifacts).length;
 }
 
+const STATUS_PLANES = ["intents", "contract", "working", "artifacts", "response", "lazy"] as const;
+const encoder = new TextEncoder();
+
+function isPresentPlane(value: unknown): boolean {
+	if (value === undefined || value === "") return false;
+	return typeof value !== "object" || value === null || Object.keys(value).length > 0;
+}
+
+/** Operator-only footprint: serialized plane sizes and intent-owned share of top-level working/lazy entries. */
+export function scopeMemoryLines(states: ScopedStates): string[] {
+	const lines: string[] = [];
+	for (const scope of ["global", "cwd", "session"] as const) {
+		const state = states[scope] as SemanticState;
+		const sizes = STATUS_PLANES.filter((plane) => isPresentPlane(state[plane]))
+			.map((plane) => `${plane} ${encoder.encode(JSON.stringify(state[plane])).length} B`);
+		if (sizes.length === 0) continue;
+		const owned = ownedTopLevelKeys(scope, state);
+		const shares = (["working", "lazy"] as const).flatMap((plane) => {
+			const value = state[plane];
+			const keys = value !== null && typeof value === "object" && !Array.isArray(value) ? Object.keys(value) : [];
+			return keys.length === 0 ? [] : [`${plane} ${keys.filter((key) => owned[plane].has(key)).length}/${keys.length}`];
+		});
+		lines.push(`- ${scope}: ${sizes.join(", ")}${shares.length ? `; intent-owned ${shares.join(", ")}` : ""}`);
+	}
+	return lines.length ? ["Scope memory:", ...lines] : [];
+}
+
 export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostics): string {
 	const available = diagnostics.temporal !== undefined && diagnostics.durableStateError === undefined;
 	const materialized = !available ? undefined : diagnostics.effectiveState ?? projectSemanticState(overlayStates(
@@ -79,6 +107,7 @@ export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostic
 		...(diagnostics.publicationError === undefined ? [] : [`Memory writes paused after mode change: ${conciseDiagnostic(diagnostics.publicationError)}`]),
 		...(hasArtifacts ? [`Artifacts: global ${artifacts("global")}; CWD ${artifacts("cwd")}; session ${artifacts("session")}; pending invalidations ${invalidated}`] : []),
 		...invalidationLines,
+		...(available ? scopeMemoryLines(diagnostics.scopeStates) : []),
 		...(stateJson === undefined
 			? ["Effective memory: unavailable"]
 			: ["Effective memory:", "", stateJson]),

package/node_modules/@llblab/pi-state-flow/lib/transition.ts

@@ -10,6 +10,7 @@ import {
 import type { SuccessfulArtifactRead } from "./acquisition.ts";
 import { createAcceptedTransition, type AcceptedTransition } from "./history.ts";
 import { applyPatch, containsNull, hashJson, isObject, validatePatch, type JsonObject } from "./json.ts";
+import { cascadeDeletionPatch, computeIntentCascade } from "./ownership.ts";
 import { hasCompiledSkillArtifact, SKILL_ARTIFACT_COMPILER, type SuccessfulSkillRead } from "./skills.ts";
 import type { Snapshot } from "./snapshot.ts";
 import { emptyState } from "./state.ts";
@@ -188,7 +189,10 @@ function stageScopedSemanticTransition(
 	for (const scope of SCOPES) {
 		const authored = patches.get(scope) ?? {};
 		const patch = { ...authored, ...(scope === "session" && acceptedResponse !== undefined ? { response: acceptedResponse } : {}) };
-		const materialized = applyPatch({ ...emptyState(), ...currentStates[scope] }, patch) as StateDocument;
+		let materialized = applyPatch({ ...emptyState(), ...currentStates[scope] }, patch) as StateDocument;
+		// Authored operations first, then the same-scope intent ownership cascade.
+		const cascade = computeIntentCascade(scope, currentStates[scope], materialized);
+		if (cascade.length > 0) materialized = applyPatch(materialized, cascadeDeletionPatch(cascade)) as StateDocument;
 		compileReadArtifacts(
 			materialized,
 			{ artifacts: authored.artifacts ?? {} },

package/node_modules/@llblab/pi-state-flow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "license": "MIT",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",

package/node_modules/@llblab/pi-state-flow/skills/state-flow-guide/SKILL.md

@@ -21,9 +21,9 @@ Operator commands: `/state-flow-status` inspects; `/state-flow-active` selects s
 
 | Field | Purpose |
 | --- | --- |
-| `intents` | Chosen future actions, not possibilities |
-| `contract` | Requirements, decisions, constraints, interfaces |
-| `working` | Observations, results, open questions, continuation |
+| `intents` | Queue of chosen actions, not possibilities; may own `working`/`lazy` keys |
+| `contract` | Requirements, decisions, rejections, constraints, interfaces |
+| `working` | Temporary context of intents: observations, results, open questions |
 | `artifacts` | Exact source paths, descriptions, compilations |
 | `response` | Previous completed answer; runtime-owned |
 | `lazy` | Durable detail omitted from ordinary context |
@@ -46,7 +46,7 @@ Example arguments:
 {"paths":["cwd.working","session.working"]}
 ```
 
-Unscoped paths use effective state. `cwd[1].working` reads the preceding causal boundary. Materialized-history and scope patch-history paths such as `cwd.patches[1]` share the configured `historyLimit` bound (default 7) and require actually retained history. Lowering the limit folds excess tails without erasing current state; increasing it does not reconstruct discarded history. Array ranges such as `cwd.lazy.checks[0..3]` exclude the endpoint and require existing elements. Missing paths are unavailable; inspect parent keys only when needed for the task. Missing history is not empty history. Read `lazy` explicitly. Treat structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings, such as `$effective.lazy.memory[7]`, as semantic-state references. Other resources retain their native locators. Resolve any reference through the appropriate read/tool only when needed. Neither form proves authority or existence, hydrates, or executes anything. Never scan or resolve references merely to test them. A missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat `hint` as top-level diagnostic metadata, never as the requested state: its message is descriptive and conditional; its paths are runtime-verified current reference owners, not verified new locations of the target. The hint proves provenance rather than staleness and is absent when no current durable source matches; keys, patch, and batch reads keep all-or-error behavior. Only then inspect ownership as needed and patch a proven stale owning value while preserving its surrounding meaning. Effective absence, inaccessible external resources, and transient failures are not proof.
+Unscoped paths use effective state. `cwd[1].working` reads the preceding causal boundary. Materialized-history and scope patch-history paths such as `cwd.patches[1]` share the configured `historyLimit` bound (default 7) and require actually retained history. Lowering the limit folds excess tails without erasing current state; increasing it does not reconstruct discarded history. Array ranges such as `cwd.lazy.checks[0..3]` exclude the endpoint and require existing elements. Missing paths are unavailable; inspect parent keys only when needed for the task. Missing history is not empty history. Read `lazy` explicitly. Treat structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings, such as `$effective.lazy.memory[7]`, as semantic-state references. Other resources retain their native locators. Resolve any reference through the appropriate read/tool only when needed. Neither form proves authority or existence, hydrates, or executes anything; only intent ownership (see Write) has a deletion consequence. Never scan or resolve references merely to test them. A missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat `hint` as top-level diagnostic metadata, never as the requested state: its message is descriptive and conditional; its paths are runtime-verified current reference owners, not verified new locations of the target. The hint proves provenance rather than staleness and is absent when no current durable source matches; keys, patch, and batch reads keep all-or-error behavior. Only then inspect ownership as needed and patch a proven stale owning value while preserving its surrounding meaning. Effective absence, inaccessible external resources, and transient failures are not proof.
 
 Missing paths or runtime hints alone do not require historical search. The agent may choose a targeted historical read when a previous value is useful to the current task, without separate user permission. Otherwise continue without searching. Use found values as historical evidence, not automatically as current state; never automatically restore deleted memory. Do not scan all offsets, hydrate automatically or request repair inference. A hint does not prove prior existence, retained history or relocation. A proven stale reference may be repaired within touched work without resurrecting its target. Automatic state and recent-transition projections omit lazy bodies; bounded `lazy_navigation` preserves structure, and explicit current/historical reads still return requested lazy values or patches.
 
@@ -58,12 +58,20 @@ The runtime waits cancelably for publication ownership, then applies authored Gl
 
 When present, semantic planes `intents`, `contract`, `working`, `artifacts`, and `lazy` are objects; nested lazy values may contain ordinary JSON without stored nulls. Stored checkpoints and patches may omit any documented plane. Current and historical views assemble only known fields present in the selected scopes. Absent fields and empty responses are omitted from views. Checkpoint/tail readers ignore unknown top-level fields, and writers emit only known fields. Nested data within known planes remains intact. Explicit value reads of an absent documented top-level field return `null`. Authored `patch_state` keeps its documented field grammar. Objects merge, arrays/scalars replace, omitted fields persist. Nested `null` removes an owned object key; inherited content may reappear. Canonical `"[N]"` keys patch array elements; indexed deletion is forbidden.
 
-Illustrative deletion, only for an actually completed intent and after satisfying pending acquisitions:
+Work from intents. A structured `{"$ref"}` anywhere inside an intent owns ("delete with me") an existing object key under `working` or `lazy` in the same scope; a textual `$path` mention only uses it. Opening a task:
 
 ```json
-{"session":{"intents":{"check_api":null}}}
+{"session":{"intents":{"check_api":{"action":"Verify the API","notes":{"$ref":"session.working.api"},"plan":{"$ref":"session.lazy.api_plan"}}},"working":{"api":"draft findings"},"lazy":{"api_plan":["probe","compare"]}}}
 ```
 
+Deleting the intent deletes the owned keys after the authored operations, in the same atomic patch, unless another remaining same-scope intent references the target, an ancestor or a descendant. Before closing, move what must survive to an unowned path: results to `working`, `contract` or a broader scope; reasons for abandoned work to `contract` as rejected approaches. Supersede in one patch by deleting the old intent and referencing the same targets from its replacement. Writing to an owned target in the same patch that deletes its intent does not save it: the write is deleted too. Only keys matching `[A-Za-z_$][A-Za-z0-9_$-]*` can be owned. Cross-scope, plane-root, array-element and non-`working`/`lazy` targets are never deleted, nothing is rejected or warned about, and unowned entries remain legal. Illustrative closing, only for an actually completed intent and after satisfying pending acquisitions:
+
+```json
+{"session":{"intents":{"check_api":null},"contract":{"api":"verified: v2 only"}}}
+```
+
+Name object keys in ASCII matching `[A-Za-z_$][A-Za-z0-9_$-]*` (for example `api_plan`, not a Cyrillic or spaced key): other keys cannot be addressed by `read_state` paths or `$` references, and cannot be owned by intents. Values may use any language.
+
 Never edit backing files, `response`, configuration, provenance, or runtime metadata. Verify changed owner paths when needed; check effective state after override deletion.
 
 ## Acquire and finish

package/node_modules/@llblab/pi-state-flow/skills/state-flow-memory/SKILL.md

@@ -20,9 +20,9 @@ Follow the installed runtime contract. This registered Skill follows its Pi sour
 ## Reconcile one bounded set
 
 1. **Limit the review.** Address the requested scope. A completed phase may motivate recommending cleanup, not starting it without a request. For a whole-state cleanup, inspect global, CWD, and session ownership explicitly; for a narrower request, inspect only affected owners. Use targeted reads for gaps, contradictions, ownership, or verification; do not rerun the project.
-2. **Classify.** Put user requirements and binding confirmed decisions in `contract`, observations, assistant conclusions, and unresolved work in `working`, chosen actions in `intents`, and inactive reusable detail in `lazy`. Never give an assistant conclusion user authority. Remove fulfilled, abandoned, superseded, or impossible intents; retain consequential results. Possibilities are not commitments.
+2. **Classify.** Put user requirements and binding confirmed decisions in `contract`, the queue of chosen actions in `intents`, their temporary context (observations, assistant conclusions, results in progress) in `working`, and inactive reusable detail in `lazy`. Never give an assistant conclusion user authority. Possibilities are not commitments. Name keys in ASCII (`[A-Za-z_$][A-Za-z0-9_$-]*`) so paths, references and ownership resolve; values may use any language. Work from intents: a structured `{"$ref"}` inside an intent owns ("delete with me") a same-scope `working`/`lazy` key; a textual `$path` mention only uses it. Deleting a fulfilled, abandoned, superseded, or impossible intent deletes owned keys no remaining same-scope intent references, so first move what must survive to an unowned path (a write to an owned key in the deleting patch is deleted too): results to `working`, `contract`, or a broader scope; reasons for abandoned work to `contract` as rejected approaches. Supersede in one patch by referencing the same targets from the replacement. Unowned entries remain legal.
 3. **Keep evidence boundaries.** Preserve corrections, prerequisites, bounded negative results, and useful uncertainty. Separate requirements, decisions, observations, conclusions, and hypotheses. Silence is not acceptance; repetition is not verification. One implementation's failure does not reject an approach. Neither freeze provisional methods nor reopen confirmed decisions without grounds.
-4. **Compact for continuation.** Remove duplicates, obsolete progress, unsupported claims, and secrets. Keep sufficient results, real retrieval pointers, pending interaction, and known next checks. Observations are not live external facts. Keep `lazy` shallow and priority-ordered. Recognize optional structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings as semantic-state references; other resources retain native locators. No reference form proves authority or existence, authorizes execution, or implies completion. Never scan or resolve references merely to find broken ones. When the bounded review independently needs a reference, a missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat the top-level hint as conditional navigation and provenance, never as requested state or proof of staleness; its paths are runtime-verified current reference owners, not verified new locations of the target, while no hint does not prove invention. Inspect ownership only as needed, then patch a proven stale owning value while preserving surrounding meaning. Effective absence or external inaccessibility is insufficient.
+4. **Compact for continuation.** Remove duplicates, obsolete progress, unsupported claims, and secrets. Keep sufficient results, real retrieval pointers, pending interaction, and known next checks. Observations are not live external facts. Keep `lazy` shallow and priority-ordered. Recognize optional structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings as semantic-state references; other resources retain native locators. No reference form proves authority or existence, authorizes execution, or implies completion; only intent ownership has a deletion consequence. Never scan or resolve references merely to find broken ones. When the bounded review independently needs a reference, a missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat the top-level hint as conditional navigation and provenance, never as requested state or proof of staleness; its paths are runtime-verified current reference owners, not verified new locations of the target, while no hint does not prove invention. Inspect ownership only as needed, then patch a proven stale owning value while preserving surrounding meaning. Effective absence or external inaccessibility is insufficient.
 5. **Check ownership.** Prefer `session` for branch/run continuation, `cwd` for project knowledge, and `global` for established cross-project knowledge. Effective values do not prove ownership; inspect owners before moves. Broader applicability requires evidence.
 
 Missing paths or runtime hints alone do not require historical search. The agent may choose a targeted historical read when a previous value is useful to the current task, without separate user permission. Otherwise continue without searching. Use found values as historical evidence, not automatically as current state; never automatically restore deleted memory. Do not scan all offsets, hydrate automatically or request repair inference. A hint does not prove prior existence, retained history or relocation. A proven stale reference may be repaired within touched work without resurrecting its target. Lazy bodies require explicit reads; automatic state/history projections retain navigation without hydrating those bodies.

package/node_modules/@llblab/pi-telegram/BACKLOG.md

@@ -2,6 +2,7 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
+- [ ] `Connect intent across resume` (`post-release acceptance`): The operator approved 0.51.6 release on the successful smoke and green Linux/macOS/Windows CI; this expanded live matrix is not a release blocker. Run live acceptance after rebuilding/reloading: start bare Pi, invoke `/telegram-connect` (default and named profile), immediately `/resume` a session with/without a binding. Check both leader and follower; confirm one connected destination, its correct retained/new slot, no source-target transplant, stale-context error or duplicate notice. Repeat a switch during startup and confirm disconnect cancels it. Native composition, destination-binding, cancellation, and late-completion regressions pass locally. The operator observed one immediate-resume connection complete after a short wait without error; the full profile/role/binding and cancellation matrix remains unverified live.
 - [ ] [`Workspace Thread recovery`](./docs/multi-instance-bus.md) (`environment-gated`): Complete native-Windows coverage for follower restore, inaccessible callbacks, stale targets, and Singleton↔Threaded transitions while preserving accepted work and current ownership.
   - [ ] Select an approved exact-absence observation before implementing ambiguous `deletion-issued` recovery. Never replay an unknown deletion or infer absence from cache, heartbeat silence, empty `editForumTopic`, or `sendChatAction` success.
 - [ ] [`Automatic pairing and follower input custody`](./docs/architecture.md#automatic-pairing-confirmation-design) (`activation-gated`): Keep production custody disabled until historical sources and physical references are reconciled, all legacy writers/consumers are retired or excluded under operator authority, migration is complete, and every participating peer supports the final protocol. Preserve outcome-unknown running work, exact receipt/group authority, authenticated handoff, and rollback/downgrade safety. Then compose the prepared v3 lifecycle/bus ports, add bounded operator disposition for retained legacy retry state, and run real-process plus native-Windows acceptance.

package/node_modules/@llblab/pi-telegram/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ## Unreleased
 
+## 0.51.6: Connection resume and Workspace recovery hotfix
+
+- `Workspace slot recovery`: Confirmed pressure-retirement deletion invalidates the exact stale active-target record before binding removal. Same-process and successor retries finish a retained `commit-ready` fence without repeating Telegram deletion, preventing exhausted A–Z slots from deadlocking on `protection-changed`. Includes [#305](https://github.com/llblab/pi-telegram/pull/305).
+- `Connect lifecycle`: `/telegram-connect` checks plain session generation before reading Pi context getters after awaited work. Replaced commands cannot publish stale connection notices or retry startup against the old session; config, startup, recovery and takeover confirmation discard obsolete results.
+- `Resume connection`: In-flight `/telegram-connect` or an already connected bridge carries bounded same-process intent into the resumed session, retaining the selected profile but not the source Thread. Startup restores the destination's exact binding or provisions its own slot; cancellation, expiry and late completion cannot revive obsolete work.
+- `Thread binding isolation`: Session-aware startup no longer reuses another session's active target or legacy instance binding. Pending Thread creation records its Workspace binding key; unproven or foreign-session recovery is blocked without consuming evidence or repeating creation.
+- `Connection feedback`: Manual/resumed connection failures use compact cause-and-action notices rather than raw exception guidance. Detailed errors remain in redacted diagnostics; recovery success produces one short notice, and failed disconnect keeps Pi open without a duplicate exception banner. Delayed disconnect completion cannot touch a replaced Pi context.
+- `Model continuation`: In-flight model switching injects one compact line with the resume instruction, selected model and optional thinking level, preserving the control lane and exact reply target.
+- `Lifecycle ownership`: Connect intent and resume scheduling belong to the existing session lifecycle domain; compact failure formatting belongs to status. Transport authority, durable bindings and queue custody keep their existing owners, without introducing a separate connection domain.
+
 ## 0.51.5: Follower Thread new-session hotfix
 
 - `Follower Thread /new`: Telegram `/new` now starts a new session in a follower's Pi process and preserves its Thread binding. The leader publishes and later claims the durable replacement intent through capability-gated, generation-fenced bus requests, validating its own live registration and Workspace binding before accepting the follower's request. Incompatible or stale leaders fail closed rather than silently switching sessions.

package/node_modules/@llblab/pi-telegram/README.md

@@ -57,7 +57,7 @@ Paste the bot token. If `~/.pi/agent/telegram.json` already contains a saved tok
 /telegram-connect
 ```
 
-The connected Pi instance owns Telegram polling. Use `/telegram-connect <profile>` to activate a named profile. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the `default` profile keeps unsuffixed runtime paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers. Reopening or resuming the same Pi session restores its remembered Thread at session startup; a distinct session in the same directory has its own binding and still requires explicit `/telegram-connect` when no remembered binding exists.
+The connected Pi instance owns Telegram polling. Use `/telegram-connect <profile>` to activate a named profile. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the `default` profile keeps unsuffixed runtime paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers. Reopening or resuming the same Pi session restores its remembered Thread at session startup. If `/resume` immediately follows `/telegram-connect`, or the bridge is already connected, connection intent follows the switch: the destination restores its own Thread/slot or receives a new binding, never the source session's Thread. Otherwise, a distinct unbound session still requires explicit `/telegram-connect`.
 
 After an unclean computer shutdown, `/telegram-connect` detects truncated or structurally invalid temporary ownership/routing files, quarantines only the damaged files under `tmp/telegram/recovery/`, and retries once. A journal snapshot removed by older broad temp cleanup is rebuilt when its complete segment history proves an empty result, while a revisionless snapshot is repaired from the first surviving segment's exact predecessor when the reconstructed tail validates. Otherwise the snapshot and segments are quarantined as recovery evidence, a fresh journal is published, and startup continues with an informational diagnostic instead of requiring manual JSON repair. Unsupported journal versions block recovery without rewriting or quarantining the retained files; use a compatible runtime rather than deleting journals. Saved `telegram.json` configuration and runtime diagnostics remain intact. Recovery never replaces a verifiable live owner; if safe automatic recovery cannot complete, the command gives one explicit Pi-restart instruction instead of requiring deletion of the whole `tmp/` directory.
 

package/node_modules/@llblab/pi-telegram/dist/lib/bindings.d.ts

@@ -194,9 +194,12 @@ interface TelegramCommandsAndToolsBindingDeps {
     canSendDirect: () => boolean;
     setGenerativeAppLiveSurfaceRuntime?: (runtime: GenerativeApps.GenerativeAppLiveSurfaceRuntime<GenerativeApps.TelegramBindLiveHandle> | undefined) => void;
     updateStatus: TelegramBridgeStatusUpdater;
+    isContextCurrent: (ctx: Pi.ExtensionContext) => boolean;
+    getSessionGeneration: () => number;
+    connectionIntent: NonNullable<Commands.TelegramBridgeCommandRegistrationDeps["connectionIntent"]>;
     recordRuntimeEvent: TelegramRuntimeEventRecorder;
 }
-export declare function registerTelegramCommandsAndTools({ pi, agentDir, configStore, persistConfig, setup, activeTurnRuntime, lockedPollingRuntime, stopPolling, recoverPollingStart, getDisconnectThreadName, onTransportChanged, getStatusLines, buttonActionStore, sendMarkdownReply, sendChannelMarkdownMessage, sendChannelMediaMessage, listChannelPosts, mutateChannelPost, callMultipart, getDefaultChatId, getDefaultTarget, resolveAgentTarget, routeAgentMessage, canSendDirect, setGenerativeAppLiveSurfaceRuntime, recordRuntimeEvent, updateStatus, }: TelegramCommandsAndToolsBindingDeps): void;
+export declare function registerTelegramCommandsAndTools({ pi, agentDir, configStore, persistConfig, setup, activeTurnRuntime, lockedPollingRuntime, stopPolling, recoverPollingStart, getDisconnectThreadName, onTransportChanged, getStatusLines, buttonActionStore, sendMarkdownReply, sendChannelMarkdownMessage, sendChannelMediaMessage, listChannelPosts, mutateChannelPost, callMultipart, getDefaultChatId, getDefaultTarget, resolveAgentTarget, routeAgentMessage, canSendDirect, setGenerativeAppLiveSurfaceRuntime, recordRuntimeEvent, updateStatus, isContextCurrent, getSessionGeneration, connectionIntent, }: TelegramCommandsAndToolsBindingDeps): void;
 interface TelegramLifecycleBindingDeps {
     pi: Pi.ExtensionAPI;
     publicationRuntime: TelegramBridgePublicationRuntime;

package/node_modules/@llblab/pi-telegram/dist/lib/bindings.js

@@ -323,7 +323,7 @@ export function createTelegramActivityBindingRuntime(deps) {
         },
     };
 }
-export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, persistConfig, setup, activeTurnRuntime, lockedPollingRuntime, stopPolling, recoverPollingStart, getDisconnectThreadName, onTransportChanged, getStatusLines, buttonActionStore, sendMarkdownReply, sendChannelMarkdownMessage, sendChannelMediaMessage, listChannelPosts, mutateChannelPost, callMultipart, getDefaultChatId, getDefaultTarget, resolveAgentTarget, routeAgentMessage, canSendDirect, setGenerativeAppLiveSurfaceRuntime, recordRuntimeEvent, updateStatus, }) {
+export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, persistConfig, setup, activeTurnRuntime, lockedPollingRuntime, stopPolling, recoverPollingStart, getDisconnectThreadName, onTransportChanged, getStatusLines, buttonActionStore, sendMarkdownReply, sendChannelMarkdownMessage, sendChannelMediaMessage, listChannelPosts, mutateChannelPost, callMultipart, getDefaultChatId, getDefaultTarget, resolveAgentTarget, routeAgentMessage, canSendDirect, setGenerativeAppLiveSurfaceRuntime, recordRuntimeEvent, updateStatus, isContextCurrent, getSessionGeneration, connectionIntent, }) {
     GenerativeApps.registerTelegramBindTool(pi, {
         agentDir,
         getActiveProfileName: configStore.getActiveProfileName,
@@ -452,33 +452,35 @@ export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, pe
         reloadConfig: configStore.load,
         hasBotToken: configStore.hasBotToken,
         getBotTokenDiagnostic: configStore.getBotTokenDiagnostic,
-        startPolling: async (ctx, options) => {
-            try {
-                return await lockedPollingRuntime.start(ctx, options);
-            }
-            catch (error) {
-                recordRuntimeEvent("recovery", error, { phase: "polling-start" });
-                throw error;
-            }
-        },
+        startPolling: lockedPollingRuntime.start,
+        recordConnectionEvent: (error, phase) => recordRuntimeEvent("connection", error, { phase }),
         stopPolling: stopPolling ?? lockedPollingRuntime.stop,
         recoverPollingStart,
         getDisconnectThreadName,
         queueAgentConnectionContext,
         updateStatus,
+        isContextCurrent,
+        getSessionGeneration,
+        connectionIntent,
         getProfileNames: () => Config.getTelegramProfileNames(configStore.getStoredConfig()),
-        activateDefaultProfileConfig: async () => {
+        activateDefaultProfileConfig: async (_ctx, isCurrent) => {
             const previousProfileName = configStore.getActiveProfileName();
             await configStore.load();
+            if (!isCurrent())
+                return;
             if (previousProfileName) {
                 await (stopPolling ?? lockedPollingRuntime.stop)();
+                if (!isCurrent())
+                    return;
             }
             configStore.activateProfile(undefined);
             await onTransportChanged?.();
         },
-        activateProfileConfig: async (_ctx, profileName) => {
+        activateProfileConfig: async (_ctx, profileName, isCurrent) => {
             const previousProfileName = configStore.getActiveProfileName();
             await configStore.load();
+            if (!isCurrent())
+                return false;
             if (!Config.isValidTelegramProfileName(profileName))
                 return false;
             const storedConfig = configStore.getStoredConfig();
@@ -486,6 +488,8 @@ export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, pe
                 return false;
             if (previousProfileName !== profileName) {
                 await (stopPolling ?? lockedPollingRuntime.stop)();
+                if (!isCurrent())
+                    return false;
             }
             if (!configStore.activateProfile(profileName))
                 return false;