@llblab/pi-kit 0.27.5 → 0.28.0

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

@@ -1,12 +1,14 @@
 /**
  * Telegram singleton lock helpers
  * Zones: telegram ownership, filesystem, transport authority
- * Owns extension-local owners.json access and Telegram bridge ownership semantics
+ * Owns filesystem authority, atomic runtime-section publication and Telegram bridge ownership semantics
  */
-import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { basename, dirname, join } from "node:path";
-import { resolveTelegramOwnersPath } from "./paths.js";
+import { isDeepStrictEqual } from "node:util";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { isWireRecord as runtimeStateRecord } from "./wire.js";
+import { isTelegramSessionPollingJournalPath, resolveTelegramOwnersPath, resolveTelegramSessionPollingJournalPath, resolveTelegramUpdateJournalPathForProfile, } from "./paths.js";
 export const TELEGRAM_LOCK_KEY = "default";
 export const TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS = 8_000;
 export const TELEGRAM_OWNERSHIP_CHECK_MS = 1_000;
@@ -42,6 +44,53 @@ export function createTelegramLockKeyResolver(activeProfile) {
         return resolveTelegramLockKey(activeProfile.getActiveProfileName());
     };
 }
+/**
+ * Captures exact context, session generation and owned leader epoch before awaits.
+ * Session replacement, release or re-election revokes the grant; a successor never renews it.
+ */
+export function createTelegramOwnedStateAuthorityCapture(lock, session) {
+    return () => {
+        const ctx = session.get(), generation = session.getGeneration();
+        if (ctx === undefined || !session.isCurrent(ctx, generation))
+            return undefined;
+        const epoch = lock.getOwnedLeaderEpoch();
+        if (epoch === undefined)
+            return undefined;
+        const current = () => session.isCurrent(ctx, generation) && lock.owns(ctx) && lock.getOwnedLeaderEpoch() === epoch;
+        return current() ? current : undefined;
+    };
+}
+/**
+ * Leader polling journal: the path owners.json names, else the session that would host it on acquisition.
+ * Without a session identity, the flat root `inbox` remains the compatibility fallback.
+ */
+export function createTelegramLeaderJournalPathResolver(deps) {
+    // An existing flat root journal keeps its custody; new installations never create one.
+    const createOwn = (profileName = deps.getProfileName()) => {
+        const root = resolveTelegramUpdateJournalPathForProfile(profileName);
+        if (existsSync(root))
+            return root;
+        const sessionId = deps.getSessionId();
+        return sessionId === undefined ? undefined : resolveTelegramSessionPollingJournalPath(sessionId, undefined, profileName);
+    };
+    return {
+        createJournalPath: () => createOwn(),
+        resolve(profileName) {
+            const named = deps.getNamedJournalPath();
+            if (named && (isTelegramSessionPollingJournalPath(named) ||
+                named === resolveTelegramUpdateJournalPathForProfile(profileName)))
+                return named;
+            return createOwn(profileName) ?? resolveTelegramUpdateJournalPathForProfile(profileName);
+        },
+    };
+}
+/** A released key keeps only `{ journalPath }`: no owner, but the successor's polling custody. */
+export function readTelegramLockJournalPath(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const path = value.journalPath;
+    return typeof path === "string" && path ? path : undefined;
+}
 export function readLocks(path = getOwnersPath()) {
     if (!existsSync(path))
         return {};
@@ -479,6 +528,201 @@ export function withTelegramFileTransaction(transactionPath, operation, options
         releaseLockTransactionGuard(transactionPath, owner);
     }
 }
