@llblab/pi-kit 0.15.0 → 0.16.0

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

@@ -2,7 +2,7 @@
 // Excludes: temporal algebra, Pi lifecycle, Git objects/remotes, and backend fallback policy.
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { closeSync, lstatSync, mkdirSync, openSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import {
 	assertOwnedFileUpdates, captureTemporalFileBases, parseScopeProvenance, parseScopeStream, restoreDurableFileBases,
@@ -44,17 +44,42 @@ export function initializeFileStore(root: string): void {
 	mkdirSync(resolve(root), { recursive: true });
 }
 
+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 {
+	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;
+	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"; }
+}
+
+/** Wait only for a cooperating live owner; interrupted or malformed locks remain explicit recovery errors. */
+export function acquirePublicationLock(path: string, unavailable: (cause: unknown) => Error): number {
+	const deadline = Date.now() + PUBLICATION_LOCK_WAIT_MS;
+	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);
+			Atomics.wait(publicationLockWait, 0, 0, Math.min(PUBLICATION_LOCK_POLL_MS, deadline - Date.now()));
+		}
+	}
+}
+
 /** Git writers also acquire this lock before their common-Git-directory lock. */
 export function withStoragePublicationLock<T>(repositoryRoot: string, action: (root: string) => T): T {
 	const root = resolve(repositoryRoot);
 	assertStorageDirectory(root);
 	const path = resolve(root, ".state-flow-publication.lock");
-	let descriptor: number;
-	try {
-		descriptor = openSync(path, "wx", 0o600);
-	} catch (error) {
-		throw new RevisionUnavailableError(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause: error });
-	}
+	const descriptor = acquirePublicationLock(path, (cause) => new RevisionUnavailableError(
+		`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause },
+	));
 	try {
 		writeFileSync(descriptor, `${process.pid}\n`);
 		return action(root);
@@ -91,9 +116,9 @@ export function planTemporalPublication(
 		changedScopes.push(scope);
 	}
 	const provenanceUpdates: OwnedFileUpdate[] = [];
-	// Shared metadata owns provenance, temporal boundaries, and CWD identity beside semantic files.
+	// Every scope metadata file owns provenance and temporal boundaries beside semantic files.
 	if (!runtimeOnly) {
-		for (const scope of ["global", "cwd"] as const) {
+		for (const scope of SCOPES) {
 			const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
 			const registry = provenance?.[scope] ?? parseScopeProvenance(files.get(paths.meta)!.content, paths.meta);
 			const currentFile = files.get(paths.meta)!;
@@ -104,18 +129,21 @@ export function planTemporalPublication(
 		}
 	}
 	const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-	const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config)!.content, files.get(runtimePaths.meta)!.content, cwd, sessionId);
+	const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config)!.content, files.get(runtimePaths.runtime)!.content, cwd, sessionId, files.get(runtimePaths.meta)!.content);
 	if (previousRuntime !== undefined && changedScopes.length > 0 && runtime === undefined) throw new Error("Temporal semantic publication requires its session runtime cohort");
 	const runtimeUpdates: OwnedFileUpdate[] = [];
 	if (runtime !== undefined) {
-		const sources = serializeSessionRuntime(runtime, cwd, sessionId, runtimeOnly ? undefined : view.scopes.session, files.get(runtimePaths.meta)!.content);
+		const sources = serializeSessionRuntime(runtime, cwd, sessionId);
 		if (!sameJson(runtime.meta.lineage, view.lineage)) throw new Error("Runtime lineage does not match the temporal cohort");
-		if (files.get(runtimePaths.config)!.content !== sources.config || files.get(runtimePaths.meta)!.content !== sources.meta) {
-			runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.meta, content: sources.meta });
+		if (files.get(runtimePaths.config)!.content !== sources.config || files.get(runtimePaths.runtime)!.content !== sources.runtime) {
+			runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.runtime, content: sources.runtime });
+		}
+		if (files.get(runtimePaths.runtime)!.identity === "missing" && files.get(runtimePaths.meta)!.content !== undefined
+			&& previousRuntime !== undefined && !provenanceUpdates.some(({ path }) => path === runtimePaths.meta)) {
+			const registry = provenance?.session ?? parseArtifactProvenanceRegistry(previousRuntime.meta.artifacts, "State Flow session artifact provenance");
+			const content = serializeScopeMetadata(registry, view.scopes.session, "session", undefined, files.get(runtimePaths.meta)!.content);
+			runtimeUpdates.push({ path: runtimePaths.meta, content });
 		}
-	} else if (!runtimeOnly && changedScopes.includes("session")) {
-		const content = serializeScopeMetadata(undefined, view.scopes.session, "session", undefined, files.get(runtimePaths.meta)!.content);
-		if (files.get(runtimePaths.meta)!.content !== content) runtimeUpdates.push({ path: runtimePaths.meta, content });
 	}
 	const changedPaths = new Set(changedScopes.flatMap((scope) => {
 		const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
@@ -153,14 +181,14 @@ function decodeFileCohort(cwd: string, sessionId: string, root: string, base: Te
 		scopes[scope] = stream;
 	}
 	const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-	const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.meta), cwd, sessionId);
+	const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), cwd, sessionId, files.get(paths.meta));
 	if (!runtime || runtime.meta.publication !== "files") throw new Error("File-only recovery requires file publication provenance, not a Git self reference");
 	const view = { scopes, lineage: runtime.meta.lineage };
 	validateTemporalState(view);
 	const provenance: Record<StateScope, ArtifactProvenanceRegistry> = {
 		global: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta),
 		cwd: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta),
-		session: parseArtifactProvenanceRegistry(runtime.meta.artifacts, "State Flow session artifact provenance"),
+		session: parseScopeProvenance(files.get(paths.meta), paths.meta),
 	};
 	return { runtime, view, provenance };
 }

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

@@ -27,12 +27,18 @@ export interface StateFlowTelegramState {
 	contract: Record<string, unknown>;
 	working: Record<string, unknown>;
 	response: string;
+	lazy?: unknown;
 }
 
+export type StateFlowTelegramRichText =
+	| string
+	| StateFlowTelegramRichText[]
+	| { type: "bold" | "code"; text: StateFlowTelegramRichText };
+
 export type StateFlowTelegramRichBlock =
-	| { type: "heading"; text: string; size: 3 }
-	| { type: "pre"; text: string; language?: string }
-	| { type: "details"; summary: string | { type: "bold" | "code"; text: string }; blocks: StateFlowTelegramRichBlock[]; is_open?: true };
+	| { type: "heading"; text: StateFlowTelegramRichText; size: 3 }
+	| { type: "pre"; text: StateFlowTelegramRichText; language?: string }
+	| { type: "details"; summary: StateFlowTelegramRichText; blocks: StateFlowTelegramRichBlock[]; is_open?: true };
 
 export interface StateFlowTelegramRichMessage {
 	blocks: StateFlowTelegramRichBlock[];
@@ -168,6 +174,9 @@ function renderStateFlowTelegramField(value: unknown): string {
 		const length = Math.floor((low + high) / 2);
 		const candidate = JSON.stringify({
 			truncated: true,
+			...(value !== null && typeof value === "object" && !Array.isArray(value)
+				? { keys: Object.keys(value) }
+				: {}),
 			preview: json.slice(0, length),
 			omittedChars: json.length - length,
 		}, null, 2);
@@ -182,14 +191,18 @@ function renderStateFlowTelegramField(value: unknown): string {
 }
 
 export function renderStateFlowRichState(scope: StateFlowTelegramScope, step: number, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
-	const fields = ["artifacts", "contract", "working", "response"] as const;
+	const fields = ["artifacts", "contract", "working", "response", "lazy"] as const;
 	return {
 		blocks: [
-			{ type: "heading", text: `${STATE_FLOW_SCOPE_LABELS[scope]}: \`#${step}\``, size: 3 },
+			{
+				type: "heading",
+				text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: `#${step}` }],
+				size: 3,
+			},
 			...fields.map((field) => ({
 				type: "details" as const,
 				summary: { type: "code" as const, text: field },
-				blocks: [{ type: "pre" as const, language: "json", text: renderStateFlowTelegramField(state[field]) }],
+				blocks: [{ type: "pre" as const, language: "json", text: renderStateFlowTelegramField(state[field] ?? {}) }],
 			})),
 		],
 		skip_entity_detection: true,

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

