pi-braid-telegram 0.1.7 → 0.1.9

package/README.md

@@ -53,12 +53,13 @@ Every `BRAID_TG_*` name has a `TELEGRAM_*` alias; the prefixed name wins when bo
 
 `braid.telegram.*` keys in `~/.pi/agent/settings.json`:
 
-| Key                             | Default  | Effect                                                     |
-| ------------------------------- | -------- | ---------------------------------------------------------- |
-| `braid.telegram.sendMaxChars`   | `4096`   | Cap for plain `telegram_send` text; re-read per send       |
-| `braid.telegram.notifyMaxChars` | `1200`   | Cap for the turn-complete update; re-read per notification |
-| `braid.telegram.tts`            | edge-tts | Voice source, rate and voices; read at extension load      |
-| `braid.telegram.pauseStateFile` | unset    | Where the pause control keeps its state; read at load      |
+| Key                              | Default  | Effect                                                                                                                                          |
+| -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `braid.telegram.sendMaxChars`    | `4096`   | Cap for plain `telegram_send` text; re-read per send                                                                                            |
+| `braid.telegram.notifyMaxChars`  | `1200`   | Cap for the turn-complete update; re-read per notification                                                                                      |
+| `braid.telegram.pollerAutoStart` | off      | Working directories that start the inbound poller by themselves: `true` everywhere, an absolute-cwd array those only, exact match; read at load |
+| `braid.telegram.tts`             | edge-tts | Voice source, rate and voices; read at extension load                                                                                           |
+| `braid.telegram.pauseStateFile`  | unset    | Where the pause control keeps its state; read at load                                                                                           |
 
 ## Limits
 

package/build-info.json

