pi-braid-telegram 0.1.8 → 0.1.10

package/README.md

@@ -53,17 +53,21 @@ 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
 
 - Only whitelisted chats are read, and only owner messages can become a turn.
 - The poller is off by default and only one runs per process.
+- A lock write the filesystem refuses is reported, never fatal: the acquisition answers "not taken"
+  and the running heartbeat records the failure and retries on its schedule. While the write is
+  refused, this holder's heartbeat ages into the takeover window.
 - Voice replies need a TTS source. `source: "none"` refuses the send rather than silently sending
   text.
 - Transcription needs a key. Without one a voice note is still delivered, as the downloaded file,

package/build-info.json

@@ -1,9 +1,9 @@
 {
   "name": "pi-braid-telegram",
-  "version": "0.1.8",
-  "sha": "e1d647e5b1e0c9367bd49bcde72e3a316c908250",
-  "shaShort": "e1d647e5",
+  "version": "0.1.10",
+  "sha": "3a3de965131cd125b58a807b064a43d37b7f466f",
+  "shaShort": "3a3de965",
   "branch": "detached",
   "dirty": false,
-  "packedAt": "2026-11-04T17:20:23.646Z"
+  "packedAt": "2026-11-11T22:45:42.463Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-braid-telegram",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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";
@@ -137,6 +138,7 @@ import {
   type PollerLockInfo,
   type PollerLockRefusalReason,
   type PollerLockTakeoverReason,
+  type PollerLockWriteFailure,
 } from "./lib/poller-lock.js";
 import { isWorkerRole, resolveSessionRole } from "./lib/session-role.js";
 import {
@@ -484,9 +486,10 @@ let pollerWanted = false;
  * singleton), `role-forbidden` (worker session — the seat owns the poller),
  * `lock-held` (another process owns the machine-wide lock; `holder` names it,
  * `refusalReason` says which kind of holder it is, and `path` is the file an
- * operator inspects), or `lock-path-underivable` (no absolute braid root, so
- * the ownership lock has no home). Callers render the reason for their own
- * surface.
+ * operator inspects), `lock-write-failed` (the lock file could not be written,
+ * so no acquisition happened; `failure` carries the errno and the file), or
+ * `lock-path-underivable` (no absolute braid root, so the ownership lock has no
+ * home). Callers render the reason for their own surface.
  */
 type PollerStartRefusal =
   | { started: false; reason: "already-running" }
@@ -498,6 +501,12 @@ type PollerStartRefusal =
       refusalReason: PollerLockRefusalReason;
       path: string;
     }
