pi-braid-telegram 0.1.8 → 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.8",
-  "sha": "e1d647e5b1e0c9367bd49bcde72e3a316c908250",
-  "shaShort": "e1d647e5",
+  "version": "0.1.9",
+  "sha": "ced405d5d39735e56ba7b2079c95b75371153e99",
+  "shaShort": "ced405d5",
   "branch": "detached",
   "dirty": false,
-  "packedAt": "2026-11-04T17:20:23.646Z"
+  "packedAt": "2026-11-10T18:51:54.828Z"
 }

package/package.json

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

@@ -48,7 +48,7 @@ export const POLLER_HEARTBEAT_STALE_MS = 30_000;
  */
 const LEGACY_PID_REUSE_SLACK_MS = 60_000;
 
-/** Boot identity recorded when neither the kernel id nor sysctl is readable. */
+/** 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
@@ -178,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;
 }
 

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,