@tokenfactory/acc-runner 0.44.7 → 0.44.9

package/scripts/com.tokenfactory.acc-runner.plist

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  macOS LaunchAgent template for `acc-runner watch`.
+
+  Tokens replaced by install-launchd.sh:
+    __CAFFEINATE_PATH__   absolute path to /usr/bin/caffeinate
+    __NODE_INVOKER__      absolute path to the node@22 binary (or
+                          /usr/bin/env when the CLI is a shell shim that
+                          must resolve node itself through PATH below)
+    __ACC_RUNNER_PATH__   absolute path to the acc-runner CLI entrypoint
+    __NODE_BIN_DIR__      bin dir of node@22, e.g. /opt/homebrew/opt/node@22/bin
+    __ACC_ENV_ENTRIES__   marker line; replaced by the resolved ACC_* env
+                          entries (ACC_TARGET_REPO, ACC_REPO_PATH,
+                          ACC_RUNNER_REPOS, ACC_RUNNER_CONCURRENCY), or by
+                          nothing when none are set
+    __HOME__              operator's $HOME
+
+  Why PATH and the ACC_* vars are baked in rather than inherited:
+    launchd does NOT source ~/.zshrc or ~/.zprofile. A job started at login
+    gets a bare PATH (/usr/bin:/bin:/usr/sbin:/sbin) and none of the shell's
+    exports. On the fleet host ~/.zprofile is what puts node@20 on PATH, so
+    an inherited-PATH agent would run the runner under the wrong node (or no
+    node at all) and the repo's node-22 pin (docs/acc/NODE_VERSION_PIN.md)
+    would be violated on every pre-PR gate. node@22's bin dir is therefore
+    FIRST on the PATH string below, ahead of /opt/homebrew/bin where the
+    default-linked (node@20) symlink lives.
+
+  Secrets are deliberately NOT baked in. The plist is a plain 0644 file in
+  ~/Library/LaunchAgents; the runner's OAuth tokens stay in the OS keychain
+  via keytar, and ANTHROPIC_API_KEY belongs in the keychain-backed config,
+  never here.
+
+  Behavior:
+    - caffeinate -dis keeps display, idle, system from sleeping while
+      acc-runner is running. Released the moment caffeinate exits, so
+      the lid-close behavior of the operator's Mac is unchanged when
+      the agent is unloaded.
+    - RunAtLoad=true starts the runner at login (and therefore after a
+      reboot, once the operator's session opens).
+    - KeepAlive=true auto-restarts on crash. launchd applies its
+      exponential throttle (default 10s, raised here to 60s) so a
+      crash-loop only restarts once a minute.
+    - StandardOut/ErrorPath capture the watch loop's stdio so the
+      doctor command and ops runbook have a single log location.
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.tokenfactory.acc-runner</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>__CAFFEINATE_PATH__</string>
+    <string>-dis</string>
+    <string>__NODE_INVOKER__</string>
+    <string>__ACC_RUNNER_PATH__</string>
+    <string>watch</string>
+  </array>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>ThrottleInterval</key>
+  <integer>60</integer>
+
+  <key>ProcessType</key>
+  <string>Interactive</string>
+
+  <key>StandardOutPath</key>
+  <string>__HOME__/Library/Logs/acc-runner.out.log</string>
+
+  <key>StandardErrorPath</key>
+  <string>__HOME__/Library/Logs/acc-runner.err.log</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>__HOME__</string>
+    <key>PATH</key>
+    <string>__NODE_BIN_DIR__:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    __ACC_ENV_ENTRIES__
+  </dict>
+
+  <key>WorkingDirectory</key>
+  <string>__HOME__</string>
+</dict>
+</plist>

package/scripts/gen-build-info.d.mts

@@ -0,0 +1,3 @@
+// Type surface for the provenance helper in gen-build-info.mjs, so the unit
+// test can import it under NodeNext + strict without allowJs.
+export function commitField(sha: string, statusPorcelain: string): string;

package/scripts/gen-build-info.mjs

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const generatedTs = path.join(root, "src", "build-info.generated.ts");
+const generatedJs = path.join(root, "dist", "build-info.generated.js");
+
+function git(args) {
+  const r = spawnSync("git", args, { cwd: root, encoding: "utf8" });
+  return r.status === 0 ? r.stdout.trim() : "unknown";
+}
+
+// AC1: HEAD alone can't prove the built tree was clean (a hand-built tree with
+// uncommitted edits still points at a clean commit), so suffix `-dirty` for an
+// unclean tree. Exclude the generated file itself: the `pre` step rewrites it,
+// so by `post` it is ALWAYS modified and counting it would pin every build to
+// `-dirty` and destroy the signal. The dist hash already captures built output.
+export function commitField(sha, statusPorcelain) {
+  if (sha === "unknown") return sha;
+  const dirty =
+    statusPorcelain !== "" &&
+    statusPorcelain !== "unknown" &&
+    statusPorcelain
+      .split("\n")
+      .some((line) => line.trim() !== "" && !line.includes("build-info.generated.ts"));
+  return dirty ? `${sha}-dirty` : sha;
+}
+
+function gitCommit() {
+  return commitField(git(["rev-parse", "HEAD"]), git(["status", "--porcelain"]));
+}
+
+async function distHash() {
+  const dist = path.join(root, "dist");
+  const files = [];
+  async function walk(dir) {
+    for (const ent of await readdir(dir, { withFileTypes: true })) {
+      const p = path.join(dir, ent.name);
+      if (ent.isDirectory()) await walk(p);
+      else if (ent.isFile() && !p.endsWith("build-info.generated.js")) files.push(p);
+    }
+  }
+  await walk(dist);
+  const h = createHash("sha256");
+  for (const file of files.sort()) {
+    h.update(path.relative(dist, file));
+    h.update("\0");
+    h.update(await readFile(file));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+
+function ts(commitSha, distSha256) {
+  return `// Generated by scripts/gen-build-info.mjs. Do not edit by hand.\n` +
+    `export const BUILD_COMMIT_SHA = ${JSON.stringify(commitSha)};\n` +
+    `export const BUILD_DIST_SHA256 = ${JSON.stringify(distSha256)};\n`;
+}
+
+// File-writing steps run only when invoked directly (`node …/gen-build-info.mjs
+// pre|post`); importing the module (e.g. from tests) is side-effect free.
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  if (process.argv[2] === "post") {
+    await writeFile(generatedJs, ts(gitCommit(), await distHash()));
+    await writeFile(generatedTs, ts("unknown", "unknown"));
+  } else {
+    await writeFile(generatedTs, ts(gitCommit(), "pending-build"));
+  }
+}

package/scripts/install-launchd.sh

@@ -0,0 +1,235 @@
+#!/usr/bin/env bash
+#
+# Install the acc-runner macOS LaunchAgent so `acc-runner watch` survives
+# reboot, logout and crashes.
+#
+# Renders ./com.tokenfactory.acc-runner.plist into
+# ~/Library/LaunchAgents and loads it via launchctl. Idempotent:
+# re-running unloads any prior copy first.
+#
+# What it bakes into the plist (launchd sources NEITHER ~/.zshrc NOR
+# ~/.zprofile, so nothing can be inherited):
+#   - PATH with node@22's bin dir FIRST, ahead of /opt/homebrew/bin where
+#     the .zprofile-pinned node@20 symlink lives. The repo pin is node 22
+#     (docs/acc/NODE_VERSION_PIN.md) and the pre-PR gate runs under it.
+#   - the ACC_* config vars: ACC_TARGET_REPO, ACC_REPO_PATH,
+#     ACC_RUNNER_REPOS, ACC_RUNNER_CONCURRENCY.
+#
+# Value resolution, per variable (first hit wins; unresolved = omitted,
+# so the runner's own config.json/server defaults still apply):
+#   1. the environment this script is invoked with
+#   2. $ACC_RUNNER_LAUNCHD_ENV (default ~/.config/acc-runner/launchd.env),
+#      a KEY=VALUE file
+#   3. ~/.config/acc-runner/config.json ("repo-path", "repos")
+# ACC_RUNNER_CONCURRENCY is never defaulted: an env value outranks the
+# operator's server-set concurrency, so it is baked only when explicit.
+#
+# Secrets are never written to the plist — tokens live in the OS keychain.
+#
+# Usage:
+#   packages/acc-runner/scripts/install-launchd.sh
+#   packages/acc-runner/scripts/install-launchd.sh --no-load   # render only
+#   packages/acc-runner/scripts/install-launchd.sh --help
+#
+# Rollback: packages/acc-runner/scripts/uninstall-launchd.sh
+# Docs:     docs/acc/RUNNER_LAUNCHD.md
+
+set -euo pipefail
+
+NODE_MAJOR=22
+LABEL="com.tokenfactory.acc-runner"
+DO_LOAD=1
+
+for arg in "$@"; do
+  case "$arg" in
+    --no-load) DO_LOAD=0 ;;
+    -h|--help) awk 'NR>=2 { if ($0 !~ /^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) echo "install-launchd.sh: unknown option '$arg' (see --help)" >&2; exit 2 ;;
+  esac
+done
+
+if [[ "$(uname)" != "Darwin" ]]; then
+  echo "install-launchd.sh: macOS-only (uname=$(uname))" >&2
+  exit 1
+fi
+
+CAFFEINATE_PATH="$(command -v caffeinate || true)"
+if [[ -z "$CAFFEINATE_PATH" ]]; then
+  echo "install-launchd.sh: caffeinate not found in PATH" >&2
+  exit 1
+fi
+
+ACC_RUNNER_PATH="$(command -v acc-runner || true)"
+if [[ -z "$ACC_RUNNER_PATH" ]]; then
+  echo "install-launchd.sh: acc-runner not found in PATH" >&2
+  echo "  install globally first: pnpm add -g @tokenfactory/acc-runner" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TEMPLATE="$SCRIPT_DIR/com.tokenfactory.acc-runner.plist"
+if [[ ! -f "$TEMPLATE" ]]; then
+  echo "install-launchd.sh: template missing at $TEMPLATE" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------- node@22
+
+node_major_of() { "$1" -v 2>/dev/null | sed -n 's/^v\([0-9][0-9]*\).*/\1/p'; }
+
+resolve_node_bin_dir() {
+  local candidates=() d cur
+  [[ -n "${ACC_RUNNER_NODE_BIN_DIR:-}" ]] && candidates+=("$ACC_RUNNER_NODE_BIN_DIR")
+  candidates+=("/opt/homebrew/opt/node@${NODE_MAJOR}/bin" "/usr/local/opt/node@${NODE_MAJOR}/bin")
+  # Version managers found on runner hosts. Unmatched globs stay literal and
+  # are dropped by the -d test below.
+  for d in "${NVM_DIR:-$HOME/.nvm}/versions/node/v${NODE_MAJOR}."*/bin \
+           "${FNM_DIR:-$HOME/.local/share/fnm}/node-versions/v${NODE_MAJOR}."*/installation/bin \
+           "$HOME/.volta/tools/image/node/${NODE_MAJOR}."*/bin; do
+    [[ -d "$d" ]] && candidates+=("$d")
+  done
+  cur="$(command -v node || true)"
+  [[ -n "$cur" ]] && candidates+=("$(dirname "$cur")")
+
+  for d in "${candidates[@]}"; do
+    [[ -x "$d/node" ]] || continue
+    [[ "$(node_major_of "$d/node")" == "$NODE_MAJOR" ]] || continue
+    printf '%s' "$d"
+    return 0
+  done
+  return 1
+}
+
+NODE_BIN_DIR="$(resolve_node_bin_dir || true)"
+if [[ -z "$NODE_BIN_DIR" ]]; then
+  echo "install-launchd.sh: no node ${NODE_MAJOR} found on this host." >&2
+  echo "  The repo pins node ${NODE_MAJOR} (docs/acc/NODE_VERSION_PIN.md); the agent must not" >&2
+  echo "  run the .zprofile-pinned node@20. Install one, e.g.:" >&2
+  echo "    brew install node@${NODE_MAJOR}       # or: nvm install ${NODE_MAJOR}" >&2
+  echo "  or point ACC_RUNNER_NODE_BIN_DIR at an existing install and re-run." >&2
+  exit 1
+fi
+
+# Resolve the CLI to a real file so we can decide how to invoke it: a JS
+# entrypoint is run by node@22 directly; a shell shim (pnpm) must run itself
+# and pick node up from the baked PATH.
+real_path_of() {
+  local p="$1" target
+  while [[ -L "$p" ]]; do
+    target="$(readlink "$p")"
+    case "$target" in
+      /*) p="$target" ;;
+      *)  p="$(cd "$(dirname "$p")" && cd "$(dirname "$target")" && pwd)/$(basename "$target")" ;;
+    esac
+  done
+  printf '%s' "$p"
+}
+
+ACC_RUNNER_ENTRY="$(real_path_of "$ACC_RUNNER_PATH")"
+case "$ACC_RUNNER_ENTRY" in
+  *.js|*.mjs|*.cjs) NODE_INVOKER="$NODE_BIN_DIR/node" ;;
+  *)                NODE_INVOKER="/usr/bin/env"; ACC_RUNNER_ENTRY="$ACC_RUNNER_PATH" ;;
+esac
+
+# ------------------------------------------------------------- ACC_* vars
+
+ENV_FILE="${ACC_RUNNER_LAUNCHD_ENV:-$HOME/.config/acc-runner/launchd.env}"
+
+from_env_file() { # $1 = key
+  [[ -f "$ENV_FILE" ]] || return 0
+  sed -n "s/^[[:space:]]*$1=//p" "$ENV_FILE" | tail -n1 | sed 's/^"\(.*\)"$/\1/'
+}
+
+from_config_json() { # $1 = config.json field; arrays are joined with commas
+  "$NODE_BIN_DIR/node" -e '
+    const fs = require("node:fs"), os = require("node:os"), p = require("node:path");
+    const base = process.env.XDG_CONFIG_HOME || p.join(os.homedir(), ".config");
+    try {
+      const j = JSON.parse(fs.readFileSync(p.join(base, "acc-runner", "config.json"), "utf8"));
+      const v = j[process.argv[1]];
+      if (Array.isArray(v)) process.stdout.write(v.filter(Boolean).join(","));
+      else if (typeof v === "string") process.stdout.write(v);
+      else if (typeof v === "number") process.stdout.write(String(v));
+    } catch { /* absent or unreadable config.json → no value */ }
+  ' "$1" 2>/dev/null || true
+}
+
+# Prints the first non-empty argument. Always succeeds (an all-empty list is
+# a normal "not configured" outcome, not an error under `set -e`).
+first_nonempty() { local v; for v in "$@"; do [[ -n "$v" ]] && { printf '%s' "$v"; break; }; done; return 0; }
+
+VAL_TARGET_REPO="$(first_nonempty "${ACC_TARGET_REPO:-}" "$(from_env_file ACC_TARGET_REPO)")"
+VAL_REPO_PATH="$(first_nonempty "${ACC_REPO_PATH:-}" "$(from_env_file ACC_REPO_PATH)" "$(from_config_json repo-path)")"
+VAL_REPOS="$(first_nonempty "${ACC_RUNNER_REPOS:-}" "$(from_env_file ACC_RUNNER_REPOS)" "$(from_config_json repos)")"
+VAL_CONCURRENCY="$(first_nonempty "${ACC_RUNNER_CONCURRENCY:-}" "$(from_env_file ACC_RUNNER_CONCURRENCY)")"
+
+ENTRIES_FILE="$(mktemp -t acc-runner-launchd-env)"
+trap 'rm -f "$ENTRIES_FILE" "${ENTRIES_FILE}.plist"' EXIT
+
+xml_escape() { printf '%s' "$1" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g'; }
+
+add_entry() { # $1 = key, $2 = value (skipped when empty)
+  [[ -n "$2" ]] || { echo "  - $1: not set (omitted; runner falls back to config.json / server default)"; return 0; }
+  printf '    <key>%s</key>\n    <string>%s</string>\n' "$1" "$(xml_escape "$2")" >> "$ENTRIES_FILE"
+  echo "  - $1=$2"
+}
+
+echo "Baking environment into $LABEL:"
+echo "  - PATH: $NODE_BIN_DIR (node $("$NODE_BIN_DIR/node" -v)) first, then Homebrew + system dirs"
+add_entry ACC_TARGET_REPO "$VAL_TARGET_REPO"
+add_entry ACC_REPO_PATH "$VAL_REPO_PATH"
+add_entry ACC_RUNNER_REPOS "$VAL_REPOS"
+add_entry ACC_RUNNER_CONCURRENCY "$VAL_CONCURRENCY"
+
+# ----------------------------------------------------------------- render
+
+TARGET_DIR="$HOME/Library/LaunchAgents"
+TARGET="$TARGET_DIR/$LABEL.plist"
+LOG_DIR="$HOME/Library/Logs"
+mkdir -p "$TARGET_DIR" "$LOG_DIR"
+
+# Escape sed replacement slashes so paths containing `/` substitute cleanly.
+esc() { printf '%s' "$1" | sed 's#[\\/&]#\\&#g'; }
+
+sed \
+  -e "s/__CAFFEINATE_PATH__/$(esc "$CAFFEINATE_PATH")/g" \
+  -e "s/__NODE_INVOKER__/$(esc "$NODE_INVOKER")/g" \
+  -e "s/__ACC_RUNNER_PATH__/$(esc "$ACC_RUNNER_ENTRY")/g" \
+  -e "s/__NODE_BIN_DIR__/$(esc "$NODE_BIN_DIR")/g" \
+  -e "s/__HOME__/$(esc "$HOME")/g" \
+  "$TEMPLATE" > "${ENTRIES_FILE}.plist"
+
+# Replace the marker LINE with the generated entries (or with nothing). The
+# pattern is anchored so the token's mention in the template's comment block
+# is left alone.
+awk -v entries="$ENTRIES_FILE" '
+  /^[[:space:]]*__ACC_ENV_ENTRIES__[[:space:]]*$/ {
+    while ((getline line < entries) > 0) print line
+    close(entries)
+    next
+  }
+  { print }
+' "${ENTRIES_FILE}.plist" > "$TARGET"
+
+plutil -lint "$TARGET" >/dev/null || { echo "install-launchd.sh: rendered plist is invalid: $TARGET" >&2; exit 1; }
+
+echo "Installed $TARGET"
+
+# ------------------------------------------------------------------- load
+
+if [[ "$DO_LOAD" -eq 0 ]]; then
+  echo "Skipped launchctl load (--no-load). Load it with:"
+  echo "  launchctl unload \"$TARGET\" 2>/dev/null; launchctl load \"$TARGET\""
+  exit 0
+fi
+
+if launchctl list | awk '{print $3}' | grep -qx "$LABEL"; then
+  launchctl unload "$TARGET" 2>/dev/null || true
+fi
+launchctl load "$TARGET"
+
+echo "Loaded $LABEL via launchctl"
+echo "Logs: $LOG_DIR/acc-runner.{out,err}.log"
+echo "Verify: launchctl list | grep $LABEL   # PID in col 1, exit code 0 in col 2"
+echo "Verify node: grep -A2 '<key>PATH</key>' \"$TARGET\""
+echo "Rollback: $SCRIPT_DIR/uninstall-launchd.sh"

package/scripts/setup-dedicated-runner-darwin.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+#
+# v0.13-DEDICATED-RUNNER — set up a headless Mac mini as the
+# acc-runner host.
+#
+# Idempotent: every step short-circuits if already applied.
+#   * pmset values are read first; only written if they differ.
+#   * launchd plist is unloaded before reload.
+#   * keychain unlock is best-effort (logs a hint on failure).
+#
+# Pairs with com.tokenfactory.acc-runner-dedicated.plist. See
+# docs/acc/DEDICATED_RUNNER_RUNBOOK.md.
+
+set -euo pipefail
+
+if [[ "$(uname)" != "Darwin" ]]; then
+  echo "setup-dedicated-runner-darwin.sh: macOS-only (uname=$(uname))" >&2
+  exit 1
+fi
+
+CAFFEINATE_PATH="$(command -v caffeinate || true)"
+ACC_RUNNER_PATH="$(command -v acc-runner || true)"
+if [[ -z "$CAFFEINATE_PATH" || -z "$ACC_RUNNER_PATH" ]]; then
+  echo "Missing prerequisites: caffeinate=$CAFFEINATE_PATH acc-runner=$ACC_RUNNER_PATH" >&2
+  echo "Install acc-runner first: pnpm add -g @tokenfactory/acc-runner" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TEMPLATE="$SCRIPT_DIR/com.tokenfactory.acc-runner-dedicated.plist"
+if [[ ! -f "$TEMPLATE" ]]; then
+  echo "Template missing: $TEMPLATE" >&2
+  exit 1
+fi
+
+LABEL="com.tokenfactory.acc-runner-dedicated"
+TARGET_DIR="$HOME/Library/LaunchAgents"
+TARGET="$TARGET_DIR/$LABEL.plist"
+LOG_DIR="$HOME/Library/Logs"
+mkdir -p "$TARGET_DIR" "$LOG_DIR"
+
+# 1. Power management — disable sleep on AC, disable Power Nap, restart on power loss.
+pmset_set() {
+  local scope="$1" key="$2" want="$3"
+  local cur
+  cur="$(pmset -g custom 2>/dev/null | awk -v k="$key" '$1==k {print $2; exit}')"
+  if [[ "$cur" != "$want" ]]; then
+    echo "pmset $scope $key $want (was: ${cur:-unset})"
+    sudo pmset "$scope" "$key" "$want"
+  fi
+}
+pmset_set -c sleep 0
+pmset_set -c disksleep 0
+pmset_set -a powernap 0
+pmset_set -a autorestart 1
+
+# 2. Render the dedicated plist with absolute paths.
+esc() { printf '%s' "$1" | sed 's#[\\/&]#\\&#g'; }
+sed \
+  -e "s/__CAFFEINATE_PATH__/$(esc "$CAFFEINATE_PATH")/g" \
+  -e "s/__ACC_RUNNER_PATH__/$(esc "$ACC_RUNNER_PATH")/g" \
+  -e "s/__HOME__/$(esc "$HOME")/g" \
+  "$TEMPLATE" > "$TARGET"
+
+# 3. Reload launchd (unload first; ignore missing).
+if launchctl list 2>/dev/null | awk '{print $3}' | grep -qx "$LABEL"; then
+  launchctl unload "$TARGET" 2>/dev/null || true
+fi
+launchctl load "$TARGET"
+
+echo "Installed $TARGET"
+echo "Loaded $LABEL via launchctl"
+echo "Logs: $LOG_DIR/acc-runner-dedicated.{out,err}.log"
+echo "Verify: acc-runner doctor"
+echo "Uninstall: launchctl unload \"$TARGET\" && rm \"$TARGET\""

package/scripts/setup-dedicated-runner-linux.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+#
+# v0.13-DEDICATED-RUNNER — set up a Linux VPS (or mini-PC) as the
+# acc-runner host via a systemd user unit.
+#
+# Idempotent: re-running rewrites the unit file and restarts the
+# service. enable-linger is checked before re-enabling so SSH-less
+# operators don't see a spurious prompt.
+#
+# RUNNER-LINUX-SUPERVISOR-1: `--instance <name>` supervises a NAMED
+# runner instance. The name forks the unit (acc-runner-<name>.service),
+# the ExecStart (`watch --instance <name>`) and ACC_RUNNER_INSTANCE, so
+# several named instances coexist on one host instead of overwriting the
+# single acc-runner.service they used to share. Without the flag every
+# rendered byte is what it was before — existing hosts are unaffected.
+#
+# Usage:
+#   packages/acc-runner/scripts/setup-dedicated-runner-linux.sh
+#   packages/acc-runner/scripts/setup-dedicated-runner-linux.sh --instance staging-smoke
+#   packages/acc-runner/scripts/setup-dedicated-runner-linux.sh --help
+#
+# Secrets are never written to the unit — tokens live in the OS keychain
+# (per instance: `acc-runner login --instance <name>`).
+#
+# Verify:   acc-runner doctor --instance <name>   (checks this unit)
+# See docs/acc/DEDICATED_RUNNER_RUNBOOK.md.
+
+set -euo pipefail
+
+INSTANCE=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --instance)
+      INSTANCE="${2:-}"
+      [[ -n "$INSTANCE" ]] || { echo "setup-dedicated-runner-linux.sh: --instance needs a name" >&2; exit 2; }
+      shift 2
+      ;;
+    --instance=*) INSTANCE="${1#*=}"; shift ;;
+    -h|--help)
+      awk 'NR>=2 { if ($0 !~ /^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"
+      exit 0
+      ;;
+    *) echo "setup-dedicated-runner-linux.sh: unknown option '$1' (see --help)" >&2; exit 2 ;;
+  esac
+done
+
+# Mirrors INSTANCE_NAME_RE in packages/acc-runner/src/instance.ts. The name
+# lands in a unit name and a keychain account, so nothing escapable is allowed.
+if [[ -n "$INSTANCE" && ! "$INSTANCE" =~ ^[a-z0-9][a-z0-9-]{0,31}$ ]]; then
+  echo "setup-dedicated-runner-linux.sh: invalid --instance '$INSTANCE'" >&2
+  echo "  must match ^[a-z0-9][a-z0-9-]{0,31}$ (lowercase, digits, dashes)" >&2
+  exit 2
+fi
+
+if [[ "$(uname)" != "Linux" ]]; then
+  echo "setup-dedicated-runner-linux.sh: Linux-only (uname=$(uname))" >&2
+  exit 1
+fi
+
+ACC_RUNNER_PATH="$(command -v acc-runner || true)"
+if [[ -z "$ACC_RUNNER_PATH" ]]; then
+  echo "acc-runner not found in PATH. Install: sudo npm install -g @tokenfactory/acc-runner" >&2
+  exit 1
+fi
+
+if ! command -v systemctl >/dev/null 2>&1; then
+  echo "systemctl not found; this script requires systemd." >&2
+  exit 1
+fi
+
+UNIT_DIR="$HOME/.config/systemd/user"
+SERVICE="acc-runner${INSTANCE:+-$INSTANCE}"
+UNIT="$UNIT_DIR/$SERVICE.service"
+LOG_HINT="journalctl --user -u $SERVICE -f"
+mkdir -p "$UNIT_DIR"
+
+# 1. Render the unit file. systemd-inhibit blocks logind's automatic idle
+#    action while the runner is active (a no-op on always-on VPS instances,
+#    real protection on a desktop/mini-PC).
+#
+#    `--what=idle`, NOT `idle:sleep`. The two halves are separate polkit
+#    actions and they do not have the same default:
+#
+#      org.freedesktop.login1.inhibit-block-idle    allow_any=yes
+#      org.freedesktop.login1.inhibit-block-sleep   allow_any=no
+#
+#    This unit runs as a child of a lingering user@<uid>.service, which has no
+#    logind session, so polkit evaluates the `allow_any` branch. Requesting
+#    `idle:sleep` therefore took the sleep action's `no`, systemd-inhibit
+#    exited 1 BEFORE exec'ing the runner, and Restart=always turned that into a
+#    permanent 60s restart loop in which acc-runner never ran at all (observed
+#    on a live VPS: `Failed to inhibit: Access denied`, CPU 3ms per attempt).
+#    `idle` alone is allow_any=yes, so it succeeds unprivileged and
+#    session-less on the stock policy.
+#
+#    Dropping `sleep` costs nothing a runner host wants: it only blocked an
+#    explicit `systemctl suspend`, while `idle` is what blocks the automatic
+#    IdleAction suspend the runbook actually describes.
+#
+#    Deliberately NOT gated on an install-time capability probe. The installer
+#    runs in the operator's logind session, which is `active`, so a probe would
+#    take polkit's allow_active branch and pass -- then the unit runs
+#    session-less at boot and fails anyway. A probe would ship this outage
+#    under the appearance of a fix.
+WATCH_ARGS="watch${INSTANCE:+ --instance $INSTANCE}"
+INHIBIT_PATH="$(command -v systemd-inhibit || true)"
+if [[ -n "$INHIBIT_PATH" ]]; then
+  EXEC_LINE="ExecStart=$INHIBIT_PATH --what=idle --who=$SERVICE --why=ACC-runner-watch $ACC_RUNNER_PATH $WATCH_ARGS"
+else
+  EXEC_LINE="ExecStart=$ACC_RUNNER_PATH $WATCH_ARGS"
+fi
+
+# ACC_RUNNER_INSTANCE is exported into the unit so every resolver the watch
+# process spawns (keychain account, cache root, machine string) agrees with the
+# ExecStart flag. Appended last, so the unnamed render is unchanged.
+# packages/acc-runner/src/cli.ts is `#!/usr/bin/env node`, so an absolute
+# ACC_RUNNER_PATH in ExecStart still resolves `node` against the unit's OWN
+# PATH. A node from nvm/fnm/volta lives under $HOME and is not on the system
+# path below, which exits 127 -- another silent restart loop, and the next
+# failure after the inhibit one on any host that did not install node via apt.
+# install-launchd.sh already solves this on macOS (resolve_node_bin_dir); this
+# is the Linux counterpart, kept minimal: the installer runs in the operator's
+# shell, where the intended node is already resolvable.
+UNIT_PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+NODE_BIN_DIR="$(cd "$(dirname "$(command -v node)")" 2>/dev/null && pwd || true)"
+case ":$UNIT_PATH:" in
+  *":$NODE_BIN_DIR:"*) ;;
+  *) [[ -n "$NODE_BIN_DIR" ]] && UNIT_PATH="$NODE_BIN_DIR:$UNIT_PATH" ;;
+esac
+
+ENV_LINES="Environment=ACC_RUNNER_DEDICATED=1
+Environment=PATH=$UNIT_PATH"
+if [[ -n "$INSTANCE" ]]; then
+  ENV_LINES="$ENV_LINES
+Environment=ACC_RUNNER_INSTANCE=$INSTANCE"
+fi
+
+cat > "$UNIT" <<EOF
+[Unit]
+Description=ACC runner (watch loop)${INSTANCE:+ — instance $INSTANCE}
+Documentation=https://github.com/tokenfactory-pvt-ltd/agent-control-center
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+$EXEC_LINE
+Restart=always
+RestartSec=60s
+StandardOutput=journal
+StandardError=journal
+$ENV_LINES
+
+[Install]
+WantedBy=default.target
+EOF
+
+# 2. enable-linger so the unit survives the operator's SSH disconnect.
+if ! loginctl show-user "$USER" 2>/dev/null | grep -q "Linger=yes"; then
+  echo "Enabling linger for $USER (requires sudo)..."
+  sudo loginctl enable-linger "$USER"
+fi
+
+# 3. Reload + start.
+systemctl --user daemon-reload
+systemctl --user enable --now "$SERVICE.service"
+
+echo "Installed $UNIT"
+echo "Service active: $(systemctl --user is-active "$SERVICE.service")"
+echo "Logs: $LOG_HINT"
+echo "Verify: acc-runner doctor${INSTANCE:+ --instance $INSTANCE}"
+echo "Uninstall: systemctl --user disable --now $SERVICE && rm \"$UNIT\" && sudo loginctl disable-linger $USER"