@llblab/pi-kit 0.22.1 → 0.23.0

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

@@ -1,8 +1,10 @@
 // Domain: exact file-cohort publication, current-only recovery, and cooperating worktree exclusion.
 // Excludes: temporal algebra, Pi lifecycle, Git objects/remotes, and backend fallback policy.
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
-import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 import {
 	assertOwnedFileUpdates, captureTemporalFileBases, parseScopeProvenance, parseScopeStream, restoreDurableFileBases,
 	serializeScopeMetadata, sessionRuntimePaths, temporalScopePaths, temporalStateFileUpdates, writeOwnedFileUpdates,
@@ -24,7 +26,7 @@ export function assertStorageDirectory(path: string): void {
 	const parent = dirname(root);
 	if (parent !== root) assertStorageDirectory(parent);
 	const stat = lstatSync(root, { throwIfNoEntry: false });
-	if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error(`State Flow repository path is not a regular directory: ${root}`);
+	if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error(`State Flow repository path is not a regular directory: ${JSON.stringify(root)}`);
 }
 
 /** Explicit creation only; existing bytes and unrelated files are never adopted or rewritten here. */
@@ -37,16 +39,23 @@ const PUBLICATION_LOCK_WAIT_MS = 2_000;
 const PUBLICATION_LOCK_POLL_MS = 25;
 const publicationLockWait = new Int32Array(new SharedArrayBuffer(4));
 
-function liveForeignLockOwner(path: string): boolean {
+function publicationLockOwner(path: string, allowCurrentProcess: boolean): "live" | "pending" | "absent" | "unavailable" {
 	let owner: string;
-	try { owner = readFileSync(path, "utf8").trim(); }
-	catch { return true; }
-	if (owner.length === 0) return true;
-	if (!/^[1-9]\d*$/.test(owner)) return false;
+	try {
+		const stat = lstatSync(path, { throwIfNoEntry: false });
+		if (!stat) return "absent";
+		if (!stat.isFile() || stat.isSymbolicLink()) return "unavailable";
+		owner = readFileSync(path, { encoding: "utf8", flag: constants.O_RDONLY | constants.O_NOFOLLOW }).trim();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return "absent";
+		throw error;
+	}
+	if (owner.length === 0) return "pending";
+	if (!/^[1-9]\d*$/.test(owner)) return "unavailable";
 	const pid = Number(owner);
-	if (!Number.isSafeInteger(pid) || pid === process.pid) return false;
-	try { process.kill(pid, 0); return true; }
-	catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; }
+	if (!Number.isSafeInteger(pid) || (pid === process.pid && !allowCurrentProcess)) return "unavailable";
+	try { process.kill(pid, 0); return "live"; }
+	catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM" ? "live" : "unavailable"; }
 }
 
 /** Wait only for a cooperating live owner; interrupted or malformed locks remain explicit recovery errors. */
@@ -55,7 +64,11 @@ export function acquirePublicationLock(path: string, unavailable: (cause: unknow
 	while (true) {
 		try { return openSync(path, "wx", 0o600); }
 		catch (error) {
-			if ((error as NodeJS.ErrnoException).code !== "EEXIST" || !liveForeignLockOwner(path) || Date.now() >= deadline) throw unavailable(error);
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw unavailable(error);
+			let owner: ReturnType<typeof publicationLockOwner>;
+			try { owner = publicationLockOwner(path, false); }
+			catch (cause) { throw unavailable(cause); }
+			if (owner === "unavailable" || Date.now() >= deadline) throw unavailable(error);
 			Atomics.wait(publicationLockWait, 0, 0, Math.min(PUBLICATION_LOCK_POLL_MS, deadline - Date.now()));
 		}
 	}
@@ -67,7 +80,7 @@ export function withStoragePublicationLock<T>(repositoryRoot: string, action: (r
 	assertStorageDirectory(root);
 	const path = resolve(root, ".state-flow-publication.lock");
 	const descriptor = acquirePublicationLock(path, (cause) => new RevisionUnavailableError(
-		`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause },
+		`State Flow publication lock is unavailable at ${JSON.stringify(path)}`, { cause },
 	));
 	try {
 		writeFileSync(descriptor, `${process.pid}\n`);
@@ -78,6 +91,103 @@ export function withStoragePublicationLock<T>(repositoryRoot: string, action: (r
 	}
 }
 
+export interface StorageTransaction {
+	readonly capture: typeof captureTemporalFileBase;
+	readonly publish: typeof publishTemporalStateToFiles;
+}
+
+export class PublicationBusyError extends Error {
+	constructor(path: string) { super(`State Flow publication lock is busy at ${JSON.stringify(path)}`); }
+}
+
+const storageLockContext = new AsyncLocalStorage<readonly { path: string; active: boolean }[]>();
+
+/** Await an exact file mutex; shared by canonical transactions and the independent Git backup owner. */
+export async function withFilePublicationLock<T>(
+	lockPath: string, action: () => T | Promise<T>, signal?: AbortSignal,
+	unavailable: (cause: unknown) => Error = (cause) => new RevisionUnavailableError(
+		`State Flow publication lock is unavailable at ${JSON.stringify(resolve(lockPath))}`, { cause },
+	), waitForLock = true,
+): Promise<T> {
+	const path = resolve(lockPath);
+	const inherited = storageLockContext.getStore();
+	if (inherited?.some((held) => held.active && held.path === path)) throw new Error(`Recursive State Flow publication lock at ${JSON.stringify(path)}`);
+	let descriptor: number;
+	let pendingSince: number | undefined;
+	while (true) {
+		signal?.throwIfAborted();
+		assertStorageDirectory(dirname(path));
+		try { descriptor = openSync(path, "wx", 0o600); break; }
+		catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw unavailable(error);
+			let owner: ReturnType<typeof publicationLockOwner>;
+			try { owner = publicationLockOwner(path, true); }
+			catch (cause) { throw unavailable(cause); }
+			if (owner === "unavailable") throw unavailable(error);
+			if (!waitForLock) throw new PublicationBusyError(path);
+			// An empty file may be between exclusive creation and PID publication, but not forever.
+			if (owner === "pending") pendingSince ??= performance.now();
+			else pendingSince = undefined;
+			if (pendingSince !== undefined && performance.now() - pendingSince >= PUBLICATION_LOCK_WAIT_MS) throw unavailable(error);
+		}
+		await delay(PUBLICATION_LOCK_POLL_MS, undefined, { signal });
+	}
+	let identity: ReturnType<typeof fstatSync> | undefined;
+	const held = { path, active: true };
+	let failed: { error: unknown } | undefined;
+	try {
+		identity = fstatSync(descriptor);
+		writeFileSync(descriptor, `${process.pid}\n`);
+		signal?.throwIfAborted();
+		return await storageLockContext.run([...(inherited?.filter((owner) => owner.active) ?? []), held], action);
+	} catch (error) {
+		failed = { error };
+		throw error;
+	} finally {
+		held.active = false;
+		try {
+			const current = lstatSync(path, { throwIfNoEntry: false });
+			if (!identity || !current?.isFile() || current.dev !== identity.dev || current.ino !== identity.ino
+				|| readFileSync(path, { encoding: "utf8", flag: constants.O_RDONLY | constants.O_NOFOLLOW }) !== `${process.pid}\n`) {
+				throw new Error(`State Flow publication lock changed during transaction at ${JSON.stringify(path)}; current owner preserved`);
+			}
+			rmSync(path);
+		} catch (error) {
+			if (failed) throw new AggregateError([failed.error, error], "State Flow storage transaction and lock release failed");
+			throw error;
+		} finally {
+			closeSync(descriptor);
+		}
+	}
+}
+
+/** Await store-wide exclusion, then capture/apply/publish through callback-scoped operations. */
+export async function withStorageTransaction<T>(
+	repositoryRoot: string, action: (transaction: StorageTransaction) => T | Promise<T>, signal?: AbortSignal, waitForLock = true,
+): Promise<T> {
+	const root = resolve(repositoryRoot);
+	return withFilePublicationLock(resolve(root, ".state-flow-publication.lock"), async () => {
+		let active = true;
+		const guard = (requestedRoot: string): void => {
+			if (!active) throw new Error("State Flow storage transaction has ended");
+			if (resolve(requestedRoot) !== root) throw new Error("State Flow storage transaction belongs to a different store");
+			signal?.throwIfAborted();
+		};
+		const transaction = Object.freeze<StorageTransaction>({
+			capture: (cwd, sessionId, requestedRoot, sessionKey = sessionId) => {
+				guard(requestedRoot);
+				return { files: captureTemporalFileBases(cwd, sessionId, root, sessionKey) };
+			},
+			publish: (cwd, sessionId, view, scopes, base, requestedRoot, runtime, sessionKey, provenance, runtimeOnly) => {
+				guard(requestedRoot);
+				return publishLockedTemporalStateToFiles(cwd, sessionId, view, scopes, base, root, runtime, sessionKey, provenance, runtimeOnly);
+			},
+		});
+		try { return await action(transaction); }
+		finally { active = false; }
+	}, signal, undefined, waitForLock);
+}
+
 export function assertTemporalFileBase(expected: TemporalFileBase, current: TemporalFileBase): void {
 	if (expected.files.length !== current.files.length || current.files.some((file, index) => {
 		const previous = expected.files[index]!;
@@ -194,16 +304,25 @@ export function publishTemporalStateToFiles(
 	base: TemporalFileBase, root: string, runtime: SessionRuntime, sessionKey = sessionId,
 	provenance?: Readonly<Record<StateScope, ArtifactProvenanceRegistry>>, runtimeOnly = false,
 ): { base: TemporalFileBase; revision: FileRevision; changed: boolean } {
-	return withStoragePublicationLock(root, (locked) => {
-		const current = { files: captureTemporalFileBases(cwd, sessionId, locked, sessionKey) };
-		assertTemporalFileBase(base, current);
-		const { updates } = planTemporalPublication(cwd, sessionId, view, scopes, current, locked, runtime, runtimeOnly, sessionKey, provenance);
-		const next = { files: temporalFileReceipts(current, updates) };
-		decodeFileCohort(cwd, sessionId, locked, next, sessionKey);
-		const revision = fileRevision(next, locked);
-		publishFileUpdates(current.files, updates, locked);
-		return { base: next, revision, changed: updates.length > 0 };
-	});
+	return withStoragePublicationLock(root, (locked) => publishLockedTemporalStateToFiles(
+		cwd, sessionId, view, scopes, base, locked, runtime, sessionKey, provenance, runtimeOnly,
+	));
+}
+
+/** Shared publication owner; callers must hold the matching store lock for the complete cohort. */
+function publishLockedTemporalStateToFiles(
+	cwd: string, sessionId: string, view: TemporalState, scopes: readonly StateScope[],
+	base: TemporalFileBase, root: string, runtime: SessionRuntime, sessionKey = sessionId,
+	provenance?: Readonly<Record<StateScope, ArtifactProvenanceRegistry>>, runtimeOnly = false,
+): { base: TemporalFileBase; revision: FileRevision; changed: boolean } {
+	const current = { files: captureTemporalFileBases(cwd, sessionId, root, sessionKey) };
+	assertTemporalFileBase(base, current);
+	const { updates } = planTemporalPublication(cwd, sessionId, view, scopes, current, root, runtime, runtimeOnly, sessionKey, provenance);
+	const next = { files: temporalFileReceipts(current, updates) };
+	decodeFileCohort(cwd, sessionId, root, next, sessionKey);
+	const revision = fileRevision(next, root);
+	publishFileUpdates(current.files, updates, root);
+	return { base: next, revision, changed: updates.length > 0 };
 }
 
 function publishFileUpdates(bases: readonly DurableFileBase[], updates: readonly OwnedFileUpdate[], root: string): void {

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

@@ -3,6 +3,7 @@
 // This is a leaf adapter. Core semantics, storage, and inference never depend on it; when
 // pi-telegram is absent or its registry is not ready, registration fails open and retries.
 
+import { conciseDiagnostic, diagnosticText } from "./protocol.ts";
 import { formatScopeRevisionVector } from "./status.ts";
 import type { ScopeRevisions } from "./temporal.ts";
 
@@ -93,6 +94,15 @@ export type StateFlowTelegramLoader = () => Promise<StateFlowTelegramModules>;
 export interface StateFlowTelegramControlResult {
 	ok: boolean;
 	message: string;
+	/** A completed control can lose its presentation authority after a mode or selection change. */
+	signal?: AbortSignal;
+}
+
+export interface StateFlowTelegramInspection {
+	state: StateFlowTelegramState;
+	revisions: ScopeRevisions;
+	/** A selection can revoke a completed observation before the adapter presents it. */
+	signal?: AbortSignal;
 }
 
 export interface StateFlowTelegramPort {
@@ -107,6 +117,12 @@ export interface StateFlowTelegramPort {
 	cancelStart(): void;
 }
 
+export interface StateFlowTelegramInspectionPort extends Omit<StateFlowTelegramPort, "state" | "revisions" | "start" | "stop"> {
+	inspect(scope: StateFlowTelegramScope): StateFlowTelegramInspection | Promise<StateFlowTelegramInspection>;
+	start(): StateFlowTelegramControlResult | Promise<StateFlowTelegramControlResult>;
+	stop(): StateFlowTelegramControlResult | Promise<StateFlowTelegramControlResult>;
+}
+
 export interface StateFlowTelegramAdapter {
 	ensure(): Promise<boolean>;
 	dispose(): void;
@@ -228,7 +244,8 @@ function isStateFlowTelegramScope(value: string): value is StateFlowTelegramScop
 	return value === "global" || value === "cwd" || value === "session" || value === "effective";
 }
 
-function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
+function buildStateFlowTelegramSection(port: StateFlowTelegramPort | StateFlowTelegramInspectionPort, isActive: () => boolean) {
+	let interaction = 0;
 	return {
 		id: STATE_FLOW_TELEGRAM_ID,
 		label: "🌀 State Flow",
@@ -238,7 +255,9 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
 		handleCallback: async (ctx: StateFlowTelegramCallbackContext) => {
 			// cancel/refresh remain routable for keyboards sent by earlier versions.
 			if (ctx.action !== "start" && ctx.action !== "stop" && ctx.action !== "cancel" && ctx.action !== "refresh" && ctx.action !== "show-state" && ctx.action !== "inspect" && ctx.action !== "back") return "pass" as const;
+			const request = ++interaction;
 			let notice: string | undefined;
+			let acknowledged = false;
 			try {
 				if (ctx.action === "show-state") {
 					await ctx.answerCallback();
@@ -247,30 +266,52 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
 				}
 				if (ctx.action === "inspect") {
 					if (!isStateFlowTelegramScope(ctx.payload)) throw new Error("Unknown State Flow scope");
-					const state = port.state(ctx.payload);
-					const live = port.snapshot();
-					const revisions = port.revisions?.() ?? live.revisions ?? { global: live.step, cwd: live.step, session: live.step };
-					await ctx.openRich(renderStateFlowRichState(ctx.payload, revisions, state));
-					await ctx.answerCallback();
+					let observation: StateFlowTelegramInspection;
+					if ("inspect" in port) {
+						await ctx.answerCallback("Reading State Flow memory");
+						acknowledged = true;
+						observation = await port.inspect(ctx.payload);
+					} else {
+						const state = port.state(ctx.payload);
+						const live = port.snapshot();
+						observation = { state, revisions: port.revisions?.() ?? live.revisions ?? { global: live.step, cwd: live.step, session: live.step } };
+					}
+					observation.signal?.throwIfAborted();
+					if (request !== interaction || !isActive()) return "handled" as const;
+					await ctx.openRich(renderStateFlowRichState(ctx.payload, observation.revisions, observation.state));
+					if (!acknowledged) await ctx.answerCallback();
 					return "handled" as const;
 				}
-				if (ctx.action === "start") {
-					if (port.canStartNow()) notice = port.start().message;
-					else {
-						port.deferStart();
-						notice = "State Flow will start after the current turn";
-					}
-				} else if (ctx.action === "stop") {
-					notice = port.stop().message;
+				const action = ctx.action === "stop" || (ctx.action === "start" && port.canStartNow()) ? ctx.action : undefined;
+				if (action) {
+					if ("inspect" in port) {
+						acknowledged = true;
+						// Start the control immediately and acknowledge in parallel; neither promise can reject unobserved.
+						const [, result] = await Promise.all([
+							ctx.answerCallback(action === "stop" ? "Stopping State Flow" : "Starting State Flow"),
+							Promise.resolve().then(() => port[action]()),
+						]);
+						if (result.signal?.aborted) return "handled" as const;
+						notice = result.message;
+					} else notice = port[action]().message;
+				} else if (ctx.action === "start") {
+					port.deferStart();
+					notice = "State Flow will start after the current turn";
 				} else if (ctx.action === "cancel") {
 					port.cancelStart();
 					notice = "Pending start cancelled";
 				}
 			} catch (error) {
-				notice = error instanceof Error ? error.message : String(error);
+				notice = diagnosticText(error);
 			}
-			await ctx.answerCallback(notice);
-			await ctx.edit(buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action)));
+			if (request !== interaction || !isActive()) return "handled" as const;
+			const summary = notice === undefined ? undefined : conciseDiagnostic(notice, 200);
+			const view = buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action));
+			if (acknowledged && summary !== undefined) {
+				// Callback queries can expire during storage waits; retain errors in the existing menu instead.
+				view.text += `\n\n${summary.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")}`;
+			} else if (!acknowledged) await ctx.answerCallback(summary);
+			await ctx.edit(view);
 			return "handled" as const;
 		},
 	};
@@ -302,7 +343,7 @@ export async function loadStateFlowTelegramModules(): Promise<StateFlowTelegramM
 }
 
 export function createStateFlowTelegramAdapter(options: {
-	port: StateFlowTelegramPort;
+	port: StateFlowTelegramPort | StateFlowTelegramInspectionPort;
 	load?: StateFlowTelegramLoader;
 }): StateFlowTelegramAdapter {
 	const load = options.load ?? loadStateFlowTelegramModules;
@@ -323,7 +364,7 @@ export function createStateFlowTelegramAdapter(options: {
 		if (epoch !== generation) return false;
 		if (!sectionRegistered && modules.sections) {
 			try {
-				const dispose = modules.sections.registerTelegramSection(buildStateFlowTelegramSection(options.port));
+				const dispose = modules.sections.registerTelegramSection(buildStateFlowTelegramSection(options.port, () => epoch === generation));
 				if (epoch === generation) {
 					disposers.push(dispose);
 					sectionRegistered = true;

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

@@ -68,13 +68,13 @@ function validateSkillCompilerOutput(scope: StateScope, path: string, output: un
 	const problems: string[] = [];
 	if (!isObject(output)) problems.push("artifact entry is missing");
 	else {
-		if (typeof output.description !== "string" || output.description.trim().length === 0) problems.push("description must be a non-empty string");
+		if (typeof output.description !== "string" || output.description.trim().length === 0) problems.push("description must be non-empty");
 		if (output.kind !== "skill") problems.push('kind must be "skill"');
-		if (!isObject(output.compilation) || Object.keys(output.compilation).length === 0) problems.push("compilation must be a non-empty object");
+		if (!isObject(output.compilation) || Object.keys(output.compilation).length === 0) problems.push("compilation object must be non-empty");
 	}
 	if (problems.length === 0) return;
 	const target = `${scope}.artifacts[${JSON.stringify(path)}]`;
-	throw new Error(`Skill compiler output at ${target} is invalid: ${problems.join("; ")}. Example: {${JSON.stringify(scope)}:{"artifacts":{${JSON.stringify(path)}:{"description":"What this Skill provides","kind":"skill","compilation":{"rules":["Operational rule retained from the Skill"]}}}}}`);
+	throw new Error(`Invalid Skill at ${target}: ${problems.join("; ")}`);
 }
 
 function validateSkillCompilerTargets(
@@ -107,7 +107,7 @@ function compileReadSkills(
 		const output = patch.artifacts[read.path];
 		validateSkillCompilerOutput(scope, read.path, output);
 		const compiled = compileArtifact({
-			source: { path: read.path, hash: read.hash },
+			source: { path: read.path, scope, hash: read.hash },
 			compiler: SKILL_ARTIFACT_COMPILER,
 			output: { ...structuredClone(output), kind: "skill" } as ArtifactCompilerOutput,
 		});
@@ -125,11 +125,11 @@ function compileReadSkills(
 	}
 }
 
-function validateMaterializedTransition(nextState: StateDocument): void {
+function validateMaterializedTransition(nextState: StateDocument, scope: StateScope): void {
 	if (containsNull(nextState)) {
 		throw new Error("Materialized state cannot contain null; use null only as an object-key deletion marker");
 	}
-	validateArtifactRegistry(nextState.artifacts);
+	validateArtifactRegistry(nextState.artifacts, `${scope}.artifacts`);
 	if (Object.hasOwn(nextState.contract, "compiled_skills")) {
 		throw new Error("contract.compiled_skills is retired; Skill compilations belong only in source-addressed artifacts");
 	}
@@ -153,7 +153,7 @@ function validateScopePatch(scope: unknown, patch: unknown): asserts patch is Sc
 	if (Object.hasOwn(patch, "lazy") && !isObject(patch.lazy)) {
 		throw new Error("Scoped State Flow patch field lazy must be a JSON object");
 	}
-	if (isObject(patch.artifacts)) validateModelArtifactPatch(patch.artifacts);
+	if (isObject(patch.artifacts)) validateModelArtifactPatch(patch.artifacts, `${scope}.artifacts`);
 }
 
 function completePatch(patch: ScopePatch, response: string): StatePatch {
@@ -209,7 +209,7 @@ function stageScopedSemanticTransition(
 			provenanceUpdates[scope],
 		);
 		compileReadSkills(scope, nextState, { artifacts: authored.artifacts ?? {} }, skillReads.filter((read) => read.scope === scope), provenanceUpdates[scope]);
-		validateMaterializedTransition(nextState);
+		validateMaterializedTransition(nextState, scope);
 		nextStates[scope] = nextState;
 	}
 	return {

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

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
   "keywords": [

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

@@ -48,7 +48,9 @@ Unscoped paths use effective state. `cwd[1].working` reads the preceding causal
 
 ## Write
 
-Call `patch_state` alone per assistant response; await acceptance before dependent work. Supply one or more of `global`, `cwd`, and `session`; supplied scopes commit atomically. Omit unchanged scopes.
+Call `patch_state` alone per assistant response; await acceptance before dependent work. Supply one or more of `global`, `cwd`, and `session`; supplied scopes commit atomically. Default to Session for current work, CWD for reusable project knowledge, and Global for established cross-project knowledge. Omit unchanged scopes.
+
+The runtime waits cancelably for publication ownership, then applies authored Global/CWD operations to current canonical values. Untouched fields survive; overlapping targets follow successful acceptance order. Correct repeats succeed as `State already current.` without another semantic revision. Do not repeat external actions during a memory wait, or rebuild an entire scope from an older snapshot. Session ownership/history fences remain private, not a universal merge.
 
 Semantic planes `intents`, `contract`, `working`, `artifacts`, and the required `lazy` root are objects; nested lazy values may contain ordinary JSON without stored nulls. 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.
 

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

@@ -47,6 +47,7 @@ Keep each fact in one authoritative layer:
 - `/skills/generated-control-surface`: Optional state-derived, late-bound interface over truthful domain evidence, capabilities, workflows, and choices; it remains renderer-neutral, independent from the bridge skill, and owns no parallel state.
 - `/skills/generative-apps`: Agent operating contract for compiling stable repeated Telegram interaction into deterministic standalone applications or bounded view/controller adapters whose buttons bypass model inference.
 - `/skills/show-me`: Portable visual-explanation protocol with Telegram-aware phone-width Markdown and self-contained browser artifact guidance; it owns explanation shape and evidence honesty, not bridge transport.
+- `Skill discovery`: Compiled npm/git packages expose bundled Skills only through `pi.skills`, preserving Pi package filters. A raw TypeScript extension checkout may contribute the source Skill root through `resources_discover`; compiled runtime and source runtime must never both own discovery.
 - `/.agents/skills/telegram-bot`: Bot API lookup guidance and vendored `api.md`; keep the reference intact.
 - `/.agents/skills/domain-dag`: Repository architecture guidance and validator.
 
@@ -82,7 +83,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - Admission is journal-first: validate and persist the complete `getUpdates` response before one monotonic offset commit, then signal an independent worker without awaiting semantic execution. Missing cursor with a non-empty journal, malformed/foreign authority, or capacity exhaustion fails closed. “Durable” means process-crash recovery after atomic rename, not unflushed host/kernel/filesystem/device/power-loss survival.
 - Storage cutovers must reconcile actual consumer locations before correcting path adapters. Never normalize a relative historical reference into new authority or treat equal reference strings / empty canonical storage as source completeness. Exact-path preflight is lexical only; physical identity, historical coverage, writer closure and migration remain separate proofs.
 - Workspace mutations acquire cross-process admission before their shared process-local gate and hold it through asynchronous API work and durable settlement. Topic lifecycle, complete unbound/reroute target handling, manual disconnect, and session-restart cleanup use profile-wide scope; either retained retirement-fence phase rejects them before state access. Cleanup scope spans intent publication, target mutation, persistence, and transport release. Detached reconciliation that mutates Thread state must reacquire fresh profile admission through the same gate; it cannot inherit a caller lease that ended before its timer runs. A live operation ID has one process-local caller: concurrent reuse is rejected before lease acquisition, while retry after the caller exits may resume exact durable authority.
-- Workspace retirement is capacity-pressure-only. Elapsed time and heartbeat silence never trigger deletion; only complete `A`–`Z` exhaustion may propose the oldest continuously proven inactive, fully unprotected binding. Exact deletion, durable retirement, and fence completion precede slot reuse. Authorized demand-driven rotation retries one failed fresh allocation after retirement; restore-only follower startup never evicts. Release ordinary registration/provisioning leases before acquiring the destructive fence, retain the shared mutation gate across retirement, and validate the exact permit immediately before one non-retried deletion. Persist an exact method/target-matched rejection before withdrawing its intent; release that fence only after durable withdrawal, retaining the binding. A later attempt requires fresh operation authority. Protection reads must never repair, quarantine, or reset journals. Non-destructive owner detachment must atomically retain one exact Workspace binding and its letter while removing only its uniquely matched owner record and stamping first inactivity; it never manufactures Thread-deletion evidence or clears accepted work. Retained prune observations are bounded, non-routing and registration/profile/epoch/runtime-fenced. One unfinished preservation operation retains its admission identity across fresh-PID-proof retries; it can never become deletion authority. Leader quit requires completed delivery/polling/worker teardown under the captured session generation, profile and epoch; reload/new/resume/fork never establish inactivity. Unknown deletion outcomes retain their fence; only confirmed durable completion permits reuse.
+- Workspace retirement is capacity-pressure-only. Elapsed time and heartbeat silence never trigger deletion; only complete `A`–`Z` exhaustion may propose the oldest continuously proven inactive, fully unprotected binding. Exact deletion, durable retirement, and fence completion precede slot reuse. Authorized demand-driven rotation retries one failed fresh allocation after retirement; restore-only follower startup never evicts. Release ordinary registration/provisioning leases before acquiring the destructive fence, retain the shared mutation gate across retirement, and validate the exact permit immediately before one non-retried deletion. Persist an exact method/target-matched rejection before withdrawing its intent; release that fence only after durable withdrawal, retaining the binding. A later attempt requires fresh operation authority. Protection reads must never repair, quarantine, or reset journals. Non-destructive owner detachment must atomically retain one exact Workspace binding and its letter while removing only its uniquely matched owner record and stamping first inactivity; it never manufactures Thread-deletion evidence or clears accepted work. During authenticated follower registration, the exact Workspace claim owns the letter: a mismatched retained target record is repaired to that claim before binding commit, while any unrelated binding that owns the stale letter remains untouched. Retained prune observations are bounded, non-routing and registration/profile/epoch/runtime-fenced. One unfinished preservation operation retains its admission identity across fresh-PID-proof retries; it can never become deletion authority. Leader quit requires completed delivery/polling/worker teardown under the captured session generation, profile and epoch; reload/new/resume/fork never establish inactivity. Unknown deletion outcomes retain their fence; only confirmed durable completion permits reuse.
 - Foreign forwarding settles as `accepted`, `retryable`, or `terminal-rejected`. Only an authenticated acknowledgement carrying the expected `deliveryId` and `sourceUpdateId` releases leader journal authority. Negative, missing, stale, mismatched, or capacity-failed settlement remains durable; callback error answers are side effects only.
 - A forwarding delivery id is stable across registration replacement and derives from envelope kind, source `update_id`, and stable recipient binding. Runtime instance and registration generation remain separate attempt fences. Persisted message ownership carries the stable binding so replay can rebind only to its current authenticated registration.
 - A queued receipt persists its acquiring runtime instance, OS pid/process-birth identity, session generation, acquisition id, and acquisition time. Only exact authority may settle or discard it. Cached presence is not current execution proof: prepared custody must revalidate the exact queued owner/group without recovery and refuse offers or uncertain reads. Completion requires an exact removal acknowledgement, never merely `!ready`; a retained acknowledgement permits local cleanup only, not replay. Same-process session replacement may reconstruct the claim and the original process may settle after transport ownership moves; a foreign process may neither replay nor settle it through generic removal or a copied acquisition id.
@@ -151,7 +152,7 @@ Before non-trivial work:
 While working:
 
 - Keep changes inside this repository; updating an installed Pi checkout is a separate operator action.
-- Rebuild the package with `npm run build` after edits. Pi loads `dist/pi-telegram/index.js`, so source-only changes are not live and `/reload` or process restart alone will reload stale compiled output.
+- Rebuild the package with `npm run build` after edits. Pi loads `dist/pi-telegram/index.js`, so source-only changes are not live and `/reload` or process restart alone will reload stale compiled output. Keep the committed `dist/` synchronized for Git installs; builds use a temporary candidate and rollback-safe swap, while `npm run build:check` rejects drift without rewriting the tree.
 - Read large artifacts search-first and range-bounded. For `CHANGELOG.md`, inspect only the current release section unless older history is relevant.
 - Keep successful validation output compact; inspect focused failure tails. Prefer focused tests/typecheck during iteration and broad validation at a stable gate.
 - Preserve unrelated work and do not commit, publish, tag, deploy, or perform external actions without explicit authorization.

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

@@ -4,6 +4,16 @@
 
 ## Unreleased
 
+## 0.51.4: Resolver-owned Skills and drift-safe Git installs
+
+- `Resolver-owned Skills`: Auto-discovered user/project checkouts now contribute source Skills even when Pi selects their compiled entrypoint, while manifest-loaded npm, Git, and Pi Kit packages retain `pi.skills` filters and package provenance. Resolver regressions cover checkout and filtered-package behavior; unsupported source manifest aliases are removed.
+- `Drift-safe distributive`: The compiled runtime and Skill tree are now committed for self-contained Git installs. Builds compile into a temporary candidate and use a rollback-safe swap; validation rejects stale committed output without silently repairing it.
+
+## 0.51.3: Follower recovery and filterable Skills
+
+- `Follower slot reconciliation`: Re-registration now treats the exact Workspace claim as canonical when a retained follower record carries a different slot. It repairs the record before binding commit, preserves the unrelated binding that owns the stale letter, and makes repeated registration idempotent instead of returning `Telegram Workspace binding claim changed.` forever.
+- `Filterable packaged Skills`: Compiled npm/git installations now leave bundled Skill discovery to the `pi.skills` manifest, so Pi package filters can select or disable individual Skills. A raw TypeScript checkout under Pi's `extensions` directory still contributes its source Skill root through `resources_discover`, preserving local-repository development without double-owning installed resources.
+
 ## 0.51.2: Model switching and typing continuity
 
 - `In-flight model switching`: Telegram model selection can again stop, switch, and continue any interruptible agent run in the current Pi session, including local/TUI work without an active Telegram prompt. The exact model-menu chat/Thread/message supplies fallback continuation ownership, active tools defer abort until settlement, and cancellation/session boundaries clear both selection and target state instead of returning a false busy response.

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

@@ -26,6 +26,8 @@ From git:
 pi install git:github.com/llblab/pi-telegram
 ```
 
+Installed npm/git packages expose bundled Skills through their `pi.skills` manifest, so Pi package filters and package provenance remain authoritative. A checkout auto-discovered directly under Pi's user or project `extensions` directory contributes its adjacent source Skills even when Pi selects the checkout's compiled entrypoint; the two discovery paths are mutually exclusive.
+
 The extension requires Pi `0.84.4` or newer, matching the package's peer dependencies. Its Activity API uses the public `agent_settled` lifecycle event to keep retries/continuations under one activity identity and release that identity only after the run fully settles.
 
 Pi is the primary and only officially supported host. Narrow host-neutral adapters preserve ordered prompt blocks and normalize synchronous or asynchronous legacy/generic settings services for Pi-compatible hosts, but this is best-effort compatibility rather than an OMP support guarantee. Alternate-host shims must still reproduce required Pi lifecycle semantics—especially `agent_settled`—and their maintainers own ongoing validation.
@@ -317,7 +319,7 @@ The docs index lives at [docs/README.md](./docs/README.md).
 
 ## Development
 
-Pi loads the compiled `dist/pi-telegram/index.js` entrypoint. After every project change, run `npm run build` before `/reload`, restart, or live verification; reloading source without rebuilding can leave the running extension on stale compiled code.
+Pi loads the compiled `dist/pi-telegram/index.js` entrypoint. The committed distributive also makes Git installs self-contained. After every project change, run `npm run build` before `/reload`, restart, or live verification; `npm run build:check` verifies source/artifact synchronization without rewriting it.
 
 ```bash
 npm run build

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

@@ -722,12 +722,30 @@ export function createTelegramBusFollowerTargetProvisioner(deps) {
                 : recoverableTarget && !pendingTargetRecovery
                     ? await recoverRequestedTarget()
                     : await provisionTarget();
+            const alignResultWithWorkspaceSlot = () => {
+                if (!workspaceIdentity ||
+                    result.record.slot === workspaceIdentity.slot)
+                    return;
+                deps.recordRuntimeEvent("bus", "Telegram follower record slot reconciled to its Workspace claim", {
+                    phase: "follower-register-slot-reconcile",
+                    instanceId: registration.instanceId,
+                    chatId: result.target.chatId,
+                    threadId: result.target.threadId,
+                    previousSlot: result.record.slot,
+                    slot: workspaceIdentity.slot,
+                });
+                result = {
+                    ...result,
+                    record: { ...result.record, slot: workspaceIdentity.slot },
+                };
+            };
+            alignResultWithWorkspaceSlot();
             const crossSessionReuse = !!reconnectRecord &&
                 reconnectRecord.instanceId !== registration.instanceId;
             if (reconnectRecord && !crossSessionReuse) {
                 const nowMs = getNowMs();
                 const refreshedRecord = deps.topicTargetStore.upsert({
-                    ...reconnectRecord,
+                    ...result.record,
                     instanceId: registration.instanceId,
                     updatedAtMs: nowMs,
                     lastSyncObservedAtMs: nowMs,
@@ -804,7 +822,7 @@ export function createTelegramBusFollowerTargetProvisioner(deps) {
                     else if (crossSessionReuse && reconnectRecord) {
                         const nowMs = getNowMs();
                         const transferredRecord = deps.topicTargetStore.upsert({
-                            ...reconnectRecord,
+                            ...result.record,
                             profileKey: followerProfileKey,
                             owner: followerOwner.kind === "manual-follower"
                                 ? followerOwner
@@ -861,6 +879,7 @@ export function createTelegramBusFollowerTargetProvisioner(deps) {
                 }
             }
             if (workspaceIdentity) {
+                alignResultWithWorkspaceSlot();
                 const workspaceCommit = Threads.commitTelegramWorkspaceProvisionBinding({
                     store: deps.topicTargetStore,
                     instanceId: registration.instanceId,
@@ -872,7 +891,7 @@ export function createTelegramBusFollowerTargetProvisioner(deps) {
                         ...(result.record.threadName
                             ? { threadName: result.record.threadName }
                             : {}),
-                        ...(result.record.slot ? { slot: result.record.slot } : {}),
+                        slot: workspaceIdentity.slot,
                         journalBindingKeys: [followerProfileKey],
                         journalBindingsComplete: true,
                         updatedAtMs: getNowMs(),

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

@@ -1,8 +1,14 @@
 /**
  * Bundled Telegram skill discovery
  * Zones: pi agent, telegram guidance
- * Owns source-checkout and installed-package skill path contribution
+ * Owns source-checkout skill contribution; installed packages use their manifest
  */
 import type { ExtensionAPI } from "./pi.ts";
+export declare function getTelegramExtensionPackageRoot(modulePath: string): string;
+export interface TelegramRawExtensionCheckoutOptions {
+    agentDir?: string;
+    cwd?: string;
+}
+export declare function isRawTelegramExtensionCheckout(modulePath: string, options?: TelegramRawExtensionCheckoutOptions): boolean;
 export declare const TELEGRAM_SKILLS_PATH: string;
-export declare function registerTelegramSkillDiscovery(pi: Pick<ExtensionAPI, "on">): void;
+export declare function registerTelegramSkillDiscovery(pi: Pick<ExtensionAPI, "on">, modulePath?: string, options?: TelegramRawExtensionCheckoutOptions): boolean;

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

@@ -1,12 +1,44 @@
 /**
  * Bundled Telegram skill discovery
  * Zones: pi agent, telegram guidance
- * Owns source-checkout and installed-package skill path contribution
+ * Owns source-checkout skill contribution; installed packages use their manifest
  */
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-export const TELEGRAM_SKILLS_PATH = fileURLToPath(new URL("../skills", import.meta.url));
-export function registerTelegramSkillDiscovery(pi) {
+import { resolveAgentDir } from "./paths.js";
+const TELEGRAM_SKILLS_MODULE_PATH = fileURLToPath(import.meta.url);
+export function getTelegramExtensionPackageRoot(modulePath) {
+    let current = dirname(modulePath);
+    while (true) {
+        if (existsSync(join(current, "package.json"))) {
+            const parent = dirname(current);
+            if (basename(current) === "dist" && existsSync(join(parent, "package.json"))) {
+                return parent;
+            }
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return dirname(modulePath);
+        current = parent;
+    }
+}
+export function isRawTelegramExtensionCheckout(modulePath, options = {}) {
+    const packageRoot = resolve(getTelegramExtensionPackageRoot(modulePath));
+    const agentDir = resolve(options.agentDir ?? resolveAgentDir());
+    const cwd = resolve(options.cwd ?? process.cwd());
+    return dirname(packageRoot) === join(agentDir, "extensions") ||
+        dirname(packageRoot) === join(cwd, ".pi", "extensions");
+}
+export const TELEGRAM_SKILLS_PATH = join(getTelegramExtensionPackageRoot(TELEGRAM_SKILLS_MODULE_PATH), "skills");
+export function registerTelegramSkillDiscovery(pi, modulePath = TELEGRAM_SKILLS_MODULE_PATH, options = {}) {
+    // Pi auto-discovers extension entrypoints but not their manifest Skills.
+    // Manifest-loaded packages own Skills and filters through `pi.skills`.
+    if (!isRawTelegramExtensionCheckout(modulePath, options))
+        return false;
     pi.on("resources_discover", () => ({
-        skillPaths: [TELEGRAM_SKILLS_PATH],
+        skillPaths: [join(getTelegramExtensionPackageRoot(modulePath), "skills")],
     }));
+    return true;
 }