@@ -35,7 +35,7 @@ export interface StagedScopedTransition {
 }
 
 const SCOPES = new Set<StateScope>(["global", "cwd", "session"]);
-const PATCH_KEYS = new Set(["artifacts", "contract", "working"]);
+const PATCH_KEYS = new Set(["artifacts", "contract", "working", "lazy"]);
 
 function compileReadArtifacts(
 	nextState: StateDocument,
@@ -123,14 +123,17 @@ function validateScopePatch(scope: unknown, patch: unknown): asserts patch is Sc
 	validatePatch(patch);
 	for (const key of Object.keys(patch)) {
 		if (!PATCH_KEYS.has(key)) {
-			throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, and working are model-owned`);
+			throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, working, and lazy are model-owned`);
 		}
 	}
-	for (const key of PATCH_KEYS) {
+	for (const key of ["artifacts", "contract", "working"] as const) {
 		if (Object.hasOwn(patch, key) && !isObject(patch[key])) {
 			throw new Error(`Scoped State Flow patch field ${key} must be a JSON object`);
 		}
 	}
+	if (Object.hasOwn(patch, "lazy") && patch.lazy === null) {
+		throw new Error("Scoped State Flow patch field lazy cannot be null");
+	}
 	if (isObject(patch.artifacts)) validateModelArtifactPatch(patch.artifacts);
 }
 