+export class TelegramRuntimeStateError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "TelegramRuntimeStateError";
+        this.code = code;
+    }
+}
+const TELEGRAM_RUNTIME_STATE_SECTIONS = ["transport", "workspace", "admission", "runtime"];
+const TELEGRAM_ACTIVE_STATE_TRANSACTIONS = Symbol.for("@llblab/pi-telegram/active-state-transactions");
+function requireRuntimeStatePath(path) {
+    if (typeof path !== "string" || !isAbsolute(path) || resolve(path) !== path)
+        throw new TelegramRuntimeStateError("invalid", "Telegram runtime state path must be canonical and absolute.");
+}
+function requireRuntimeStateProfile(profile) {
+    if (typeof profile !== "string" || !profile.length || profile.length > 512 || /[\x00-\x1f]/u.test(profile))
+        throw new TelegramRuntimeStateError("invalid", "Telegram runtime state profile is invalid.");
+}
+/** Private single-link regular file read with identity continuity; initial absence only is positive. */
+function readTelegramRuntimeSource(path) {
+    requireRuntimeStatePath(path);
+    let source;
+    let observed = false;
+    try {
+        const stat = lstatSync(path);
+        observed = true;
+        if (!stat.isFile() || stat.nlink !== 1 ||
+            (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
+            throw new TelegramRuntimeStateError("invalid", "Telegram runtime state must be a private regular file.");
+        const fd = openSync(path, "r");
+        try {
+            const opened = fstatSync(fd);
+            if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.nlink !== 1 || !opened.isFile() ||
+                (process.platform !== "win32" && (opened.mode & 0o077) !== 0))
+                throw new TelegramRuntimeStateError("invalid", "Telegram runtime state identity changed before reading.");
+            source = readFileSync(fd).toString("utf8");
+        }
+        finally {
+            closeSync(fd);
+        }
+        const after = lstatSync(path);
+        if (after.dev !== stat.dev || after.ino !== stat.ino || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs)
+            throw new TelegramRuntimeStateError("invalid", "Telegram runtime state changed during observation.");
+    }
+    catch (error) {
+        if (!observed && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    return source;
+}
+/** Strict, observational envelope read; section owners validate their own payloads. Legacy state is never adopted here. */
+export function readTelegramRuntimeState(path) {
+    const observed = readTelegramRuntimeSource(path);
+    if (observed === undefined)
+        return { version: 2, profiles: {} };
+    let value;
+    try {
+        value = JSON.parse(observed);
+    }
+    catch (error) {
+        throw new TelegramRuntimeStateError("invalid", "Telegram runtime state is unreadable.", { cause: error });
+    }
+    if (!runtimeStateRecord(value) || value.version !== 2 || !runtimeStateRecord(value.profiles) ||
+        Object.keys(value).some(key => key !== "version" && key !== "profiles"))
+        throw new TelegramRuntimeStateError("invalid", "Telegram runtime state envelope is unsupported or malformed.");
+    for (const [profile, sections] of Object.entries(value.profiles)) {
+        requireRuntimeStateProfile(profile);
+        if (!runtimeStateRecord(sections) || Object.keys(sections).some(key => !TELEGRAM_RUNTIME_STATE_SECTIONS.includes(key)))
+            throw new TelegramRuntimeStateError("invalid", "Telegram runtime state sections are malformed.");
+    }
+    return value;
+}
+/**
+ * Operator-approved optimistic recovery before leader acquisition: when the shared envelope, any transport section or a
+ * caller-validated section is damaged, publish a fresh empty envelope instead of refusing. All profiles lose runtime
+ * continuity. Filesystem access errors are not damage and still throw. Returns whether a reset was published.
+ */
+export function resetDamagedTelegramRuntimeState(path, validateProfile) {
+    requireRuntimeStatePath(path);
+    const runtimeDir = join(dirname(path), "runtime");
+    mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
+    return withTelegramFileTransaction(join(runtimeDir, `${basename(path)}.transaction`), () => {
+        let damaged = false;
+        try {
+            for (const [profile, sections] of Object.entries(readTelegramRuntimeState(path).profiles)) {
+                assertTelegramStateTransport(sections.transport);
+                try {
+                    validateProfile?.(profile, sections);
+                }
+                catch {
+                    damaged = true;
+                }
+            }
+        }
+        catch (error) {
+            if (!(error instanceof TelegramRuntimeStateError))
+                throw error;
+            damaged = true;
+        }
+        if (!damaged)
+            return false;
+        const tempPath = join(runtimeDir, `${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+        try {
+            writeFileSync(tempPath, `${JSON.stringify({ version: 2, profiles: {} }, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            if (!renameTelegramPathWithRetry(tempPath, path))
+                throw new Error("Telegram runtime state reset publication disappeared.");
+        }
+        finally {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        return true;
+    });
+}
+/**
+ * One physical read/check/write transaction for one named section. The caller supplies domain policy; copies expose
+ * current sibling facts without granting writes to them. No await, nested transaction, repair or legacy import.
+ */
+export function mutateTelegramRuntimeStateSection(path, profile, section, mutate, options) {
+    requireRuntimeStatePath(path);
+    requireRuntimeStateProfile(profile);
+    if (!TELEGRAM_RUNTIME_STATE_SECTIONS.includes(section))
+        throw new TelegramRuntimeStateError("invalid", "Telegram runtime state section is invalid.");
+    const active = (globalThis[TELEGRAM_ACTIVE_STATE_TRANSACTIONS] ??= new Set());
+    if (active.has(path))
+        throw new TelegramRuntimeStateError("invalid", "Nested Telegram runtime state transaction is not allowed.");
+    const assertCurrent = () => {
+        if (!options.isCurrent())
+            throw new TelegramRuntimeStateError("authority-changed", "Telegram runtime state publication authority changed.");
+    };
+    assertCurrent();
+    active.add(path);
+    try {
+        const runtimeDir = join(dirname(path), "runtime");
+        mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
+        return withTelegramFileTransaction(join(runtimeDir, `${basename(path)}.transaction`), () => {
+            assertCurrent();
+            const file = readTelegramRuntimeState(path);
+            const previous = Object.hasOwn(file.profiles, profile) ? file.profiles[profile] : {};
+            const outcome = mutate(structuredClone(previous[section]), structuredClone(previous));
+            if (!runtimeStateRecord(outcome) || !Object.hasOwn(outcome, "value") || !Object.hasOwn(outcome, "result") || "then" in outcome)
+                throw new TelegramRuntimeStateError("invalid", "Telegram runtime state mutations must return a synchronous value and result.");
+            // Normalize intentional optional properties to their wire representation before comparison/publication.
+            const next = outcome.value === undefined ? undefined : JSON.parse(JSON.stringify(outcome.value));
+            assertCurrent();
+            if (isDeepStrictEqual(previous[section], next))
+                return outcome.result;
+            const updated = { ...previous };
+            if (next === undefined)
+                delete updated[section];
+            else
+                updated[section] = next;
+            if (Object.keys(updated).length)
+                Object.defineProperty(file.profiles, profile, { value: updated, enumerable: true, configurable: true, writable: true });
+            else
+                delete file.profiles[profile];
+            const tempPath = join(runtimeDir, `${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+            try {
+                options.onPublicationBoundary?.("before-write");
+                assertCurrent();
+                writeFileSync(tempPath, `${JSON.stringify(file, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+                options.onPublicationBoundary?.("after-write-before-rename");
+                assertCurrent();
+                try {
+                    if (!renameTelegramPathWithRetry(tempPath, path, { rename: options.publishRename }))
+                        throw new Error("Telegram runtime state temporary publication disappeared.");
+                    options.onPublicationBoundary?.("after-rename");
+                    assertCurrent();
+                }
+                catch (error) {
+                    throw new TelegramRuntimeStateError("publication-unknown", "Telegram runtime state publication outcome is unknown.", { cause: error });
+                }
+                return outcome.result;
+            }
+            finally {
+                try {
+                    unlinkSync(tempPath);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+            }
+        });
+    }
+    finally {
+        active.delete(path);
+    }
+}
 function withLockTransaction(locksPath, mutate) {
     return withTelegramFileTransaction(`${locksPath}.transaction`, () => {
         const locks = readLocksForTransaction(locksPath);
@@ -541,6 +785,7 @@ export function parseTelegramLockEntry(value) {
             ? record.busSocketPath
             : undefined,
         busSecret: typeof record.busSecret === "string" ? record.busSecret : undefined,
+        ...(readTelegramLockJournalPath(record) ? { journalPath: readTelegramLockJournalPath(record) } : {}),
     };
 }
 export function isProcessAlive(pid) {
@@ -555,7 +800,7 @@ export function isProcessAlive(pid) {
         return error.code !== "ESRCH";
     }
 }
-export function formatTelegramLockEntry(lock) {
+function formatTelegramLockEntry(lock) {
     return lock.cwd ? `pid ${lock.pid}, cwd ${lock.cwd}` : `pid ${lock.pid}`;
 }
 function formatTelegramFollowerRegistrationFailure(message) {
@@ -606,6 +851,8 @@ function canSupersedeSameProcessOwner(current, pid, ctx, instanceId, runtimeGene
 }
 function createLockEntry(pid, ctx, options) {
     const lock = { pid, cwd: ctx.cwd };
+    if (options.journalPath)
+        lock.journalPath = options.journalPath;
     if (options.instanceId) {
         const nowMs = options.getNowMs?.();
         lock.instanceId = options.instanceId;
@@ -631,8 +878,26 @@ function formatLockState(state) {
             return `stale (${formatTelegramLockEntry(state.lock)})`;
     }
 }
+function assertTelegramStateTransport(value) {
+    if (value === undefined)
+        return;
+    if (!runtimeStateRecord(value))
+        throw new TelegramRuntimeStateError("invalid", "Telegram state transport is malformed.");
+    const keys = ["pid", "cwd", "instanceId", "heartbeatMs", "leaderEpoch", "runtimeGeneration", "busSocketPath", "busSecret", "journalPath"];
+    if (Object.keys(value).some(key => !keys.includes(key)) ||
+        (value.pid === undefined ? Object.keys(value).length !== 1 || !readTelegramLockJournalPath(value) :
+            !Number.isSafeInteger(value.pid) || value.pid <= 0) ||
+        ["cwd", "instanceId", "busSocketPath", "busSecret", "journalPath"].some(key => value[key] !== undefined && typeof value[key] !== "string") ||
+        ["heartbeatMs", "runtimeGeneration"].some(key => value[key] !== undefined && (!Number.isSafeInteger(value[key]) || value[key] < 0)) ||
+        (value.journalPath !== undefined && !readTelegramLockJournalPath(value)) ||
+        (value.leaderEpoch !== undefined && (typeof value.leaderEpoch === "string" ? value.leaderEpoch.length === 0 : !Number.isSafeInteger(value.leaderEpoch))))
+        throw new TelegramRuntimeStateError("invalid", "Telegram state transport is malformed.");
+}
 export function createTelegramLockRuntime(options = {}) {
     const key = options.key ?? TELEGRAM_LOCK_KEY;
+    if (options.statePath && options.locksPath)
+        throw new TelegramRuntimeStateError("invalid", "Telegram transport must select one storage identity.");
+    const statePath = options.statePath;
     const locksPath = options.locksPath ?? getOwnersPath();
     const pid = options.pid ?? process.pid;
     const isAlive = options.isProcessAlive ?? isProcessAlive;
@@ -650,9 +915,59 @@ export function createTelegramLockRuntime(options = {}) {
             return key() || TELEGRAM_LOCK_KEY;
         return key;
     };
+    const readOwners = () => {
+        if (!statePath)
+            return readLocks(locksPath);
+        // Read-only ownership queries fail closed (no owner); acquisition/publication still refuse malformed state.
+        try {
+            const transports = Object.fromEntries(Object.entries(readTelegramRuntimeState(statePath).profiles)
+                .filter(([, value]) => Object.hasOwn(value, "transport")).map(([profile, value]) => [profile, value.transport]));
+            assertTelegramStateTransport(transports[resolveEffectiveKey()]);
+            return transports;
+        }
+        catch {
+            return {};
+        }
+    };
+    const transactOwners = (mutate) => {
+        if (!statePath)
+            return withLockTransaction(locksPath, mutate);
+        const profile = resolveEffectiveKey();
+        return mutateTelegramRuntimeStateSection(statePath, profile, "transport", current => {
+            assertTelegramStateTransport(current);
+            const locks = { [profile]: current };
+            const outcome = mutate(locks);
+            const value = outcome.changed ? locks[profile] : current;
+            assertTelegramStateTransport(value);
+            return { value, result: outcome.result };
+        }, { ...options.statePublication, isCurrent: () => resolveEffectiveKey() === profile });
+    };
     const readLock = () => {
         const effectiveKey = resolveEffectiveKey();
-        return parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+        return parseTelegramLockEntry(readOwners()[effectiveKey]);
+    };
+    // A live older-release leader polls the same bot from its own directory. Only identity is exposed: its bus
+    // endpoint, secret and epoch belong to another protocol and must never become a follower target.
+    const readLegacyOwner = (effectiveKey) => {
+        if (!options.legacyLocksPath || options.legacyLocksPath === (statePath ?? locksPath))
+            return undefined;
+        try {
+            const records = statePath ? readLocksForTransaction(options.legacyLocksPath) : readLocks(options.legacyLocksPath);
+            if (statePath)
+                for (const value of Object.values(records))
+                    assertTelegramStateTransport(value);
+            const raw = records[effectiveKey];
+            const legacy = parseTelegramLockEntry(raw);
+            if (!legacy || getLockState(legacy, -1, isAlive, stateOptions()).kind !== "active-elsewhere")
+                return undefined;
+            return { pid: legacy.pid, ...(legacy.cwd ? { cwd: legacy.cwd } : {}), ...(legacy.instanceId ? { instanceId: legacy.instanceId } : {}),
+                ...(legacy.heartbeatMs !== undefined ? { heartbeatMs: legacy.heartbeatMs } : {}) };
+        }
+        catch (error) {
+            if (statePath)
+                throw error;
+            return undefined;
+        }
     };
     const adoptCompatibleOwnedLock = (effectiveKey, lock, ctx) => {
         if (ownedLock) {
@@ -671,8 +986,11 @@ export function createTelegramLockRuntime(options = {}) {
         return ownedLock;
     };
     return {
-        acquire: (ctx, acquireOptions = {}) => withLockTransaction(locksPath, (locks) => {
+        acquire: (ctx, acquireOptions = {}) => transactOwners((locks) => {
             const effectiveKey = resolveEffectiveKey();
+            const legacy = readLegacyOwner(effectiveKey);
+            if (legacy)
+                return { result: { ok: false, lock: legacy }, changed: false };
             const current = parseTelegramLockEntry(locks[effectiveKey]);
             const state = getLockState(current, pid, isAlive, stateOptions());
             const expectedOwned = adoptCompatibleOwnedLock(effectiveKey, current, ctx);
@@ -714,7 +1032,9 @@ export function createTelegramLockRuntime(options = {}) {
                     changed: false,
                 };
             }
+            const journalPath = readTelegramLockJournalPath(locks[effectiveKey]) ?? options.createJournalPath?.(ctx);
             const lock = createLockEntry(pid, ctx, {
+                journalPath,
                 instanceId: options.instanceId,
                 busSocketPath: options.busSocketPath,
                 busSecret: options.busSecret,
@@ -738,13 +1058,17 @@ export function createTelegramLockRuntime(options = {}) {
         release: () => {
             // Withdraw local send authority even if the durable release fails.
             deliveryRevoked = true;
-            return withLockTransaction(locksPath, (locks) => {
+            return transactOwners((locks) => {
                 const effectiveKey = resolveEffectiveKey();
                 const state = getLockState(parseTelegramLockEntry(locks[effectiveKey]), pid, isAlive, stateOptions());
                 const changed = ownedLockKey === effectiveKey &&
                     hasSameLockOwner(parseTelegramLockEntry(locks[effectiveKey]), ownedLock);
                 if (changed) {
-                    delete locks[effectiveKey];
+                    const journalPath = readTelegramLockJournalPath(locks[effectiveKey]);
+                    if (journalPath)
+                        locks[effectiveKey] = { journalPath };
+                    else
+                        delete locks[effectiveKey];
                     ownedLockKey = undefined;
                     ownedLock = undefined;
                 }
@@ -752,12 +1076,13 @@ export function createTelegramLockRuntime(options = {}) {
             });
         },
         getState: () => getLockState(readLock(), pid, isAlive, stateOptions()),
+        getJournalPath: () => readTelegramLockJournalPath(readOwners()[resolveEffectiveKey()]),
         getStatusLabel: () => formatLockState(getLockState(readLock(), pid, isAlive, stateOptions())),
         getOwnedLeaderEpoch: () => {
             if (deliveryRevoked)
                 return undefined;
             const effectiveKey = resolveEffectiveKey();
-            const lock = parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+            const lock = parseTelegramLockEntry(readOwners()[effectiveKey]);
             const exactOwner = adoptCompatibleOwnedLock(effectiveKey, lock);
             return hasSameLockOwner(lock, exactOwner) ? lock?.leaderEpoch : undefined;
         },
@@ -765,10 +1090,10 @@ export function createTelegramLockRuntime(options = {}) {
             if (deliveryRevoked)
                 return false;
             const effectiveKey = resolveEffectiveKey();
-            const lock = parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+            const lock = parseTelegramLockEntry(readOwners()[effectiveKey]);
             return hasSameLockOwner(lock, adoptCompatibleOwnedLock(effectiveKey, lock, ctx));
         },
-        commitIfOwned: (commit) => !deliveryRevoked && withLockTransaction(locksPath, (locks) => {
+        commitIfOwned: (commit) => !deliveryRevoked && transactOwners((locks) => {
             const effectiveKey = resolveEffectiveKey();
             const lock = parseTelegramLockEntry(locks[effectiveKey]);
             const exactOwner = ownedLockKey === effectiveKey && hasSameLockOwner(lock, ownedLock);
@@ -780,9 +1105,34 @@ export function createTelegramLockRuntime(options = {}) {
                 return { result: false, changed: false };
             }
             commit();
-            return { result: true, changed: false };
+            // External-file commits may retain an independent effect; never acknowledge under a changed unified owner.
+            const current = !statePath || (!deliveryRevoked && hasSameLockOwner(parseTelegramLockEntry(readOwners()[effectiveKey]), ownedLock));
+            return { result: current, changed: false };
         }),
-        refresh: (ctx) => !deliveryRevoked && withLockTransaction(locksPath, (locks) => {
+        publishStateSectionIfOwned(section, mutate, publication) {
+            if (section !== "workspace" && section !== "runtime")
+                throw new TelegramRuntimeStateError("invalid", "Telegram owner section publication is restricted to Workspace and runtime observations.");
+            if (!statePath)
+                throw new TelegramRuntimeStateError("invalid", "Consolidated transport storage is not selected.");
+            const profile = resolveEffectiveKey(), expected = ownedLock ? { ...ownedLock } : undefined;
+            if (publication.expectedScope && (publication.expectedScope.path !== statePath || publication.expectedScope.profile !== profile))
+                return { committed: false };
+            if (deliveryRevoked || ownedLockKey !== profile || !expected || !publication.isCurrent())
+                return { committed: false };
+            const isCurrent = () => !deliveryRevoked && resolveEffectiveKey() === profile && ownedLockKey === profile &&
+                hasSameLockOwner(ownedLock, expected) && publication.isCurrent() &&
+                hasSameLockOwner(parseTelegramLockEntry(readOwners()[profile]), expected);
+            if (!isCurrent())
+                return { committed: false };
+            return mutateTelegramRuntimeStateSection(statePath, profile, section, (current, observed) => {
+                assertTelegramStateTransport(observed.transport);
+                if (!hasSameLockOwner(parseTelegramLockEntry(observed.transport), expected))
+                    return { value: current, result: { committed: false } };
+                const outcome = mutate(current, observed);
+                return { value: outcome.value, result: { committed: true, result: outcome.result } };
+            }, { ...publication, isCurrent });
+        },
+        refresh: (ctx) => !deliveryRevoked && transactOwners((locks) => {
             const effectiveKey = resolveEffectiveKey();
             const lock = parseTelegramLockEntry(locks[effectiveKey]);
             const expectedOwner = adoptCompatibleOwnedLock(effectiveKey, lock, ctx);
@@ -806,6 +1156,7 @@ export function createTelegramLockRuntime(options = {}) {
                     ? { busSocketPath: options.busSocketPath }
                     : {}),
                 busSecret: options.busSecret ?? lock.busSecret,
+                ...(lock.journalPath ? { journalPath: lock.journalPath } : {}),
             };
             locks[effectiveKey] = refreshedLock;
             ownedLockKey = effectiveKey;
@@ -999,6 +1350,15 @@ export function createTelegramLockedPollingRuntime(deps) {
                 await ownershipStop;
             if (!isCurrent())
                 return cancelled;
+            if (!options.election && deps.resetDamagedState) {
+                try {
+                    if (deps.resetDamagedState())
+                        deps.recordRuntimeEvent?.("lock", new Error("Damaged Telegram runtime state was reset; previous runtime continuity was discarded."), { phase: "state-reset" });
+                }
+                catch (error) {
+                    deps.recordRuntimeEvent?.("lock", error, { phase: "state-reset" });
+                }
+            }
             let acquired = deps.lock.acquire(ctx, {
                 force: options.force,
                 expectedOwner: options.election?.expectedOwner ??
@@ -1093,6 +1453,12 @@ export function createTelegramLockedPollingRuntime(deps) {
             return "Telegram bridge disconnected.";
         },
         suspend: suspendPolling,
+        captureTransportAuthority(ctx) {
+            const generation = pollingGeneration;
+            const current = () => generation === pollingGeneration && activeContext === ctx && !ownershipStop &&
+                (deps.isContextCurrent?.(ctx) ?? true) && deps.lock.owns(snapshotLockContext(ctx));
+            return current() ? current : undefined;
+        },
         isSuspended: () => suspendedGeneration === pollingGeneration &&
             suspensionsInFlight === 0 && startupsInFlight === 0 && !sessionAutoStartRun && !ownershipStop,
         onPersistentConflict: async (ctx, count) => {

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

@@ -4,22 +4,27 @@
  * Owns bounded JSONL runtime evidence files, previous-log preservation, and profile-aware log paths without becoming routing state
  */
 import * as Status from "./status.ts";
-export type TelegramLogPathInput = string | (() => string);
-export interface TelegramRuntimeJsonlEvent {
+type TelegramLogPathInput = string | (() => string);
+interface TelegramRuntimeJsonlEvent {
     at: number;
     category: string;
     message: string;
     details?: Record<string, unknown>;
 }
-export interface TelegramRuntimeJsonlLogOptions {
+interface TelegramRuntimeJsonlLogOptions {
     path?: TelegramLogPathInput;
     previousPath?: TelegramLogPathInput;
     maxBytes?: number;
     getNowMs?: () => number;
     canReset?: () => boolean;
     commitReset?: (commit: () => void) => boolean;
+    /** Explicit shared-file protocol; profile-labelled scope reset is an append, never truncation. */
+    sharedProfiles?: {
+        getProfileName: () => string | undefined;
+        captureAuthority: () => (() => boolean) | undefined;
+    };
 }
-export interface TelegramRuntimeJsonlLog {
+interface TelegramRuntimeJsonlLog {
     getPath: () => string;
     reset: (reason: string, scope?: Record<string, unknown>) => void;
     resetIfScopeChanged: (scopeKey: string, reason: string, scope?: Record<string, unknown>) => void;
@@ -28,7 +33,18 @@ export interface TelegramRuntimeJsonlLog {
 export declare function getTelegramRuntimeLogPath(agentDir?: string, profileName?: string): string;
 export declare function getTelegramPreviousRuntimeLogPath(agentDir?: string, profileName?: string): string;
 export declare function createTelegramRuntimeJsonlLog(options?: TelegramRuntimeJsonlLogOptions): TelegramRuntimeJsonlLog;
-export interface TelegramRuntimeDiagnosticsRuntime<TContext> {
+interface TelegramRuntimeDiagnosticsStatusPorts<TContext> {
+    instanceId: string;
+    updateStatus(ctx: TContext, error?: string): void;
+    getStatusState(): Status.TelegramBridgeStatusLineState;
+    persistSnapshot(snapshot: ReturnType<typeof Status.createTelegramStatusSnapshot>): Promise<void>;
+    session?: {
+        get(): TContext | undefined;
+        getGeneration(): number;
+        isCurrent(ctx: TContext, generation?: number): boolean;
+    };
+}
+interface TelegramRuntimeDiagnosticsRuntime<TContext> {
     events: Status.TelegramRuntimeEventRecorder;
     recordRuntimeEvent(category: string, error: unknown, details?: Record<string, unknown>): void;
     bindStorage(ports: {
@@ -36,15 +52,17 @@ export interface TelegramRuntimeDiagnosticsRuntime<TContext> {
         getProfileName(): string | undefined;
         canReset(): boolean;
         commitReset(commit: () => void): boolean;
+        captureAuthority?: () => (() => boolean) | undefined;
     }): void;
-    bindStatus(ports: {
-        instanceId: string;
-        updateStatus(ctx: TContext, error?: string): void;
-        getStatusState(): Status.TelegramBridgeStatusLineState;
-        persistSnapshot(snapshot: ReturnType<typeof Status.createTelegramStatusSnapshot>): Promise<void>;
-    }): void;
+    bindStatus(ports: TelegramRuntimeDiagnosticsStatusPorts<TContext>): void;
+    onSessionStart(): void;
+    onSessionShutdown(): Promise<void>;
     updateStatus(ctx: TContext, error?: string): void;
     getStatusLines(options?: Status.TelegramBridgeStatusLineOptions): string[];
     scheduleSnapshotPersist(): void;
 }
-export declare function createTelegramRuntimeDiagnosticsRuntime<TContext>(): TelegramRuntimeDiagnosticsRuntime<TContext>;
+export declare function createTelegramRuntimeDiagnosticsRuntime<TContext>(options?: {
+    sharedFile?: boolean;
+    snapshotTimer?: Pick<Parameters<typeof Status.createTelegramRuntimeDiagnosticsSnapshotScheduler>[0], "setTimer" | "clearTimer">;
+}): TelegramRuntimeDiagnosticsRuntime<TContext>;
+export {};