@llblab/pi-telegram 0.51.2 → 0.51.4

package/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/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/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/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/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/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;
 }

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.51.2",
+  "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": {

package/docs/multi-instance-bus.md

@@ -151,7 +151,7 @@ A registered instance exposes:
 
 ## Approved Next Contract: Directory Names And Reclaimable Slots
 
-Status: approved design with a locally tested pure selection policy in `lib/workspace-slots.ts` and profile-isolated display preference persistence/default resolution in `lib/config.ts`. Workspace claims now reserve global letters before provisioning and preserve legacy binding keys. An exact claim assigns the first free letter to a missing-slot binding or the selected member of a duplicate-slot set, but persistence waits for successful target recovery; unresolved duplicates block unrelated fresh allocation. Sticky suffix metadata and acknowledged `displayTitle` persist in Workspace bindings. `lib/thread-display.ts` provides the three-mode projection plus serialized title reconciliation wired into leader startup and follower registration. Heartbeat ACKs carry acknowledged display titles to followers and the current-thread/TUI projection uses them without changing restoration identity. Settings now exposes Letters (default), Names, and Directories; follower changes use the capability-gated leader-owned setting path. Live bot chooser/notice labels and cross-instance agent-target resolution use acknowledged titles without granting routing authority. The Thread store now persists the first proven `inactiveSinceMs` transition with exact confirmed target absence or fenced non-destructive detachment of a confirmed-dead follower or quiescent quitting leader whose tab is preserved; successful active provisioning clears it. Pressure selection, intents, mocked execution, and recovery are implemented. A 2/2 same-model independent post-fix quorum cleared the admission-composition blocker at 0.96 confidence per reviewer, and the operator has since authorized demand-driven rotation. Fresh allocation now invokes the existing retirement lifecycle under full capacity; `BACKLOG.md` owns remaining disposable-client acceptance.
+Status: approved design with a locally tested pure selection policy in `lib/workspace-slots.ts` and profile-isolated display preference persistence/default resolution in `lib/config.ts`. Workspace claims now reserve global letters before provisioning and preserve legacy binding keys. An exact claim assigns the first free letter to a missing-slot binding or the selected member of a duplicate-slot set, but persistence waits for successful target recovery; unresolved duplicates block unrelated fresh allocation. If authenticated follower re-registration finds that its retained target record carries another letter, the exact claim is canonical: registration repairs that record before binding commit and leaves the unrelated binding that owns the stale letter intact. Sticky suffix metadata and acknowledged `displayTitle` persist in Workspace bindings. `lib/thread-display.ts` provides the three-mode projection plus serialized title reconciliation wired into leader startup and follower registration. Heartbeat ACKs carry acknowledged display titles to followers and the current-thread/TUI projection uses them without changing restoration identity. Settings now exposes Letters (default), Names, and Directories; follower changes use the capability-gated leader-owned setting path. Live bot chooser/notice labels and cross-instance agent-target resolution use acknowledged titles without granting routing authority. The Thread store now persists the first proven `inactiveSinceMs` transition with exact confirmed target absence or fenced non-destructive detachment of a confirmed-dead follower or quiescent quitting leader whose tab is preserved; successful active provisioning clears it. Pressure selection, intents, mocked execution, and recovery are implemented. A 2/2 same-model independent post-fix quorum cleared the admission-composition blocker at 0.96 confidence per reviewer, and the operator has since authorized demand-driven rotation. Fresh allocation now invokes the existing retirement lifecycle under full capacity; `BACKLOG.md` owns remaining disposable-client acceptance.
 
 The pure policy distinguishes a free letter, a proposed pressure-reclamation victim, and protected/invalid capacity. Its caller must supply a validated profile-wide snapshot, reservations, proven inactivity start, and explicit protection classification; duplicate legacy letters block selection. The policy performs no filesystem or Telegram operations and does not establish liveness or deletion authority. It proposes a victim only when every profile-wide letter is occupied or reserved; elapsed time alone never triggers retirement.
 

package/docs/public-api.md

@@ -71,7 +71,7 @@ Every assistant-authored HTML comment is transport-private on Telegram: previews
 - `telegram_channel_post(action, operation_id, markdown?)` edits or deletes one exact `published` record returned by `telegram_channel_posts`. Edit requires Markdown and delete forbids it. A media-post edit replaces the caption through `editMessageCaption`, while a text post uses `editMessageText`; both render Markdown formatting, including spoilers, as Telegram HTML. The direct leader fences the tool call as outcome-unknown before the mutation call, so ambiguous failures are never replayed automatically.
 - `telegram_channel_posts(chat_id?, limit?)` lists newest bounded records from the active profile's agent-owned post journal. It returns publication, edit/delete outcome-unknown, confirmed, and deleted local records only, including retained media kind/file name/size/SHA-256 identity; it never reads or claims completeness for Telegram channel history. This explicit successful listing is the only tool response that exposes retained authored Markdown; channel tool failures use fixed redacted messages, while pre-issuance media/caption validation errors stay actionable.
 - `telegram_message(text, chat_id?, media?, channel?, thread_id?, thread?)` sends a direct Telegram Markdown message when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus. A public `@username`, or an exact negative numeric channel ID with `channel: true`, is passed as `chat_id` without a local registry; channel delivery requires the direct leader, and Telegram enforces whether the bot has channel posting permission. Channel delivery accepts `media` as one local `.jpg`/`.jpeg`/`.png`/`.webp` photo or `.mp4` video (photo ≤ 10 MiB, video ≤ 50 MiB), uploaded through multipart `sendPhoto`/`sendVideo` with `text` as its HTML caption (≤ 1024 visible characters); unsupported media types and albums are rejected before issuance, and the durable channel-post journal binds media identity and caption so duplicate or lost-acknowledgement retries never re-upload. `thread` accepts a live numeric Thread id or its current acknowledged display title; name matching is case-insensitive and fails closed when absent or ambiguous, while delivery captures the numeric target. During an active Telegram turn, omitted targeting and an explicit target equal to that turn are rejected so the ordinary final-reply path remains the sole current-target response; an explicit different chat/thread target remains allowed. Outside active turns, paired/default local/TUI delivery remains unchanged. Top-level `telegram_button` comments inside `text` are parsed with the same planner used for normal replies and attached to that message; buttons are never standalone Telegram messages.
-- The bundled `telegram-bridge` Skill owns action syntax, target routing, Threaded Mode, formatting, Generative App operation, and profile-specific debugging guidance. The bundled `show-me` Skill owns portable evidence-honest explanations and adapts them to phone-width Markdown or self-contained HTML artifacts when Telegram is the active surface. The regular prompt routes applicable turns to these and the other bundled Skills. `telegram_attach`, `telegram_bind`, and `telegram_message` remain registered but are model-active only while this instance owns direct transport or holds a live follower registration; disconnect/loss suppresses their schemas and prompt metadata, and recovery restores only the operator's previously active pi-telegram subset.
+- The bundled `telegram-bridge` Skill owns action syntax, target routing, Threaded Mode, formatting, Generative App operation, and profile-specific debugging guidance. The bundled `show-me` Skill owns portable evidence-honest explanations and adapts them to phone-width Markdown or self-contained HTML artifacts when Telegram is the active surface. The regular prompt routes applicable turns to these and the other bundled Skills. Compiled npm/git installations expose them through the package `pi.skills` manifest so Pi resource filters remain authoritative; a raw TypeScript checkout under Pi's `extensions` directory contributes its source Skill root at runtime instead. `telegram_attach`, `telegram_bind`, and `telegram_message` remain registered but are model-active only while this instance owns direct transport or holds a live follower registration; disconnect/loss suppresses their schemas and prompt metadata, and recovery restores only the operator's previously active pi-telegram subset.
 - `telegram_voice` hidden comments request Telegram-native voice delivery through `{text}`, `{text|lang}`, `{text|lang|rate}`, or a JSON object. JSON is the fallback for multiline content, named fields, or escaping; equivalent `text` or `value` supplies the spoken payload, with explicit `text` taking precedence.
 - `telegram_button` hidden comments create footer buttons; standalone column-zero triple-backtick `telegram_button` blocks create button rows between paragraphs in Native Rich Markdown. Both accept the same singleton or mixed JSON/CML matrix and share prompt/app routing; fenced blocks also accept adjacent top-level JSON/CML objects without an outer array or commas as vertical singleton rows. Native rows allow at most eight buttons and must fit one Rich Message chunk; invalid or incomplete blocks register nothing. Drafts hide action fences. HTML compatibility projects fenced controls into the footer. In-body clicks acknowledge without recoloring the Rich body; selected-style highlighting remains footer-only. One marker accepts a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row; separators are optional and one trailing comma is tolerated at matrix, row, and JSON-object boundaries. Top-level cells become full-width rows, while nested rows group one or more buttons horizontally without an artificial parser-width cap. CML uses `{value}`, `{label|prompt}`, prompt-only `{|prompt}`, or the corresponding three-atom form with `selected_style`; an omitted label uses the existing prompt-as-label fallback, and the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. A fourth atom accepts `1` or `true` (disabled), and `0` or `false` (enabled), with exact lowercase spelling; an omitted fourth position stays enabled, and the third atom may be empty in this form (`{|Next||1}`). JSON uses boolean `disabled`. Disabled cells need no prompt or selected style: `{Next|||1}` is label-only and `{|||1}` is blank (JSON `{"label":"Next","disabled":true}` and `{"disabled":true}`). The Telegram renderer supplies a non-breaking space only when the label is empty. Disabled cells stay visible but carry `disabled: {}` instead of callback data and register no prompt or bound action; invalid disabled values reject the candidate matrix. It trims atom boundaries and supports only the minimal escapes `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Use JSON `label` plus `prompt`, or `value` when both strings are identical. Action markers are colon-free; colon-prefixed payloads are rejected. Use top-level column-zero action wrappers, outside quotes, lists, or enclosing code examples. Ordinary code fences and larger outer fences preserve literal examples; bare JSON/CML in prose never activates.
 

package/lib/bus-leader.ts

@@ -1210,13 +1210,36 @@ export function createTelegramBusFollowerTargetProvisioner(
         : recoverableTarget && !pendingTargetRecovery
           ? await recoverRequestedTarget()
           : await provisionTarget();
+      const alignResultWithWorkspaceSlot = (): void => {
+        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,
@@ -1300,7 +1323,7 @@ export function createTelegramBusFollowerTargetProvisioner(
           } else if (crossSessionReuse && reconnectRecord) {
             const nowMs = getNowMs();
             const transferredRecord = deps.topicTargetStore.upsert({
-              ...reconnectRecord,
+              ...result.record,
               profileKey: followerProfileKey,
               owner:
                 followerOwner.kind === "manual-follower"
@@ -1361,6 +1384,7 @@ export function createTelegramBusFollowerTargetProvisioner(
         }
       }
       if (workspaceIdentity) {
+        alignResultWithWorkspaceSlot();
         const workspaceCommit =
           Threads.commitTelegramWorkspaceProvisionBinding({
             store: deps.topicTargetStore,
@@ -1373,7 +1397,7 @@ export function createTelegramBusFollowerTargetProvisioner(
               ...(result.record.threadName
                 ? { threadName: result.record.threadName }
                 : {}),
-              ...(result.record.slot ? { slot: result.record.slot } : {}),
+              slot: workspaceIdentity.slot,
               journalBindingKeys: [followerProfileKey],
               journalBindingsComplete: true,
               updatedAtMs: getNowMs(),

package/lib/skills.ts

@@ -1,21 +1,65 @@
 /**
  * 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";
 
 import type { ExtensionAPI } from "./pi.ts";
+import { resolveAgentDir } from "./paths.ts";
 
-export const TELEGRAM_SKILLS_PATH = fileURLToPath(
-  new URL("../skills", import.meta.url),
+const TELEGRAM_SKILLS_MODULE_PATH = fileURLToPath(import.meta.url);
+
+export function getTelegramExtensionPackageRoot(modulePath: string): string {
+  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 interface TelegramRawExtensionCheckoutOptions {
+  agentDir?: string;
+  cwd?: string;
+}
+
+export function isRawTelegramExtensionCheckout(
+  modulePath: string,
+  options: TelegramRawExtensionCheckoutOptions = {},
+): boolean {
+  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: Pick<ExtensionAPI, "on">,
-): void {
+  modulePath = TELEGRAM_SKILLS_MODULE_PATH,
+  options: TelegramRawExtensionCheckoutOptions = {},
+): boolean {
+  // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.51.2",
+  "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": {

package/scripts/build-dist.mjs

@@ -1,44 +1,115 @@
 #!/usr/bin/env node
 
 /**
- * Builds the distributive JavaScript, declarations, Pi entrypoint, and Skills.
- * Usage: node scripts/build-dist.mjs
- *
- * The build replaces `dist`, compiles with `tsconfig.build.json`, then copies
- * package-owned runtime assets. It does not publish, pack, or modify sources.
+ * Builds or verifies the distributive JavaScript, declarations, Pi entrypoint,
+ * Skills, and runtime assets without exposing a partial tree.
  */
 
 import { spawnSync } from "node:child_process";
-import { cpSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join, relative } from "node:path";
+
+const DIST_DIR = "dist";
+const checkOnly = process.argv.includes("--check");
 
 function run(command, args) {
   const result = spawnSync(command, args, { stdio: "inherit" });
   if (result.error) throw result.error;
-  if (result.status !== 0) process.exit(result.status ?? 1);
+  if (result.status !== 0) {
+    throw new Error(`${command} exited with status ${result.status ?? "unknown"}.`);
+  }
+}
+
+function listFiles(root, current = root) {
+  return readdirSync(current, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(current, entry.name);
+    return entry.isDirectory() ? listFiles(root, path) : [relative(root, path)];
+  }).sort();
+}
+
+function normalizeTextFiles(root) {
+  const textSuffixes = [".js", ".ts", ".mjs", ".json", ".md"];
+  for (const path of listFiles(root)) {
+    if (!textSuffixes.some((suffix) => path.endsWith(suffix))) continue;
+    const absolutePath = join(root, path);
+    const source = readFileSync(absolutePath, "utf8");
+    const normalized = source.replace(/\r\n?/g, "\n");
+    if (normalized !== source) writeFileSync(absolutePath, normalized, "utf8");
+  }
+}
+
+function assertTreesEqual(expectedRoot, actualRoot) {
+  if (!existsSync(expectedRoot)) {
+    throw new Error(`${expectedRoot} is missing; run npm run build.`);
+  }
+  const expectedFiles = listFiles(expectedRoot);
+  const actualFiles = listFiles(actualRoot);
+  if (JSON.stringify(expectedFiles) !== JSON.stringify(actualFiles)) {
+    throw new Error("dist file inventory is stale; run npm run build.");
+  }
+  for (const path of expectedFiles) {
+    if (!readFileSync(join(expectedRoot, path)).equals(readFileSync(join(actualRoot, path)))) {
+      throw new Error(`dist/${path} is stale; run npm run build.`);
+    }
+  }
+}
+
+function replaceDist(candidate) {
+  const backup = `.dist-backup-${process.pid}-${Date.now()}`;
+  const hadDist = existsSync(DIST_DIR);
+  if (hadDist) renameSync(DIST_DIR, backup);
+  try {
+    renameSync(candidate, DIST_DIR);
+    if (hadDist) rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    if (hadDist && existsSync(backup) && !existsSync(DIST_DIR)) {
+      renameSync(backup, DIST_DIR);
+    }
+    throw error;
+  }
 }
 
-rmSync("dist", { recursive: true, force: true });
-mkdirSync("dist", { recursive: true });
-
-run(process.execPath, [
-  join("node_modules", "typescript", "bin", "tsc"),
-  "-p",
-  "tsconfig.build.json",
-]);
-
-mkdirSync(join("dist", "pi-telegram"), { recursive: true });
-writeFileSync(
-  join("dist", "pi-telegram", "index.js"),
-  'export { default } from "../index.js";\n',
-  "utf8",
-);
-
-cpSync("skills", join("dist", "skills"), { recursive: true });
-cpSync("package.json", join("dist", "package.json"));
-cpSync(
-  join("lib", "generative-app-worker.mjs"),
-  join("dist", "lib", "generative-app-worker.mjs"),
-);
-
-run(process.execPath, ["--check", join("dist", "pi-telegram", "index.js")]);
+const candidate = mkdtempSync(join(process.cwd(), ".dist-build-"));
+try {
+  run(process.execPath, [
+    join("node_modules", "typescript", "bin", "tsc"),
+    "-p",
+    "tsconfig.build.json",
+    "--outDir",
+    candidate,
+  ]);
+
+  mkdirSync(join(candidate, "pi-telegram"), { recursive: true });
+  writeFileSync(
+    join(candidate, "pi-telegram", "index.js"),
+    'export { default } from "../index.js";\n',
+    "utf8",
+  );
+  normalizeTextFiles(candidate);
+  cpSync("skills", join(candidate, "skills"), { recursive: true });
+  cpSync("package.json", join(candidate, "package.json"));
+  cpSync(
+    join("lib", "generative-app-worker.mjs"),
+    join(candidate, "lib", "generative-app-worker.mjs"),
+  );
+  run(process.execPath, ["--check", join(candidate, "pi-telegram", "index.js")]);
+
+  if (checkOnly) {
+    assertTreesEqual(DIST_DIR, candidate);
+    console.log("pi-telegram: dist is current");
+  } else {
+    replaceDist(candidate);
+  }
+} finally {
+  rmSync(candidate, { recursive: true, force: true });
+}