@@ -140,6 +143,7 @@ function completePatch(patch: ScopePatch, response: string): StatePatch {
 		contract: patch.contract ?? {},
 		working: patch.working ?? {},
 		response,
+		...(Object.hasOwn(patch, "lazy") ? { lazy: structuredClone(patch.lazy!) } : {}),
 	};
 }
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.13.3",
+  "version": "0.14.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-memory/SKILL.md

@@ -46,6 +46,8 @@ Separate a binding requirement from the method currently proposed to satisfy it.
 
 When it affects continuation, retain what was proposed, accepted, rejected, corrected, explained, or left unresolved, and what the next response or action must address. Preserve enough referents for pending follow-ups to make sense.
 
+Treat every completed work slice as a possible restart boundary. Its checkpoint should let a fresh executor recover the achieved outcome, surviving evidence, active commitments, decision-relevant uncertainty, and exact continuation without replaying the prior reasoning trajectory. Optimize decomposition for resumability as well as functional completion; if the next safe action depends on transient context that will disappear, the slice is not yet at a sufficient boundary.
+
 Keep consequences, not a transcript or a personality dossier. Do not invent shared history or claim subjective continuity. A fresh run should not unnecessarily reopen a settled exchange or treat an unanswered proposal as approved.
 
 ### Preserve learning at its demonstrated boundary
@@ -70,11 +72,17 @@ A locator supports later retrieval; it does not replace content needed for the n
 
 Do not rerun the underlying project merely to curate its memory. Leave an exact unresolved check when verification falls outside the requested boundary.
 
-### Compact without flattening
+### Preserve priority and keep Lazy shallow
+
+Treat array order in Lazy as semantic priority: earlier entries are higher priority. Preserve that order deliberately; do not reorder entries for aesthetics, incidental grouping, or normalization.
+
+Minimize Lazy nesting, especially for top-level collections. Keep a top-level collection as a direct array when its members are the domain values. Represent a standalone item directly, normally as a string; use an object only when that item genuinely owns structured or nested fields. Do not add `items`, `owner`, `source`, or similar wrapper objects merely to describe the collection, and do not introduce nested arrays unless the domain itself requires a matrix or grouped sequence.
+
+### Compact without flattening meaning
 
 Merge redundant fragments and remove obsolete scaffolding, repeated argumentation, and routine progress. Do not rewrite unchanged state merely to normalize wording.
 
-Do not erase a meaningful correction, uncertainty, commitment, negative result, or continuation dependency to make state shorter. Do not retain the previous chain of reasoning solely to steer the next run toward the same method.
+Do not erase a meaningful correction, uncertainty, commitment, negative result, priority order, or continuation dependency to make state shorter. Do not retain the previous chain of reasoning solely to steer the next run toward the same method.
 
 ### Reconcile phase boundaries
 
@@ -90,7 +98,7 @@ Effective state does not prove which scope owns a value. When ownership matters
 
 Before writing, review the proposed changes once within the requested boundary:
 
