@llblab/pi-kit 0.22.2 → 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

@@ -152,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,11 @@
 
 ## 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.

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

@@ -26,7 +26,7 @@ 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 can select individual Skills. A raw TypeScript checkout placed directly under Pi's `extensions` directory instead contributes its adjacent source Skills at runtime; the two discovery paths are mutually exclusive.
+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.
 
@@ -319,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/skills.d.ts

@@ -4,5 +4,11 @@
  * 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">, modulePath?: string): boolean;
+export declare function registerTelegramSkillDiscovery(pi: Pick<ExtensionAPI, "on">, modulePath?: string, options?: TelegramRawExtensionCheckoutOptions): boolean;

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

@@ -3,17 +3,42 @@
  * Zones: pi agent, telegram guidance
  * Owns source-checkout skill contribution; installed packages use their manifest
  */
-import { extname } from "node:path";
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveAgentDir } from "./paths.js";
 const TELEGRAM_SKILLS_MODULE_PATH = fileURLToPath(import.meta.url);
-export const TELEGRAM_SKILLS_PATH = fileURLToPath(new URL("../skills", import.meta.url));
-export function registerTelegramSkillDiscovery(pi, modulePath = TELEGRAM_SKILLS_MODULE_PATH) {
-    // A raw source extension has no package manifest owner. Compiled npm/git
-    // packages do, so contributing again would bypass their resource filters.
-    if (extname(modulePath) !== ".ts")
+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;
 }

package/node_modules/@llblab/pi-telegram/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.51.3",
+  "version": "0.51.4",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -31,12 +31,13 @@
     "test:verbose": "node --experimental-strip-types --test --test-reporter=spec tests/*.test.ts",
     "typecheck": "tsc --noEmit",
     "build": "node scripts/build-dist.mjs",
+    "build:check": "node scripts/build-dist.mjs --check",
     "prepack": "npm run build",
     "check": "node -e \"await import('./dist/pi-telegram/index.js'); console.log('pi-telegram: extension import ok')\"",
     "audit": "npm audit --omit=peer",
     "audit:host": "npm audit",
     "pack:check": "npm pack --dry-run",
-    "validate": "npm run build && npm run typecheck && npm test && npm run audit && npm run check && npm run pack:check"
+    "validate": "npm run build:check && npm run typecheck && npm test && npm run audit && npm run check && npm run pack:check"
   },
   "files": [
     "index.ts",
@@ -102,15 +103,9 @@
     "extensions": [
       "./dist/pi-telegram/index.js"
     ],
-    "sourceExtensions": [
-      "./index.ts"
-    ],
     "skills": [
       "./dist/skills"
     ],
-    "sourceSkills": [
-      "./skills"
-    ],
     "image": "https://raw.githubusercontent.com/llblab/pi-telegram/main/screenshot.png"
   },
   "peerDependencies": {