+  | {
+      started: false;
+      reason: "lock-write-failed";
+      path: string;
+      failure: PollerLockWriteFailure;
+    }
   | { started: false; reason: "lock-path-underivable" };
 type PollerStartOutcome =
   | {
@@ -512,6 +521,9 @@ function describePollerStartRefusal(outcome: PollerStartRefusal): string {
   if (outcome.reason === "lock-held") {
     return `ownership lock held by ${describeLockHolder(outcome.holder)}: ${describeLockReason(outcome.refusalReason, outcome.path)}`;
   }
+  if (outcome.reason === "lock-write-failed") {
+    return `${outcome.failure.message} — the ownership lock was not taken, so this process does not poll`;
+  }
   if (outcome.reason === "role-forbidden") {
     return "worker role — the orchestrator seat owns the Telegram poller";
   }
@@ -598,6 +610,20 @@ function startSingletonPoller(opts: {
     { pidAlive: opts.pidAlive },
   );
   if (!acquired.ok) {
+    // A write that never landed is not a verdict about a holder: the channel may
+    // be free and still unreachable, so the reason names the file and the errno.
+    if (acquired.reason === "write-failed") {
+      log(
+        "warn",
+        `telegram poller not started: ${acquired.failure.message} — the ownership lock was not taken, so this process does not poll`,
+      );
+      return {
+        started: false,
+        reason: "lock-write-failed",
+        path: acquired.path,
+        failure: acquired.failure,
+      };
+    }
     log(
       "warn",
       `telegram poller not started: ${describeLockHolder(acquired.holder)} holds the ownership lock — ${describeLockReason(acquired.reason, acquired.path)}`,
@@ -1705,6 +1731,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 +1867,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 +1893,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

@@ -15,6 +15,12 @@
  * that process last proved it was running; the pid is read as evidence only on
  * the boot that wrote it. A recycled pid on one host is the same class, and the
  * same rule covers it.
+ *
+ * A write to the file can also fail: the volume fills, the tree goes read-only,
+ * a permission changes under it. None of that is a verdict about the channel.
+ * The acquire path answers "the lock was not taken", a beat records the failure
+ * and keeps its schedule, and a write that cannot land leaves the previous
+ * record on disk: the file is replaced whole or left as it was.
  */
 
 import { execFileSync } from "node:child_process";
@@ -22,6 +28,7 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  renameSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
@@ -48,7 +55,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
@@ -140,8 +147,32 @@ export type AcquirePollerLockResult =
       holder: PollerLockInfo;
       /** The file the caller should name in a refusal message. */
       path: string;
+    }
+  | {
+      /**
+       * The record could not be written, so nothing was acquired. Not a
+       * verdict about a holder: whoever held the channel may still hold it, and
+       * the file on disk still says who. The caller is not the owner.
+       */
+      ok: false;
+      reason: "write-failed";
+      path: string;
+      failure: PollerLockWriteFailure;
     };
 
+/**
+ * A lock record write that did not land. Returned, never thrown: the three
+ * callers of the write are a start path, an interval callback and an exit hook,
+ * and a throw in any of them ends the process. A filesystem that refused a
+ * timestamp is news about the channel, not a reason to end the seat.
+ */
+export interface PollerLockWriteFailure {
+  /** The errno code the filesystem reported (`ENOSPC`, `EACCES`, `EROFS`, …). */
+  code: string | undefined;
+  /** One sentence for an operator: which file, and what the filesystem said. */
+  message: string;
+}
+
 /** Injectable reads for the acquisition rule (tests supply a fake clock and
  *  process table; the live path uses the machine's). */
 export interface AcquirePollerLockOptions {
@@ -178,30 +209,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;
 }
 
@@ -217,9 +296,51 @@ export function resolveInstanceId(): string {
   return cachedInstanceId;
 }
 
-function writeLock(path: string, info: PollerLockInfo): void {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, JSON.stringify(info));
+/** What a refused write reports: the errno when the filesystem gave one, and a
+ *  sentence that names the file. */
+function describeWriteFailure(
+  path: string,
+  error: unknown,
+): PollerLockWriteFailure {
+  const code = (error as NodeJS.ErrnoException | null)?.code;
+  const detail = error instanceof Error ? error.message : String(error);
+  return {
+    code: typeof code === "string" ? code : undefined,
+    message: `could not write ${path}: ${detail}`,
+  };
+}
+
+/**
+ * Write the record whole or not at all: a staging file beside the target is
+ * renamed over it, so a reader sees either the previous record or the new one.
+ * A direct `writeFileSync` on the target truncates before it writes, which is
+ * how a failed beat could erase the record that says who holds the channel.
+ *
+ * The failure is returned rather than thrown for the same reason it is
+ * recorded: the callers are a timer, a start path and an exit hook, and none of
+ * them may end the process over a file it could not write.
+ */
+function writeLock(
+  path: string,
+  info: PollerLockInfo,
+): PollerLockWriteFailure | undefined {
+  const staging = `${path}.${process.pid}.tmp`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(staging, JSON.stringify(info));
+    renameSync(staging, path);
+    return undefined;
+  } catch (error) {
+    // A staging file that was created but not renamed is this process's to
+    // remove; one that never existed fails this too. The record on disk is
+    // untouched whether this succeeds or not.
+    try {
+      unlinkSync(staging);
+    } catch {
+      // Nothing staged to remove, or the same condition that refused the write.
+    }
+    return describeWriteFailure(path, error);
+  }
 }
 
 // Best-effort release at process exit: the exit hook removes the lock this
@@ -363,6 +484,9 @@ function readPidStartedAt(pid: number): number | undefined {
  *    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.
+ *
+ * A takeover the rule allows still has to reach the disk: when the write fails,
+ * the answer is `write-failed` and this process is not the owner.
  */
 export function acquirePollerLock(
   path: string,
@@ -376,15 +500,24 @@ export function acquirePollerLock(
   const instanceId = stamp.instanceId ?? resolveInstanceId();
   const existing = readPollerLock(path);
 
-  const acquire = (reason: PollerLockTakeoverReason) => {
-    writeLock(path, {
+  const acquire = (
+    reason: PollerLockTakeoverReason,
+  ): AcquirePollerLockResult => {
+    const record: PollerLockInfo = {
       pid: stamp.pid,
       startedAt: stamp.startedAt ?? at,
       instanceId,
       heartbeatAt: at,
       ...(stamp.role === undefined ? {} : { role: stamp.role }),
       ...(stamp.startedBy === undefined ? {} : { startedBy: stamp.startedBy }),
-    });
+    };
+    const failure = writeLock(path, record);
+    // The file on disk still names the previous holder (or no holder at all):
+    // this process did not acquire the channel, so it claims no exit hook and
+    // reports the write rather than dying on it.
+    if (failure !== undefined) {
+      return { ok: false, reason: "write-failed", path, failure };
+    }
     heldLockPath = path;
     installExitRelease();
     return {
@@ -451,26 +584,50 @@ export function acquirePollerLock(
 
 /**
  * Refresh `heartbeatAt` for a lock this process holds. False when the file is
- * gone or names another holder: a beat never rewrites a successor's record.
+ * gone, names another holder, or could not be written: a beat never rewrites a
+ * successor's record, and a write that cannot land reports instead of throwing.
+ * `onWriteFailure` says which of the two false answers this was.
  */
 export function refreshPollerHeartbeat(
   path: string,
-  options: { now?: () => number; pid?: number; instanceId?: string } = {},
+  options: {
+    now?: () => number;
+    pid?: number;
+    instanceId?: string;
+    /** Called with the reason when the beat reached the filesystem and the
+     *  filesystem refused it. Never called for a beat that the ownership rule
+     *  dropped before any write was attempted. */
+    onWriteFailure?: (failure: PollerLockWriteFailure) => void;
+  } = {},
 ): boolean {
   const holder = readPollerLock(path);
   if (!holder) return false;
   const pid = options.pid ?? process.pid;
   const instanceId = options.instanceId ?? resolveInstanceId();
   if (holder.pid !== pid || holder.instanceId !== instanceId) return false;
-  writeLock(path, { ...holder, heartbeatAt: (options.now ?? Date.now)() });
+  const failure = writeLock(path, {
+    ...holder,
+    heartbeatAt: (options.now ?? Date.now)(),
+  });
+  if (failure !== undefined) {
+    options.onWriteFailure?.(failure);
+    return false;
+  }
   return true;
 }
 
 /** One running heartbeat: at most one per process, on one lock file. */
 export interface PollerHeartbeat {
   readonly path: string;
-  /** Refresh now; false once the lock is no longer ours. */
+  /** Refresh now; false when no new stamp reached the file (the lock is no
+   *  longer ours, or the write failed — `lastError` says which). */
   beat(): boolean;
+  /**
+   * Why the last beat wrote nothing, or undefined once a beat lands. A failed
+   * beat is information about the channel: the beat keeps its schedule, and a
+   * later beat that writes clears this.
+   */
+  readonly lastError: PollerLockWriteFailure | undefined;
   /** Stop refreshing. Idempotent. */
   stop(): void;
 }
@@ -483,14 +640,27 @@ let activeHeartbeat:
  * Refresh the lock's heartbeat on an interval. Replaces any heartbeat already
  * running in this process: one lock, one beat. The timer is unref'd: it serves
  * the lock, never the event loop, so it cannot keep a process alive after the
- * poller it belongs to is gone.
+ * poller it belongs to is gone. The beat body cannot throw: its one fallible
+ * operation is the write, and that reports into `lastError`.
  */
 export function startPollerHeartbeat(
   path: string,
   options: { intervalMs?: number; now?: () => number } = {},
 ): PollerHeartbeat {
   stopPollerHeartbeat();
-  const beat = () => refreshPollerHeartbeat(path, { now: options.now });
+  let lastError: PollerLockWriteFailure | undefined;
+  const beat = (): boolean => {
+    let failed: PollerLockWriteFailure | undefined;
+    const written = refreshPollerHeartbeat(path, {
+      now: options.now,
+      onWriteFailure: (failure) => {
+        failed = failure;
+      },
+    });
+    if (failed !== undefined) lastError = failed;
+    else if (written) lastError = undefined;
+    return written;
+  };
   const timer = setInterval(
     beat,
     options.intervalMs ?? POLLER_HEARTBEAT_INTERVAL_MS,
@@ -501,6 +671,9 @@ export function startPollerHeartbeat(
   return {
     path,
     beat,
+    get lastError() {
+      return lastError;
+    },
     stop: () => {
       if (activeHeartbeat === entry) activeHeartbeat = undefined;
       clearInterval(timer);

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,