-- Would a fresh executor know what must still hold, what changed, what remains unresolved, and how to continue?
+- Would a fresh executor know what must still hold, what changed, what remains unresolved, and the exact next action without replaying the prior cognitive trajectory?
 - Could an omission cause a known failed attempt, an unnecessary repeated explanation, or loss of an active commitment?
 - Could a retained claim impose an unapproved method, overgeneralize a result, or hide a live alternative?
 

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

@@ -121,7 +121,7 @@ The detailed map is canonical in [`docs/architecture.md`](./docs/architecture.md
 - Command templates remain compact and shell-free. Use string leaves or ordered `template` arrays; shell operators are not an execution contract. Examples use portable executable placeholders, never machine-local paths.
 - `telegram_attach` is the canonical file path and `telegram_message` the direct Markdown text/buttons path. Both require current direct or registered-follower authority and must not replace the normal active-turn reply.
 - Inbound handlers transform text/media before queueing; outbound handlers precede programmatic/provider fallbacks. Public contracts and ordering live in `docs/inbound.md`, `docs/outbound.md`, and `docs/public-api.md`.
-- Pi integration uses public hooks and APIs. A Telegram `/new` or equivalent session replacement requires a public Pi API that executes the real terminal path.
+- Pi integration uses public hooks and APIs. Telegram `/new` is scheduled against the exact durable update, dispatched only after that update is removed from the journal, and then routed through an internal Pi command via `pi.sendUserMessage(..., { expandPromptTemplates: true })`; the command handler receives the real `ExtensionCommandContext` and calls `ctx.newSession()`. Before replacement, CAS-publish one exact expiring handoff in the profile target snapshot. `workspace-thread` successors re-key the matching Workspace binding; `classic-chat` successors preserve Profile/CWD/session/chat continuity without creating a binding or invoking topic APIs. Both atomically claim the intent before one terminal result, and the old `withSession` path never publishes the same success. Never replace the session while inbound authority is unsettled, store stale command contexts, accept an expired or mismatched handoff, inject terminal input, spawn a shadow Pi process, or mutate session files.
 
 ## 7. Engineering Conventions
 

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`._
 
+- [ ] `Unified Telegram /new continuity` (`local-actionable`, current priority; closes [#81](https://github.com/llblab/pi-telegram/issues/81)): The existing one-shot intent now has strict `workspace-thread | classic-chat` continuity. Classic preparation persists exact Profile/CWD/session/chat identity without requiring or fabricating a Workspace binding; its codec round-trip and claim path leave Workspace bindings untouched. Threaded preparation and successor re-key retain the existing slot/name path. Local implementation and docs are complete. Classic preparation-to-successor settlement passes with one terminal send and no Workspace mutation against both the same store instance and a freshly reopened process store; duplicate settlement sends nothing. Threaded re-key, mismatch, expiry, failed-claim, full-suite, invariants, and Domain DAG regressions pass under the discriminated codec. Final `dist` is rebuilt; Classic Settings also hides both Thread-specific controls rather than exposing only cleanup. Remaining: operator-authorized Classic and Threaded live smoke. Do not close or post to #81 before release authority. Both modes delete confirmation before replacement, CAS-claim before terminal send, and preserve at-most-once cross-process result semantics; do not close or post to #81 before release authority.
 - [ ] `Prompt enqueue hotfix` (`optional`, `operator-gated`): Optional nonblocking operator-authorized disposable-follower smoke: overlap delayed voice processing with turn completion and confirm one-time ordered consumption and truthful counts against the [queue contract](./docs/architecture.md#queue-and-dispatch-safety). Separately authorized supported recovery investigation remains open: prevention does not repair an already-wedged in-memory queue; establish the exact recovery path and preservation/discard consequences before mutation, otherwise report the blocker. No journal/ownership edits, replay of settled input, implicit queue clearing, or restart; live activation requires separate operator authorization.
 - [ ] `Channel multimedia posts` (`0.45.1`, live-acceptance-gated): `telegram_message` channel delivery accepts one local `.jpg`/`.jpeg`/`.png`/`.webp` photo or `.mp4` video, uploads it through the multipart transport as `sendPhoto`/`sendVideo` with `text` as the HTML caption, validates kind and size (photo ≤ 10 MiB, video ≤ 50 MiB) plus ≤ 1024 visible caption characters before issuance, and rejects unsupported types and albums instead of downgrading them to links. The channel-post journal binds kind/file name/byte size/SHA-256 and caption, so duplicate requests and lost acknowledgements never re-upload; media-post edits replace the caption through `editMessageCaption`, and Markdown spoilers render as `<tg-spoiler>`. Live image publication passed on `@llb_log`. Regressions cover confirmed publication, duplicate requests, lost ACK, pre-issuance rejection, caption edits, and reconnect replacement. Remaining: operator-authorized disposable-channel acceptance of rejected upload, duplicate request, and caption edit.
 - [ ] `Manual Thread naming` (`gated-but-preparable`, release priority): Local bot-owned `/name Name` and bare `/name` flows avoid model dispatch. One expiring exact-target input dialog immediately accepts the next valid name, always offers cancel, and offers **Reset to automatic** only while a manual override exists; duplicate/stale callbacks cannot repeat mutation. Durable manual override supersedes every automatic display mode, reset is leader/follower generation- and target-fenced, and Letters remains the default without rewriting recovery identity. Local review findings are remediated, including Bot-API-wait target-replacement regressions for leader/follower rename and reset. Remaining: disposable live acceptance for command-menu ordering, dialog, invalid input, duplicate callbacks, leader/follower rename and reset.

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

@@ -4,6 +4,13 @@
 
 ## Unreleased
 
+## 0.49.0: Unified fresh-session continuity
+
+- `/new`: Classic and Threaded Mode now share one confirmed fresh-session flow. The settled callback deletes its dialog and publishes an expiring exact-target intent; a same- or cross-process successor preserves the classic chat or re-keys the Thread/slot/name, atomically claims once, then sends one terminal result. Identity mismatches fail closed.
+- `Command menus`: Both Telegram command menus now keep the primary sequence `/start`, `/compact`, `/new`, `/continue`, `/next`; the niche `/name` command remains available but moves out of menus into the Thread display Settings guidance.
+- `Classic Settings`: Hides both Thread display and Thread cleanup controls when Threaded Mode is unavailable, rather than exposing only half of the Thread-specific surface.
+- `Thread display`: A current Thread with a manual `/name` override now appears as `custom` on the Settings row and detail heading; choosing any automatic mode clears the current Thread's override, reapplies that projection, and selects it again. Successful interactive rename/reset now settles its source before asynchronously publishing the result, so immediate `/new` cannot replay the consumed name after replacement; cancellation reports only its completed result.
+
 ## 0.48.3: Assistant publication identity hotfix
 
 - `Thread restore display identity`: Restoring or reclaiming a Thread now renames the destination from its current Workspace display title when available, rather than leaking the internal baked slot name such as `Moss` into directory-title mode.

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

@@ -164,6 +164,7 @@ Use these in the bot DM.
 | --- | --- |
 | `/start` | Pair when needed and open the main operator menu |
 | `/name [Name]` | Set a manual Thread title immediately, or open rename/reset controls when Name is omitted |
+| `/new` | Start a new Pi session in the current classic chat or Thread after confirming the bridge is idle |
 | `/compact` | Confirm and run session compaction when safe |
 | `/next` | Dispatch the next queued turn, aborting first if needed |
 | `/continue` | Enqueue a priority continuation prompt |

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

@@ -216,6 +216,7 @@ interface TelegramLifecycleBindingDeps {
     deferredQueueDispatchRuntime: Queue.TelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>;
     modelContextAvailabilityRuntime: Prompts.TelegramModelContextAvailabilityRuntime;
     disconnectOnQuit?: () => Promise<unknown>;
+    onSessionStarted?: (event: Pi.SessionStartEvent, ctx: Pi.ExtensionContext) => void;
     shutdownGenerativeAppLiveSurfaces?: () => void;
     resolveAutomaticThreadCleanupEnabled?: () => boolean | Promise<boolean>;
     buttonActionStore: OutboundHandlers.TelegramButtonActionStore;
@@ -246,5 +247,5 @@ interface TelegramLifecycleBindingDeps {
     updateStatus: TelegramBridgeStatusUpdater;
     recordRuntimeEvent: TelegramRuntimeEventRecorder;
 }
-export declare function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive, isTurnTransportActive, updateStatus, recordRuntimeEvent, }: TelegramLifecycleBindingDeps): void;
+export declare function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive, isTurnTransportActive, updateStatus, recordRuntimeEvent, }: TelegramLifecycleBindingDeps): void;
 export {};

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

@@ -499,7 +499,7 @@ export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, pe
         },
     });
 }
-export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive = () => true, isTurnTransportActive, updateStatus, recordRuntimeEvent, }) {
+export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive = () => true, isTurnTransportActive, updateStatus, recordRuntimeEvent, }) {
     const agentEndResetter = Runtime.createTelegramAgentEndResetter({
         abort,
         typing,
@@ -755,6 +755,7 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
             activityVerbosityRuntime?.reset();
             modelContextAvailabilityRuntime.reconcile();
             await sessionLifecycleRuntime.onSessionStart(event, ctx);
+            onSessionStarted?.(event, ctx);
         },
         async onSessionShutdown(event, ctx) {
             if (!isSessionContextActive(ctx))

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

@@ -1,11 +1,13 @@
 /**
  * Telegram command routing helpers
  * Zones: telegram controls, pi agent commands, queue controls
- * Owns Telegram slash-command normalization, bot command metadata, and pi-side command registration behind runtime ports
+ * Owns Telegram slash-command normalization, bot command metadata, pi-side command registration, and command-initiated session replacement orchestration behind runtime ports
  */
 import { type TelegramConfigStore } from "./config.ts";
+import type * as Pi from "./pi.ts";
 import type { ExtensionAPI, ExtensionCommandContext } from "./pi.ts";
 import type { TelegramBridgeStatusLineOptions } from "./status.ts";
+import type { TelegramSessionReplacementIntent } from "./threads.ts";
 import { type PendingTelegramControlItem, type TelegramQueueAdmissionReceipt } from "./queue.ts";
 export interface ParsedTelegramCommand {
     name: string;
@@ -60,6 +62,7 @@ export declare const TELEGRAM_COMMAND_EMOJI: {
     readonly abort: "⏹️";
     readonly stop: "🟥";
     readonly name: "🏷️";
+    readonly new: "🆕";
 };
 export type TelegramCommandEmojiName = keyof typeof TELEGRAM_COMMAND_EMOJI;
 export declare function getTelegramCommandEmoji(command: TelegramCommandEmojiName): string;
@@ -144,7 +147,7 @@ export declare function createTelegramThreadDisplayNameRenameBinding(): {
 };
 export declare function parseTelegramRequestedThreadName(args: string): string | undefined;
 export declare function registerTelegramBridgeCommands(pi: ExtensionAPI, deps: TelegramBridgeCommandRegistrationDeps): void;
-export declare const TELEGRAM_RESERVED_COMMAND_NAMES: readonly ["stop", "name", "abort", "next", "continue", "status", "queue", "compact", "model", "thinking", "settings", "help", "start"];
+export declare const TELEGRAM_RESERVED_COMMAND_NAMES: readonly ["stop", "name", "new", "abort", "next", "continue", "status", "queue", "compact", "model", "thinking", "settings", "help", "start"];
 export type TelegramReservedCommandName = (typeof TELEGRAM_RESERVED_COMMAND_NAMES)[number];
 export declare function isTelegramReservedCommandName(commandName: string | undefined): commandName is TelegramReservedCommandName;
 export type TelegramCommandAction = {
@@ -156,6 +159,9 @@ export type TelegramCommandAction = {
 } | {
     kind: "name";
     executionMode: "immediate";
+} | {
+    kind: "new";
+    executionMode: "immediate";
 } | {
     kind: "abort";
     executionMode: "immediate";
@@ -192,6 +198,7 @@ export type TelegramCommandExecutionMode = "ignored" | "immediate";
 export interface TelegramCommandActionDeps<TMessage, TContext> {
     handleStop: (message: TMessage, ctx: TContext) => Promise<void>;
     handleName: (message: TMessage, ctx: TContext, name: string) => Promise<void>;
+    handleNew: (message: TMessage, ctx: TContext) => Promise<void>;
     handleAbort: (message: TMessage, ctx: TContext) => Promise<void>;
     handleNext: (message: TMessage, ctx: TContext) => Promise<void>;
     handleContinue: (message: TMessage, ctx: TContext) => Promise<void>;
@@ -264,6 +271,13 @@ export interface TelegramCompactConfirmationCallbackQuery {
         message_thread_id?: number;
     };
 }
+export interface TelegramNewConfirmationCallbackDeps<TContext> {
+    ctx: TContext;
+    answerCallbackQuery: (callbackQueryId: string, text?: string) => Promise<void>;
+    editInteractiveMessage: (chatId: number, messageId: number, text: string, mode: "markdown" | "html" | "plain", replyMarkup: TelegramCompactConfirmationReplyMarkup) => Promise<void>;
+    deleteMessage: (chatId: number, messageId: number) => Promise<void>;
+    runNew: (ctx: TContext) => Promise<void>;
+}
 export interface TelegramCompactConfirmationCallbackDeps<TContext> {
     ctx: TContext;
     answerCallbackQuery: (callbackQueryId: string, text?: string) => Promise<void>;
@@ -390,6 +404,7 @@ export interface TelegramCommandRuntimeDeps<TMessage extends TelegramCommandRunt
     }) => void;
     stopTypingLoop?: () => void;
     enqueueContinueTurn: (message: TMessage, ctx: TContext) => Promise<void>;
+    requestNewSession?: (message: TMessage) => void;
     compact: (ctx: TContext, callbacks: {
         onComplete: () => void;
         onError: (error: unknown) => void;
@@ -434,6 +449,10 @@ export declare const TELEGRAM_COMMAND_ACTIONS: {
         readonly kind: "name";
         readonly executionMode: "immediate";
     };
+    readonly new: {
+        readonly kind: "new";
+        readonly executionMode: "immediate";
+    };
     readonly abort: {
         readonly kind: "abort";
         readonly executionMode: "immediate";
@@ -515,10 +534,27 @@ export declare function handleTelegramNextCommand(deps: {
 export declare function handleTelegramContinueCommand<TMessage, TContext>(message: TMessage, ctx: TContext, deps: {
     enqueueContinueTurn: (message: TMessage, ctx: TContext) => Promise<void>;
 }): Promise<void>;
+export declare function buildTelegramNewConfirmationReplyMarkup(): TelegramCompactConfirmationReplyMarkup;
+export declare function getTelegramNewConfirmationHtml(): string;
+export declare function openTelegramNewConfirmation(target: TelegramCommandMessageTarget, deps: TelegramCompactConfirmationDeps): Promise<void>;
+export declare function handleTelegramNewConfirmationCallback<TContext>(query: TelegramCompactConfirmationCallbackQuery, deps: TelegramNewConfirmationCallbackDeps<TContext>): Promise<boolean>;
 export declare function buildTelegramCompactConfirmationReplyMarkup(): TelegramCompactConfirmationReplyMarkup;
 export declare function getTelegramCompactConfirmationHtml(): string;
 export declare function openTelegramCompactConfirmation(target: TelegramCommandMessageTarget, deps: TelegramCompactConfirmationDeps): Promise<void>;
 export declare function handleTelegramCompactConfirmationCallback<TContext>(query: TelegramCompactConfirmationCallbackQuery, deps: TelegramCompactConfirmationCallbackDeps<TContext>): Promise<boolean>;
+export interface TelegramNewCommandDeps extends TelegramRuntimeEventRecorderPort {
+    isIdle: () => boolean;
+    hasPendingMessages: () => boolean;
+    hasActiveTelegramTurn: () => boolean;
+    hasDispatchPending: () => boolean;
+    hasQueuedTelegramItems: () => boolean;
+    isCompactionInProgress: () => boolean;
+    requestNewSession?: () => void;
+    sendTextReply: (text: string, options?: {
+        parseMode?: "HTML";
+    }) => Promise<void>;
+}
+export declare function handleTelegramNewCommand(deps: TelegramNewCommandDeps): Promise<void>;
 export declare function handleTelegramCompactCommand(deps: TelegramCompactCommandDeps): Promise<void>;
 export declare function handleTelegramStatusCommand<TContext>(deps: {
     ctx: TContext;
@@ -538,4 +574,100 @@ export declare function createTelegramCommandHandler<TMessage extends TelegramCo
 export declare function createTelegramCommandOrPromptRuntime<TMessage, TContext>(deps: TelegramCommandOrPromptRuntimeDeps<TMessage, TContext>): {
     dispatchMessages: (messages: TMessage[], ctx: TContext) => Promise<void>;
 };
+export declare const TELEGRAM_SESSION_ACTION_COMMAND_NAME = "telegram-session-action";
+export declare const TELEGRAM_SESSION_ACTION_COMMAND_DESCRIPTION = "(internal) replace the current Pi session after Telegram settlement";
+export declare function delayTelegramSessionAction(delayMs: number): Promise<void>;
+export interface TelegramSessionActionRuntimeDeps {
+    registerCommand: Pi.ExtensionAPI["registerCommand"];
+    sendUserMessage: Pi.ExtensionAPI["sendUserMessage"];
+    notifyResult: (target: {
+        chatId: number;
+        threadId?: number;
+        messageId: number;
+    }, result: "success" | "cancelled" | "failure") => Promise<void>;
+    prepareReplacement?: (ctx: Pi.ExtensionCommandContext, updateId: number, target: {
+        chatId: number;
+        threadId?: number;
+        messageId: number;
+    }) => Promise<void>;
+    recordRuntimeEvent?: (category: string, error: unknown) => void;
+}
+export interface TelegramSessionReplacementSettlementDeps {
+    getIntent: () => Promise<TelegramSessionReplacementIntent | undefined>;
+    hasSuccessorContinuity: (intent: TelegramSessionReplacementIntent) => boolean;
+    editSuccess: (intent: TelegramSessionReplacementIntent) => Promise<{
+        ok: boolean;
+        retryable?: boolean;
+        message?: string;
+    }>;
+    clearIntent: (intent: TelegramSessionReplacementIntent) => Promise<boolean>;
+    profileName: string | undefined;
+    cwd: string;
+    sessionId: string;
+    now?: () => number;
+    sleep?: (delayMs: number) => Promise<void>;
+    isCurrent?: () => boolean;
+}
+export declare function settleTelegramSessionReplacement(deps: TelegramSessionReplacementSettlementDeps): Promise<"none" | "settled" | "expired" | "failed" | "stale">;
+export declare function createTelegramSessionReplacementSettlementRuntime<TContext>(deps: {
+    resolve: (ctx: TContext) => TelegramSessionReplacementSettlementDeps | undefined;
+    onResult?: (result: "none" | "settled" | "expired" | "failed" | "stale") => void;
+    onError?: (error: unknown) => void;
+}): {
+    onSessionStart: (ctx: TContext) => void;
+};
+export interface TelegramSessionActionAssemblyDeps {
+    registerCommand: Pi.ExtensionAPI["registerCommand"];
+    sendUserMessage: Pi.ExtensionAPI["sendUserMessage"];
+    store: {
+        load: () => Promise<void>;
+        refresh?: () => Promise<void>;
+        getWorkspaceBindingByTarget: (target: {
+            chatId: number;
+            threadId?: number;
+        }, sessionId?: string) => {
+            cwd: string;
+            sessionId?: string;
+            slot?: string;
+            threadName?: string;
+            manualThreadName?: string;
+            target: {
+                chatId: number;
+                threadId: number;
+            };
+        } | undefined;
+        getSessionReplacementIntent: () => TelegramSessionReplacementIntent | undefined;
+        commitSessionReplacementIntent: (intent: TelegramSessionReplacementIntent, isCurrent: () => boolean) => Promise<boolean>;
+        removeSessionReplacementIntent: (intent: TelegramSessionReplacementIntent, isCurrent: () => boolean) => Promise<boolean>;
+    };
+    getProfileName: () => string | undefined;
+    ownsPersistence: () => boolean;
+    sendResult: (target: {
+        chatId: number;
+        threadId?: number;
+    }, html: string) => Promise<{
+        ok: boolean;
+        retryable?: boolean;
+    }>;
+    handoffTtlMs: number;
+    now?: () => number;
+    recordRuntimeEvent?: (category: string, error: unknown) => void;
+}
+export declare function createTelegramSessionActionAssembly(deps: TelegramSessionActionAssemblyDeps): {
+    action: TelegramSessionActionRuntime;
+    settlement: {
+        onSessionStart: (ctx: Pi.ExtensionContext) => void;
+    };
+};
+export interface TelegramSessionActionRuntime {
+    register: () => void;
+    scheduleAfterUpdate: (updateId: number, target: {
+        chatId: number;
+        threadId?: number;
+        messageId: number;
+    }) => boolean;
+    onUpdateCompleted: (updateId: number) => void;
+    hasPending: () => boolean;
+}
+export declare function createTelegramSessionActionRuntime(deps: TelegramSessionActionRuntimeDeps): TelegramSessionActionRuntime;
 export {};