tokenmaxxing 1.7.0 → 1.9.0

package/src/lib/install.ts

@@ -1,8 +1,4 @@
-// Install/uninstall the on-PATH `claude` supervisor wrapper + settings entries.
-// The wrapper is a 2-line `exec ... __supervise "$@"` shim so dispatch never
-// depends on argv0 semantics.
-
-import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { accessSync, appendFileSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { escape } from "es-toolkit";
 import { z } from "zod";
@@ -19,7 +15,6 @@ const InstallOutcomeSchema = z.object({
 });
 export type InstallOutcome = z.infer<typeof InstallOutcomeSchema>;
 
-/** True if our binDir comes before the real claude's dir on PATH. */
 export function isBinDirAhead(): boolean {
   const dirs = (process.env.PATH ?? "").split(":");
   const ourIdx = dirs.indexOf(paths.binDir);
@@ -33,12 +28,8 @@ export function isBinDirAhead(): boolean {
   }
 }
 
-// Optional "1"/"true"/"yes" flag; unset/empty → undefined (feature off).
 const EnvFlagSchema = z.enum(["1", "true", "yes"]).optional().catch(undefined);
 
-/** True when this process is the Nix-packaged CLI (flake startScript sets
- *  TOKENMAXXING_NIX=1; store-path Bun.main is the fallback for wraps that
- *  forget the env). Env overrides parse at the read site. */
 export function isNixPackaged(): boolean {
   if (EnvFlagSchema.parse(process.env.TOKENMAXXING_NIX) != null) return true;
   try {
@@ -48,17 +39,38 @@ export function isNixPackaged(): boolean {
   }
 }
 
-/** True when a Nix module owns the periodic check timer; init must not write
- *  a second imperative unit. */
 export function skipImperativeTimer(): boolean {
   return EnvFlagSchema.parse(process.env.TOKENMAXXING_SKIP_TIMER) != null;
 }
 
-/** Nix supervisor shim: prefer a PATH-stable `tokenmaxxing` (profile /
- *  current-system, excluding this binDir) so upgrades/GC of an old store
- *  generation stay reachable; fall back to bun+entry for the rare
- *  `nix run ... -- init` case where nothing is on PATH yet (works until that
- *  generation is GC'd — docs steer users to `nix profile install` first). */
+function isNixStorePath(path: string): boolean {
+  return path === "/nix/store" || path.startsWith("/nix/store/");
+}
+
+function isEacces(e: unknown): boolean {
+  return typeof e === "object" && e != null && "code" in e && e.code === "EACCES";
+}
+
+function cannotWriteRcTarget(target: string): boolean {
+  if (EnvFlagSchema.parse(process.env.TOKENMAXXING_SKIP_SHELL_RC) != null) return true;
+  if (isNixStorePath(target)) return true;
+  if (!existsSync(target)) return false;
+  try {
+    accessSync(target, constants.W_OK);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+export function managedShellRcSkipLines(): { headline: string; detail: string; exportLine: string } {
+  return {
+    headline: "shell rc is managed (Home Manager / nix-store) - PATH was not auto-edited",
+    detail: `put ${paths.binDir} on PATH via home.sessionPath (programs.tokenmaxxing Home Manager module sets this), e.g.`,
+    exportLine: `home.sessionPath = [ "${paths.binDir}" ];`,
+  };
+}
+
 function nixSupervisorShim(bun: string, entry: string): string {
   return `#!/bin/sh
 dir=$(CDPATH= cd -- "$(dirname "$0")" && pwd)
@@ -81,11 +93,7 @@ exec ${JSON.stringify(bun)} run ${JSON.stringify(entry)} "$@"
 
 export function installSupervisor(): InstallOutcome {
   mkdirSync(paths.binDir, { recursive: true });
-  const target = installedBin(); // binDir/tokenmaxxing
-  // Resolve the entry through the global-bin symlink (bun add -g links
-  // ~/.bun/bin/tokenmaxxing → the package's src/main.ts) so the shim points
-  // into the installed package tree, where its imports resolve. Nix shims
-  // prefer PATH first (see nixSupervisorShim).
+  const target = installedBin();
   const entry = realpathSync(Bun.main);
   if (isNixPackaged()) {
     writeFileAtomic(target, nixSupervisorShim(process.execPath, entry), 0o755);
@@ -93,9 +101,7 @@ export function installSupervisor(): InstallOutcome {
     writeFileAtomic(target, `#!/bin/sh\nexec ${JSON.stringify(process.execPath)} run ${JSON.stringify(entry)} "$@"\n`, 0o755);
   }
 
-  // the on-PATH `claude` wrapper
   writeFileAtomic(paths.supervisorLink, `#!/bin/sh\nexec ${JSON.stringify(target)} __supervise "$@"\n`, 0o755);
-  // the `xx` short alias → tokenmaxxing
   writeFileAtomic(join(paths.binDir, "xx"), `#!/bin/sh\nexec ${JSON.stringify(target)} "$@"\n`, 0o755);
 
   installSettings();
@@ -107,14 +113,6 @@ export function installSupervisor(): InstallOutcome {
   };
 }
 
-// ---- codex supervisor + Stop hook -------------------------------------------
-
-/** Codex hook declarations we merge into. The FILE nests the event map under a
- *  `hooks` field (`struct HooksFile { description?, hooks }`, binary-verified
- *  0.144.4 after a live parse failure proved the docs' claude-style top-level
- *  event map wrong: "unknown field Stop, expected description or hooks").
- *  Loose everywhere: every other event and every foreign Stop entry rides
- *  along verbatim. */
 const CodexHookEventsSchema = z.looseObject({
   Stop: z.array(z.looseObject({ hooks: z.array(z.looseObject({ command: z.string().optional() })).default([]) })).default([]),
 });
@@ -126,20 +124,9 @@ const CodexHooksFileSchema = z.looseObject({
 const CODEX_STOP_HOOK_SUBCOMMAND = "__codex-stop-hook";
 
 function codexStopHookCommand(): string {
-  // Quoted like the claude shim commands: an install path with a space would
-  // otherwise mis-split and the hook would silently never run.
   return `${JSON.stringify(installedBin())} ${CODEX_STOP_HOOK_SUBCOMMAND}`;
 }
 
-/** Idempotently install the tokenmaxxing Stop entry in ~/.codex/hooks.json,
- *  preserving every other declaration. Codex skips new hooks until the user
- *  trusts them via /hooks (trust is recorded against the hook's hash), so the
- *  caller must surface that step. */
-/** Surgical WITHIN groups, ownership verified structurally (closing-review
- *  catch, mirroring settings.ts's removeHook fix): the old whole-group filter
- *  deleted a foreign hook the user had appended into our group - the natural
- *  edit, since install writes exactly one group - and its includes() match
- *  claimed any command merely mentioning the subcommand. */
 function withoutOurCodexStopHooks(groups: { hooks: { type?: string; command?: string }[] }[]): typeof groups {
   return groups
     .map((group) => ({ ...group, hooks: group.hooks.filter((hook) => !isOurHookCommand(hook.command ?? "", CODEX_STOP_HOOK_SUBCOMMAND)) }))
@@ -181,7 +168,6 @@ export function codexSupervisorLink(): string {
   return join(paths.binDir, "codex");
 }
 
-/** The on-PATH `codex` wrapper + the Stop hook declaration. */
 export function installCodexSupervisor(): void {
   mkdirSync(paths.binDir, { recursive: true });
   writeFileAtomic(codexSupervisorLink(), `#!/bin/sh\nexec ${JSON.stringify(installedBin())} __supervise-codex "$@"\n`, 0o755);
@@ -193,26 +179,18 @@ export function uninstallCodexSupervisor(): void {
   if (existsSync(codexSupervisorLink())) rmSync(codexSupervisorLink(), { force: true });
 }
 
-// ---- periodic `check` timer ------------------------------------------------
-// The hooks evaluate only at turn boundaries; one long agentic turn can burn a
-// window from healthy to depleted with zero boundaries (2026-07-10 incident).
-// A timer closes that gap: launchd on macOS, a systemd user timer on Linux.
-
-const CHECK_INTERVAL_S = 180;
+const CHECK_INTERVAL_S = 60;
 const LAUNCHD_LABEL = "com.tokenmaxxing.check";
 
 function launchdPlist(): string {
   return join(paths.launchdAgentsDir, `${LAUNCHD_LABEL}.plist`);
 }
 
-/** `gui/<uid>` launchd domain, or null when the platform has no getuid. */
 function launchdDomain(): string | null {
   const uid = process.getuid?.();
   return uid == null ? null : `gui/${uid}`;
 }
 
-/** launchctl/systemctl may be absent (spawnSync throws ENOENT) or hang on a
- *  dead session bus (ssh without lingering) - degrade, never crash or block. */
 function run(cmd: string[]): boolean {
   try {
     return Bun.spawnSync(cmd, { stdout: "ignore", stderr: "ignore", timeout: 10_000 }).exitCode === 0;
@@ -221,12 +199,7 @@ function run(cmd: string[]): boolean {
   }
 }
 
-/** Install + activate the periodic check job. False means the unit files are in
- *  place but activation failed (e.g. systemd user session absent over ssh) -
- *  the caller prints the manual activation step. */
 function installCheckTimer(): boolean {
-  // Nix module owns the timer (TOKENMAXXING_SKIP_TIMER): do not write a second
-  // unit that would double-fire or clobber the declarative one.
   if (skipImperativeTimer()) return true;
 
   if (process.platform === "darwin") {
@@ -238,7 +211,7 @@ function installCheckTimer(): boolean {
 <plist version="1.0">
 <dict>
   <key>Label</key><string>${LAUNCHD_LABEL}</string>
-  <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>check</string></array>
+  <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>check</string><string>--if-due</string></array>
   <key>StartInterval</key><integer>${CHECK_INTERVAL_S}</integer>
   <key>StandardOutPath</key><string>/dev/null</string>
   <key>StandardErrorPath</key><string>${escape(join(paths.home, "check.stderr.log"))}</string>
@@ -249,13 +222,11 @@ function installCheckTimer(): boolean {
     );
     const domain = launchdDomain();
     if (domain == null) return false;
-    run(["launchctl", "bootout", `${domain}/${LAUNCHD_LABEL}`]); // reload a changed plist
-    // bootstrap can lose a benign race with an in-flight bootout; loaded is loaded.
+    run(["launchctl", "bootout", `${domain}/${LAUNCHD_LABEL}`]);
     return run(["launchctl", "bootstrap", domain, plist]) || checkTimerHealthy();
   }
 
-  // systemd: quote the path and escape `%` (unit-file specifier character).
-  const exec = `"${installedBin().replaceAll("%", "%%")}" check`;
+  const exec = `"${installedBin().replaceAll("%", "%%")}" check --if-due`;
   writeFileAtomic(
     join(paths.systemdUserDir, "tokenmaxxing-check.service"),
     `[Unit]
@@ -275,7 +246,7 @@ Description=tokenmaxxing periodic account-switch check
 [Timer]
 OnBootSec=60
 OnUnitActiveSec=${CHECK_INTERVAL_S}
-AccuracySec=30
+AccuracySec=5
 
 [Install]
 WantedBy=timers.target
@@ -288,7 +259,6 @@ WantedBy=timers.target
   );
 }
 
-/** The manual activation command for an unloaded timer, per platform. */
 export function timerActivationHint(): string {
   if (process.platform === "darwin") {
     return `launchctl bootstrap gui/$(id -u) ${launchdPlist()}`;
@@ -296,10 +266,7 @@ export function timerActivationHint(): string {
   return "systemctl --user daemon-reload && systemctl --user enable --now tokenmaxxing-check.timer";
 }
 
-/** True when the timer unit exists AND the service manager reports it loaded. */
 export function checkTimerHealthy(): boolean {
-  // Declarative Nix timer: init wrote nothing; doctor must not demand the
-  // imperative unit.
   if (skipImperativeTimer()) return true;
   if (process.platform === "darwin") {
     const domain = launchdDomain();
@@ -311,7 +278,6 @@ export function checkTimerHealthy(): boolean {
   );
 }
 
-/** The manual deactivation command for a still-loaded timer, per platform. */
 export function timerDeactivationHint(): string {
   if (process.platform === "darwin") {
     return `launchctl bootout gui/$(id -u)/${LAUNCHD_LABEL}`;
@@ -319,10 +285,6 @@ export function timerDeactivationHint(): string {
   return "systemctl --user disable --now tokenmaxxing-check.timer";
 }
 
-/** Is the launchd check job loaded? Exit contract verified on this machine
- *  (macOS 26, 2026-07-20): `launchctl print` exits 0 for a loaded job and 113
- *  for a missing one. Anything else - including a spawn failure or timeout -
- *  is "unavailable": an unanswerable probe must never read as "not loaded". */
 function launchdJobLoaded(): "loaded" | "not-loaded" | "unavailable" {
   const domain = launchdDomain();
   if (domain == null) return "unavailable";
@@ -335,15 +297,6 @@ function launchdJobLoaded(): "loaded" | "not-loaded" | "unavailable" {
   }
 }
 
-/** Is the systemd check timer active? Classification goes by the state
- *  string, never the exit code: systemctl(1) documents only "0 if at least
- *  one is active, non-zero otherwise" for is-active, but guarantees "unless
- *  --quiet is specified, this will also print the current unit state to
- *  standard output" (verified against the systemd manpage 2026-07-20). The
- *  failure mode is container-verified (ubuntu:24.04 systemd, no user bus,
- *  2026-07-20): a dead session bus prints NOTHING to stdout ("Failed to
- *  connect to bus" goes to stderr, exit 1), so an empty or unrecognized
- *  stdout is "unavailable" - "cannot ask" never reads as "inactive". */
 function systemdTimerActive(): "active" | "not-active" | "unavailable" {
   try {
     const proc = Bun.spawnSync(["systemctl", "--user", "is-active", "tokenmaxxing-check.timer"], { stdout: "pipe", stderr: "ignore", timeout: 10_000 });
@@ -356,14 +309,7 @@ function systemdTimerActive(): "active" | "not-active" | "unavailable" {
   }
 }
 
-/** True when the job is verifiably no longer loaded. A swallowed bootout
- *  failure once meant a half-uninstalled state kept firing `tokenmaxxing
- *  check` every 180s against a package that may be gone, silently
- *  (closing-review catch): deactivation is checked, not assumed - a job seen
- *  loaded must deactivate successfully, and an unanswerable probe (service
- *  manager unusable) reports false rather than pretending it is gone. */
 function uninstallCheckTimer(): boolean {
-  // Nix owns the timer: do not bootout/disable the declarative unit.
   if (skipImperativeTimer()) return true;
   if (process.platform === "darwin") {
     const domain = launchdDomain();
@@ -380,8 +326,6 @@ function uninstallCheckTimer(): boolean {
   return deactivated;
 }
 
-/** The rc file of the user's login shell, or null when the shell is unknown.
- *  Overridable for hermetic tests. */
 export function shellRcPath(): string | null {
   const override = process.env.TOKENMAXXING_SHELL_RC;
   if (override && override.length > 0) return override;
@@ -393,54 +337,45 @@ export function shellRcPath(): string | null {
 
 const PATH_LINE_MARK = "# tokenmaxxing PATH";
 
-/** Idempotently append the supervisor-bin PATH line to `rc` (created if absent).
- *  A pre-existing hand-added line for the bin dir also counts as present. */
-export function ensurePathInRc(rc: string): "added" | "present" {
+export function ensurePathInRc(rc: string): "added" | "present" | "skipped" {
   const dir = paths.binDir.startsWith(`${HOME}/`) ? `$HOME${paths.binDir.slice(HOME.length)}` : paths.binDir;
-  // Write through a dotfile-managed symlink, never over it: writeFileAtomic
-  // renames a sibling temp over its target, which would replace the link with
-  // a plain file while the dotfiles target keeps the stale line (PR #36
-  // second-round catch).
   const target = existsSync(rc) ? realpathSync(rc) : rc;
   const current = existsSync(target) ? readFileSync(target, "utf8") : "";
   const isCurrentExport = (line: string) => line.includes(`${paths.binDir}:`) || line.includes(`${dir}:`);
   const lines = current === "" ? [] : current.split("\n");
-  // A marked line for a DIFFERENT dir is removed even when the current dir is
-  // also exported: PATH prepends stack, so a stale marked line BELOW the
-  // current one would still win resolution - the recursion incident's exact
-  // vector (closing-review catch + PR #36 second-round catch). A bare marker
-  // check alone once kept such a line alive after a TOKENMAXXING_HOME
-  // relocation.
   const kept = lines.filter((line) => isCurrentExport(line) || !line.includes(PATH_LINE_MARK));
   if (kept.length !== lines.length) {
+    if (cannotWriteRcTarget(target)) return "skipped";
     const body = kept.join("\n");
     const sep0 = body === "" || body.endsWith("\n") ? "" : "\n";
     const addition = kept.some(isCurrentExport) ? "" : `export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`;
-    // preserve the rc's own mode: writeFileAtomic defaults to 0600, which
-    // would silently tighten a normally 0644 shell rc (PR #36 review catch)
-    writeFileAtomic(target, `${body}${sep0}${addition}`, statSync(target).mode & 0o777);
+    try {
+      writeFileAtomic(target, `${body}${sep0}${addition}`, statSync(target).mode & 0o777);
+    } catch (e) {
+      if (isEacces(e)) return "skipped";
+      throw e;
+    }
     return "added";
   }
   if (lines.some(isCurrentExport)) return "present";
+  if (cannotWriteRcTarget(target)) return "skipped";
   const sep = current === "" || current.endsWith("\n") ? "" : "\n";
-  appendFileSync(target, `${sep}export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`);
+  try {
+    appendFileSync(target, `${sep}export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`);
+  } catch (e) {
+    if (isEacces(e)) return "skipped";
+    throw e;
+  }
   return "added";
 }
 
 const ShellShadowerSchema = z.object({
-  /** shadow: a `claude` alias/function hides the wrapper entirely.
-   *  bypass: another alias (e.g. `cc`, `cco`) hardcodes an absolute path to a
-   *  claude binary, so launches through it skip supervision. */
   kind: z.enum(["shadow", "bypass"]),
   name: z.string(),
   line: z.string(),
 });
 export type ShellShadower = z.infer<typeof ShellShadowerSchema>;
 
-/** Scan shell-rc text for aliases/functions that shadow `claude` or hardcode a
- *  path to a claude binary. Aliases whose body starts with plain `claude` are
- *  fine (they expand through PATH into the wrapper); an absolute path is not.
- *  Lines referencing the wrapper itself are deliberate and skipped. */
 export function findClaudeShadowers(rcText: string): ShellShadower[] {
   const out: ShellShadower[] = [];
   const absClaude = /(?:^|[\s"'=])(\/[^\s"']*\/claude)(?:[\s"']|$)/;
@@ -463,21 +398,19 @@ export function findClaudeShadowers(rcText: string): ShellShadower[] {
   return out;
 }
 
-/** Remove ONLY the marker-tagged PATH line this tool added; a hand-added
- *  PATH entry without the marker is the user's own. A stale `# tokenmaxxing
- *  PATH` line pointing at an emptied binDir is exactly how the supervisor
- *  recursion incident started (.memory/supervisor-recursion-guards.md), so
- *  uninstall must not leave one behind (closing-review catch).
- *  Returns true when a line was removed. */
 export function removePathFromRc(rc: string): boolean {
   if (!existsSync(rc)) return false;
-  // same symlink + mode treatment as ensurePathInRc: write through a
-  // dotfile-managed link, keep the rc's own permissions (PR #36 catches)
   const target = realpathSync(rc);
   const lines = readFileSync(target, "utf8").split("\n");
   const kept = lines.filter((line) => !line.includes(PATH_LINE_MARK));
   if (kept.length === lines.length) return false;
-  writeFileAtomic(target, kept.join("\n"), statSync(target).mode & 0o777);
+  if (cannotWriteRcTarget(target)) return false;
+  try {
+    writeFileAtomic(target, kept.join("\n"), statSync(target).mode & 0o777);
+  } catch (e) {
+    if (isEacces(e)) return false;
+    throw e;
+  }
   return true;
 }
 

package/src/lib/keychain.ts

@@ -1,42 +1,19 @@
-// macOS login-keychain generic-password I/O, ps-safe. The darwin backend of
-// credstore.ts - construct targets there, not here.
-//   READ  : `security find-generic-password -w`  → secret only ever in stdout.
-//   WRITE : pipe an `add-generic-password -U ... -w <secret>` line into `security -i`
-//           over STDIN - the secret never appears in any process's argv (verified).
-// The service/account are non-secret and may sit in argv.
-
 import { z } from "zod";
 
 const KeychainTargetSchema = z.object({ service: z.string(), account: z.string() });
 export type KeychainTarget = z.infer<typeof KeychainTargetSchema>;
 
 const SECURITY = "/usr/bin/security";
-// security(1) interactive mode has a 4096-byte line buffer. The gate below
-// measures the ASSEMBLED line against this (with margin), never the raw
-// secret: quoteDouble expansion (one byte per `"`/`\` when the blob contains
-// an apostrophe) once pushed a raw-length-passing line over the buffer, which
-// SPLITS the line - the write exits 1 ("unknown command" for the spilled
-// remainder) AND the item is left holding a TRUNCATED secret (empirically
-// verified 2026-07-20: a 3667-byte secret assembling to a 5574-byte line
-// corrupted the item to its first 2682 bytes before the error surfaced).
 const INTERACTIVE_MAX_LINE = 4000;
 
-/** Double-quote + backslash-escape for security(1)'s interactive tokenizer. */
 function quoteDouble(s: string): string {
   return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
 
-/** Wrap a value for the `-i` line. Single-quote when possible (blob has no `'`). */
 function quoteValue(s: string): string {
   return s.includes("'") ? quoteDouble(s) : `'${s}'`;
 }
 
-/** Read an item's password blob. Returns null ONLY when the item verifiably
- *  does not exist (exit 44, errSecItemNotFound - empirically pinned on this
- *  Mac 2026-07-20). Every other failure THROWS: a locked keychain or denied
- *  ACL prompt reading as "absent" silently disarmed every fail-closed
- *  live-owner guard and the mandatory pre-swap harvest, all of which key off
- *  a null read (closing-review catch). stderr never carries the secret. */
 export async function readItem(t: KeychainTarget): Promise<string | null> {
   const p = Bun.spawn([SECURITY, "find-generic-password", "-s", t.service, "-a", t.account, "-w"], {
     stdout: "pipe",
@@ -48,11 +25,9 @@ export async function readItem(t: KeychainTarget): Promise<string | null> {
   if (p.exitCode !== 0) {
     throw new Error(`keychain read failed (exit ${p.exitCode}): ${err.trim().slice(0, 200)} - a locked keychain or denied ACL must fail loudly, never read as absent`);
   }
-  return out.replace(/\n$/, ""); // security appends exactly one trailing newline
+  return out.replace(/\n$/, "");
 }
 
-/** The full `security -i` line for a write; its LENGTH is the argv-fallback
- *  gate, so it is assembled once, here. */
 function interactiveLine(t: KeychainTarget, secret: string): string {
   return (
     `add-generic-password -U -a ${quoteDouble(t.account)} -s ${quoteDouble(t.service)} ` +
@@ -60,8 +35,6 @@ function interactiveLine(t: KeychainTarget, secret: string): string {
   );
 }
 
-/** ps-safe write: the command line + secret arrive on stdin, never in argv.
- *  The caller guarantees the encoded line fits the interactive buffer. */
 async function writeViaInteractive(encodedLine: Uint8Array): Promise<void> {
   const p = Bun.spawn([SECURITY, "-i"], {
     stdin: encodedLine,
@@ -73,9 +46,6 @@ async function writeViaInteractive(encodedLine: Uint8Array): Promise<void> {
   if (p.exitCode !== 0) throw new Error(`keychain write (interactive) failed (exit ${p.exitCode}): ${err.trim()}`);
 }
 
-/** Fallback for blobs over the interactive line limit. The secret is briefly
- *  visible in `ps` for this one short-lived process - used only when the payload
- *  (e.g. a live blob with lots of MCP OAuth state) exceeds ~4KB. */
 async function writeViaArgv(t: KeychainTarget, secret: string): Promise<void> {
   const p = Bun.spawn([SECURITY, "add-generic-password", "-U", "-a", t.account, "-s", t.service, "-w", secret], {
     stdout: "ignore",
@@ -86,20 +56,12 @@ async function writeViaArgv(t: KeychainTarget, secret: string): Promise<void> {
   if (p.exitCode !== 0) throw new Error(`keychain write (argv) failed (exit ${p.exitCode}): ${err.trim()}`);
 }
 
-/** Create-or-update an item (`-U`) with `secret` as its password. Prefers the
- *  ps-safe stdin path; falls back to argv when the ASSEMBLED interactive line
- *  would exceed the buffer (see INTERACTIVE_MAX_LINE - gating on the raw
- *  secret length let quote expansion corrupt the item). Throws on failure. */
 export async function writeItem(t: KeychainTarget, secret: string): Promise<void> {
-  // measured in UTF-8 BYTES, the unit the stdin buffer actually consumes:
-  // String.length counts UTF-16 code units and under-counts multibyte
-  // characters (cubic review catch, PR #35).
   const encoded = new TextEncoder().encode(interactiveLine(t, secret));
   if (encoded.length <= INTERACTIVE_MAX_LINE) return writeViaInteractive(encoded);
   return writeViaArgv(t, secret);
 }
 
-/** Delete an item. Returns true if it existed and was removed. */
 export async function deleteItem(t: KeychainTarget): Promise<boolean> {
   const p = Bun.spawn([SECURITY, "delete-generic-password", "-s", t.service, "-a", t.account], {
     stdout: "ignore",

package/src/lib/lock.ts

@@ -1,34 +1,17 @@
-// Cross-process advisory locking via flock(2) through bun:ffi on a real file
-// descriptor (macOS ships no flock(1) binary, and one codepath serves both
-// platforms). The lock is released when we close the fd (explicitly or on
-// process exit).
-//
-// The acquire is NON-BLOCKING (LOCK_EX|LOCK_NB) with an async retry loop: a
-// blocking LOCK_EX from this runtime freezes the whole event loop.
-// EWOULDBLOCK is told apart from real failures via errno, so a bad fd still
-// fails fast instead of spinning.
-
 import { closeSync, mkdirSync, openSync } from "node:fs";
 import { dirname } from "node:path";
 import { dlopen, FFIType, read } from "bun:ffi";
 import { delay } from "es-toolkit";
 
-// sys/file.h (identical on darwin + linux): LOCK_SH=1 LOCK_EX=2 LOCK_NB=4 LOCK_UN=8
 const LOCK_EX = 2;
 const LOCK_NB = 4;
 const LOCK_UN = 8;
-// errno.h: EWOULDBLOCK/EAGAIN is 35 on darwin, 11 on linux; EINTR is 4 on both.
 const EAGAIN = process.platform === "darwin" ? 35 : 11;
 const EINTR = 4;
 const RETRY_MS = 75;
 
 const FLOCK_DEF = { flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 } } as const;
 
-// darwin: flock(2) + __error live in libSystem; the bare name resolves via the
-// dyld shared cache even though no physical .dylib exists on disk (verified
-// 2026-07-08). linux: glibc's libc.so.6 + __errno_location (verified
-// in-container 2026-07-09, arm64). Exactly one verified path per platform -
-// a broken environment fails fast instead of falling through a guess list.
 function loadLibc() {
   if (process.platform === "darwin") {
     const lib = dlopen("libSystem.B.dylib", { ...FLOCK_DEF, __error: { args: [], returns: FFIType.ptr } });
@@ -50,12 +33,6 @@ function currentErrno(): number {
   return p == null ? -1 : read.i32(p, 0);
 }
 
-/**
- * Acquire an exclusive advisory lock on `lockPath`, waiting (without blocking
- * the event loop) until available. Returns a handle whose release() drops the
- * lock. The lock is fd-scoped, so racing hooks in separate processes serialize
- * and same-process actors queue on the retry loop.
- */
 export async function acquireLock(lockPath: string): Promise<{ release: () => void }> {
   mkdirSync(dirname(lockPath), { recursive: true });
   const fd = openSync(lockPath, "a", 0o600);
@@ -85,7 +62,6 @@ export async function acquireLock(lockPath: string): Promise<{ release: () => vo
   return { release };
 }
 
-/** Run `fn` while holding `lockPath`; always releases, even on throw. */
 export async function withLock<T>(lockPath: string, fn: () => Promise<T> | T): Promise<T> {
   const held = await acquireLock(lockPath);
   try {

package/src/lib/log.ts

@@ -1,6 +1,3 @@
-// Append-only logging. NEVER logs secret material - callers must pass only
-// non-secret context (account uuids/emails, percentages, status strings).
-
 import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { z } from "zod";
@@ -8,19 +5,14 @@ import { paths } from "./paths.ts";
 
 const LOG_MAX_BYTES = 5_000_000;
 
-/** Redact anything that looks like a token so an accidental pass-through can't leak. */
 function redact(s: string): string {
   return s
-    // JWT-ish / long opaque tokens
     .replace(/\b(sk-ant-[A-Za-z0-9._-]{6,})/g, "sk-ant-***")
     .replace(/\b([A-Za-z0-9_-]{40,})\b/g, (m) => `${m.slice(0, 4)}...(${m.length})`);
 }
 
 let echo: ((input: { event: string; parts: string }) => void) | null = null;
 
-/** Tee every subsequent log() line to a terminal printer. Off by default
- *  (hooks and the statusline own their stdout protocol). The printer receives
- *  the same redacted parts the file line gets. */
 export function setLogEcho(input: { printer: (input: { event: string; parts: string }) => void }): void {
   echo = input.printer;
 }
@@ -35,20 +27,14 @@ export function log(event: string, fields: Record<string, unknown> = {}): void {
       })
       .join(" ");
     mkdirSync(dirname(paths.logFile), { recursive: true });
-    // Rotation cap: the check timer logs every 180s, so an uncapped
-    // append-only file grows forever on a live install. One .old generation
-    // bounds total disk at ~2x the cap; older history is disposable diagnostics.
     if (existsSync(paths.logFile) && statSync(paths.logFile).size > LOG_MAX_BYTES) {
       renameSync(paths.logFile, `${paths.logFile}.old`);
     }
     appendFileSync(paths.logFile, `${new Date().toISOString()} ${event} ${line}\n`);
   } catch {
-    // logging must never throw into a hook / supervisor path
   }
-  // separate from the file sink: an unwritable log file must not also silence the echo.
   try {
     echo?.({ event, parts: line });
   } catch {
-    // the echo printer must never throw into a caller path
   }
 }