@@ -1,9 +1,9 @@
 {
   "name": "pi-braid-telegram",
-  "version": "0.1.7",
-  "sha": "55abdd57dac34879f6b39b357e31283ad6c3e974",
-  "shaShort": "55abdd57",
+  "version": "0.1.9",
+  "sha": "ced405d5d39735e56ba7b2079c95b75371153e99",
+  "shaShort": "ced405d5",
   "branch": "detached",
   "dirty": false,
-  "packedAt": "2026-11-03T21:27:05.199Z"
+  "packedAt": "2026-11-10T18:51:54.828Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-braid-telegram",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Talk to your pi coding agent from Telegram: send text or voice, get the answer back, and tap a button to decide.",
   "type": "module",
   "files": [

package/src/index.ts

@@ -94,6 +94,7 @@ import {
   type SttConfig,
 } from "./lib/transcribe.js";
 import { resolveSttKeyCandidates } from "./lib/stt-keys.js";
+import { pollerAutoStartFor } from "./lib/telegram-settings.js";
 import { normalizeAudioBytes } from "./lib/audio-normalize.js";
 import { populateVoiceTts } from "./lib/tts.js";
 import { runTelegramSend } from "./lib/tool-logic.js";
@@ -1705,6 +1706,29 @@ export default async function telegramExtension(
   pi.registerCommand("telegram", {
     description:
       "Telegram channel control: /telegram enable | /telegram send <text>",
+    getArgumentCompletions: (prefix: string) => {
+      const typed = (prefix ?? "").toLowerCase();
+      const verbs = [
+        {
+          value: "enable",
+          label: "enable",
+          description: "Start the background poller",
+        },
+        {
+          value: "disable",
+          label: "disable",
+          description: "Stop the background poller",
+        },
+        { value: "send", label: "send", description: "Send text to the owner" },
+        {
+          value: "status",
+          label: "status",
+          description: "Show channel and poller state",
+        },
+      ];
+      const matches = verbs.filter((verb) => verb.value.startsWith(typed));
+      return matches.length > 0 ? matches : null;
+    },
     handler: async (args: string, ctx: any) => {
       const trimmed = args.trim();
 
@@ -1818,7 +1842,13 @@ export default async function telegramExtension(
   // it is unset AND BRAID_TG_POLL_ENABLED is set. BRAID_TG_POLL_ENABLED opts
   // in explicitly.
   const pollDisabled = Boolean(env(ENV_POLL_DISABLED));
-  const pollEnabled = Boolean(env(ENV_POLL_ENABLED));
+  // Two ways in: the env var, or a settings entry naming this working directory
+  // (`braid.telegram.pollerAutoStart`, read through the same uncached reader the
+  // caps use, so an edit applies without a restart). The settings path is the
+  // one that survives a hand-started session after a reboot, which is the case
+  // that left the owner with no channel at all.
+  const pollByCwd = pollerAutoStartFor(process.cwd());
+  const pollEnabled = Boolean(env(ENV_POLL_ENABLED)) || pollByCwd;
 
   if (pollDisabled) {
     log(
@@ -1838,20 +1868,22 @@ export default async function telegramExtension(
       stt,
       onOwnerMessage: deliverOwnerMessage,
       onCallbackQuery: handleCallbackQuery,
-      startedBy: `${ENV_POLL_ENABLED}=1`,
+      startedBy: env(ENV_POLL_ENABLED)
+        ? `${ENV_POLL_ENABLED}=1`
+        : "settings:pollerAutoStart",
       onStart: () => void placeControlKeyboardOnce(),
       pidAlive: deps?.pidAlive,
     });
     if (!outcome.started && outcome.reason !== "already-running") {
       log(
         outcome.reason === "lock-held" ? "warn" : "info",
-        `telegram poller not auto-started (${ENV_POLL_ENABLED}=1): ${describePollerStartRefusal(outcome)}`,
+        `telegram poller not auto-started (${env(ENV_POLL_ENABLED) ? `${ENV_POLL_ENABLED}=1` : "settings:pollerAutoStart"}): ${describePollerStartRefusal(outcome)}`,
       );
     }
   } else {
     log(
       "info",
-      `telegram background poller default-off (set ${ENV_POLL_ENABLED}=1 to auto-start, or use /telegram enable or the telegram_poller tool)`,
+      `telegram background poller default-off (set ${ENV_POLL_ENABLED}=1, name this cwd in braid.telegram.pollerAutoStart, or use /telegram enable or the telegram_poller tool)`,
     );
   }
 

package/src/lib/poller-lock.ts

@@ -40,7 +40,15 @@ export const POLLER_HEARTBEAT_INTERVAL_MS = 10_000;
  */
 export const POLLER_HEARTBEAT_STALE_MS = 30_000;
 
-/** Boot identity recorded when neither the kernel id nor sysctl is readable. */
+/**
+ * Slack between the moment a pre-identity holder wrote its lock and the start
+ * time of the process now answering to the same pid. A pid can be recycled, so a
+ * live pid alone cannot prove that the recorded holder is still there; a process
+ * that started well after the record was written is someone else.
+ */
+const LEGACY_PID_REUSE_SLACK_MS = 60_000;
+
+/** Boot identity recorded when the kernel offers no readable name at all. */
 const BOOT_IDENTITY_FALLBACK = "boot-unknown";
 
 /** Default lock location: beside the other braid-owned telegram state
@@ -93,7 +101,9 @@ export type PollerLockTakeoverReason =
   | "unreadable-file"
   | "same-pid-refresh"
   | "stale-same-instance"
-  | "stale-across-namespace";
+  | "stale-across-namespace"
+  | "stale-legacy"
+  | "stale-legacy-recycled";
 
 /**
  * Why an acquisition refused.
@@ -109,6 +119,7 @@ export type PollerLockTakeoverReason =
 export type PollerLockRefusalReason =
   | "held-same-instance"
   | "held-across-namespace"
+  | "held-legacy"
   | "stale-unknown";
 
 export type PollerLockReason =
@@ -136,6 +147,9 @@ export type AcquirePollerLockResult =
 export interface AcquirePollerLockOptions {
   pidAlive?: (pid: number) => boolean;
   now?: () => number;
+  /** Start time of a live pid, in epoch ms. Injected so the legacy arm can be
+   *  tested without depending on the machine's process table. */
+  pidStartedAt?: (pid: number) => number | undefined;
 }
 
 /** Read the lock file; absent/corrupt/unreadable reads as "no holder". */
@@ -164,30 +178,78 @@ export function isPidAlive(pid: number): boolean {
   }
 }
 
-/**
- * The kernel's boot identity: `/proc/sys/kernel/random/boot_id` where the proc
- * filesystem is mounted, `sysctl -n kern.boottime` on darwin, and a recorded
- * fallback when neither is readable. A fallback is deliberate rather than a
- * guess: two boots that both fall back and share a hostname look identical,
- * which the heartbeat then has to cover.
- */
-function readBootIdentity(): string {
+/** Injectable kernel probes for the boot identity. Each returns the raw text
+ *  its source offers, or undefined when that source is unreadable here. */
+export interface BootIdentityProbes {
+  /** Contents of `/proc/sys/kernel/random/boot_id`, where procfs is mounted. */
+  readProcBootId?: () => string | undefined;
+  /** `sysctl -n <name>` on this host. */
+  readSysctl?: (name: string) => string | undefined;
+}
+
+/** The Linux kernel's own name for the boot. Absent where procfs is not mounted
+ *  in this namespace. */
+function readProcBootIdFile(): string | undefined {
   try {
-    const proc = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
-    if (proc) return proc;
+    return readFileSync("/proc/sys/kernel/random/boot_id", "utf8");
   } catch {
-    // Not Linux, or /proc not mounted in this namespace.
+    return undefined;
   }
+}
+
+/** One `sysctl -n <name>` read: undefined when the name does not exist on this
+ *  platform or sysctl refuses. */
+function runSysctl(name: string): string | undefined {
   try {
-    const sysctl = execFileSync("sysctl", ["-n", "kern.boottime"], {
+    return execFileSync("sysctl", ["-n", name], {
       encoding: "utf8",
       timeout: 2000,
       stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    if (sysctl) return sysctl;
+    });
   } catch {
-    // Absent on this platform, or sysctl refused.
+    return undefined;
   }
+}
+
+/** A probe's answer names a boot only when it carries text: an empty read falls
+ *  through to the next source. */
+function nonEmpty(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+/**
+ * The kernel's boot identity, in the order the kernel can be trusted to keep it.
+ * `/proc/sys/kernel/random/boot_id` is written once per boot and is free where
+ * procfs exists; `kern.bootsessionuuid` is darwin's name for the same fact.
+ * `kern.boottime` is the wall clock minus uptime, so a clock step moves it and
+ * two processes on one boot then compute different identities: it stays only as
+ * the last resort, a documented degradation rather than the darwin default. The
+ * recorded fallback covers a kernel that offers none of the three; two boots
+ * that both fall back and share a hostname look identical, which the heartbeat
+ * then has to cover.
+ *
+ * Probes are injected so a fixture can answer for two readings of one boot and
+ * observe which source the identity took. The live path passes none and reads
+ * this machine.
+ */
+export function readBootIdentity(probes: BootIdentityProbes = {}): string {
+  const readProc = probes.readProcBootId ?? readProcBootIdFile;
+  const sysctl = probes.readSysctl ?? runSysctl;
+  const probe = (read: () => string | undefined): string | undefined => {
+    try {
+      return nonEmpty(read());
+    } catch {
+      // A probe that throws did not read its source.
+      return undefined;
+    }
+  };
+  const kernelId = probe(readProc);
+  if (kernelId) return kernelId;
+  const sessionUuid = probe(() => sysctl("kern.bootsessionuuid"));
+  if (sessionUuid) return sessionUuid;
+  const bootTime = probe(() => sysctl("kern.boottime"));
+  if (bootTime) return bootTime;
   return BOOT_IDENTITY_FALLBACK;
 }
 
@@ -292,6 +354,12 @@ export function describeLockReason(
       return "the holder shares this instance and is no longer polling (dead pid, or a heartbeat past the staleness window)";
     case "stale-across-namespace":
       return "the holder was recorded by another boot and its heartbeat is past the staleness window";
+    case "stale-legacy":
+      return "the holder was recorded by a build that kept no identity or heartbeat, and its pid is dead, so the channel is free";
+    case "stale-legacy-recycled":
+      return "the holder was recorded by a build that kept no identity or heartbeat, and the live pid now wearing its number started after that record was written, so it is a recycled pid and not the holder";
+    case "held-legacy":
+      return `the holder was recorded by a build that kept no identity or heartbeat, so liveness cannot be read from the record, and its pid is still alive; confirm it is not polling, then remove ${path} (a clean disable releases it)`;
   }
 }
 
@@ -303,6 +371,24 @@ function heartbeatIsCurrent(holder: PollerLockInfo, now: number): boolean {
   return now - (holder.heartbeatAt as number) <= POLLER_HEARTBEAT_STALE_MS;
 }
 
+/**
+ * Start time of a live pid in epoch ms, from `ps`. Undefined when ps cannot say:
+ * an undated live pid is a refusal, never a takeover.
+ */
+function readPidStartedAt(pid: number): number | undefined {
+  try {
+    const out = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (!out) return undefined;
+    const parsed = Date.parse(out);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Take the lock. The rule, in order:
  *
@@ -319,6 +405,12 @@ function heartbeatIsCurrent(holder: PollerLockInfo, now: number): boolean {
  * 7. another boot or no recorded identity → refuse `held-across-namespace`
  *    while the heartbeat is current, acquire `stale-across-namespace` once it
  *    is not, and refuse `stale-unknown` when no heartbeat can be read at all.
+ * 8. a record written before identity existed (`instanceId` absent, so no
+ *    heartbeat ever): a dead pid is evidence enough, so acquire `stale-legacy`;
+ *    a live pid whose process started later than the record was written is a
+ *    recycled pid, so acquire `stale-legacy-recycled`; anything else refuses
+ *    `held-legacy` and names the file, because a live pid we cannot date is the
+ *    one case where guessing either steals a channel or wedges one.
  */
 export function acquirePollerLock(
   path: string,
@@ -326,6 +418,7 @@ export function acquirePollerLock(
   options: AcquirePollerLockOptions = {},
 ): AcquirePollerLockResult {
   const pidAlive = options.pidAlive ?? isPidAlive;
+  const pidStartedAt = options.pidStartedAt ?? readPidStartedAt;
   const now = options.now ?? Date.now;
   const at = now();
   const instanceId = stamp.instanceId ?? resolveInstanceId();
@@ -369,6 +462,27 @@ export function acquirePollerLock(
     return { ok: false, reason: "held-same-instance", holder: existing, path };
   }
 
+  // A record from a build that had no instance identity and no heartbeat. Its
+  // pid is the only field, and it is the field that used to wedge the channel:
+  // the arm below read the absent heartbeat as "cannot tell" and refused
+  // forever, even when the holder had died days earlier.
+  if (existing.instanceId === undefined) {
+    if (existing.pid === stamp.pid) return acquire("same-pid-refresh");
+    if (!pidAlive(existing.pid)) return acquire("stale-legacy");
+    const startedAt = pidStartedAt(existing.pid);
+    const recordedAt = Number.isFinite(existing.startedAt)
+      ? (existing.startedAt as number)
+      : undefined;
+    if (
+      startedAt !== undefined &&
+      recordedAt !== undefined &&
+      startedAt - recordedAt > LEGACY_PID_REUSE_SLACK_MS
+    ) {
+      return acquire("stale-legacy-recycled");
+    }
+    return { ok: false, reason: "held-legacy", holder: existing, path };
+  }
+
   if (!Number.isFinite(existing.heartbeatAt)) {
     return { ok: false, reason: "stale-unknown", holder: existing, path };
   }

package/src/lib/telegram-settings.ts

@@ -9,6 +9,14 @@
  *    `rich: true` (split-to-fit) or an explicit strategy.
  *  - `notifyMaxChars` — craft target + guard for turn-end notifications.
  *    Default 1200: a full readable update, not a 280-char fragment.
+ *  - `pollerAutoStart` — which working directories start the inbound poller by
+ *    themselves. `true` means everywhere, an array means those cwds only, and
+ *    anything else means nowhere: the env var and the tools stay the way in.
+ *    Matching is EXACT, never a prefix: a seat at
+ *    ~/.pi/agent/braid/orchestrator opts in without every worker worktree
+ *    under /private/tmp inheriting the channel with it. A session started by
+ *    hand in a listed directory therefore has a channel with no environment
+ *    variable at all.
  *
  * Degradation: a missing file, unreadable JSON, or an invalid entry (not a
  * finite number ≥ 1) falls back to the default — a bad setting never breaks a
@@ -29,11 +37,15 @@ export const DEFAULT_SEND_MAX_CHARS = 4096;
 /** Fallback notify cap: full readable update, not a tweet-length squeeze. */
 export const DEFAULT_NOTIFY_MAX_CHARS = 1200;
 
+/** Fallback auto-start: no directory reaches the poller until settings names it. */
+export const DEFAULT_POLLER_AUTO_START = false;
+
 interface RawBraidSettings {
   braid?: {
     telegram?: {
       sendMaxChars?: unknown;
       notifyMaxChars?: unknown;
+      pollerAutoStart?: unknown;
     };
   };
 }
@@ -43,6 +55,9 @@ export interface TelegramCaps {
   notifyMaxChars: number;
 }
 
+/** Which directories start the poller on their own: everywhere, a list, or nowhere. */
+export type PollerAutoStart = boolean | string[];
+
 /** A cap must be a positive finite number; anything else → the default. */
 function sanitizeCap(raw: unknown, fallback: number): number {
   return typeof raw === "number" && Number.isFinite(raw) && raw >= 1
@@ -77,6 +92,59 @@ export function readTelegramCaps(
   };
 }
 
+/** Normalize a path for the cwd comparison: no trailing slash, no symlink tail. */
+function normalizeCwd(path: string): string {
+  let out = path.trim();
+  while (out.length > 1 && out.endsWith("/")) out = out.slice(0, -1);
+  return out;
+}
+
+/**
+ * Read `braid.telegram.pollerAutoStart`: `true` (everywhere), an array of
+ * absolute cwds (those only), or `false` when absent or malformed. A relative
+ * entry, an empty string, or any other type is dropped rather than guessed at,
+ * because a mistyped cwd would otherwise start the poller somewhere nobody
+ * asked for.
+ */
+export function readPollerAutoStart(
+  settingsPath: string = SETTINGS_PATH,
+): PollerAutoStart {
+  let parsed: RawBraidSettings | undefined;
+  try {
+    if (existsSync(settingsPath)) {
+      parsed = JSON.parse(
+        readFileSync(settingsPath, "utf8"),
+      ) as RawBraidSettings;
+    }
+  } catch {
+    return DEFAULT_POLLER_AUTO_START;
+  }
+  const raw = parsed?.braid?.telegram?.pollerAutoStart;
+  if (raw === true) return true;
+  if (!Array.isArray(raw)) return DEFAULT_POLLER_AUTO_START;
+  const cwds = raw
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => normalizeCwd(entry))
+    .filter((entry) => entry.startsWith("/"));
+  return cwds;
+}
+
+/**
+ * Does this working directory start the poller by itself? Exact match only.
+ * A subdirectory of a listed cwd does NOT inherit it: the seat opts in for the
+ * directory it runs in, and a worker in a worktree beneath it must not.
+ */
+export function pollerAutoStartFor(
+  cwd: string,
+  settingsPath: string = SETTINGS_PATH,
+): boolean {
+  const setting = readPollerAutoStart(settingsPath);
+  if (setting === true) return true;
+  if (setting === false) return false;
+  const here = normalizeCwd(cwd);
+  return setting.includes(here);
+}
+
 /** Default cap for `telegram_send` plain text (`braid.telegram.sendMaxChars`). */
 export function resolveSendMaxChars(
   settingsPath: string = SETTINGS_PATH,