spinuptui 1.3.0-alpha.3 → 1.3.0-alpha.5

package/src/lib/scheduler.test.ts

@@ -7,7 +7,8 @@ import { agentOf, parseJobText, splitArgs, validateJob } from "./schedulerJobs.t
 import { quoteArg } from "./cliScheduler.ts"
 import { renderPlist, renderSystemd } from "./schedulerInstall.ts"
 import { runModuleJobs } from "./schedulerTick.ts"
-import { summaryOf } from "./schedulerRun.ts"
+import { agentCommand, BLOCKED_EXIT, outcomeOf, summaryOf } from "./schedulerRun.ts"
+import { stillRunningHeartbeat } from "./heartbeat.ts"
 import { tryLock } from "./flock.ts"
 
 const at = (s: string) => parseWhen(s)
@@ -351,3 +352,190 @@ describe("station claim", () => {
     expect(await decideClaim(b, "nas")).toEqual({ run: true, claimed: true })
   })
 })
+
+// ---- extend ----------------------------------------------------------------------
+
+import { mkdirSync } from "node:fs"
+import { addPeriod, extendJob, newExpiry, setHeaderValue } from "./schedulerExtend.ts"
+import { fmtDate, parseDate } from "./schedule.ts"
+
+describe("extend", () => {
+  const day = (s: string) => parseDate(s)
+
+  test("periods, clamped to the month's last day", () => {
+    expect(fmtDate(addPeriod(day("2026-10-29"), "1y"))).toBe("2027-10-29")
+    expect(fmtDate(addPeriod(day("2028-02-29"), "1y"))).toBe("2029-02-28")
+    expect(fmtDate(addPeriod(day("2026-01-31"), "1m"))).toBe("2026-02-28")
+    expect(fmtDate(addPeriod(day("2026-12-30"), "2w"))).toBe("2027-01-13")
+    expect(fmtDate(addPeriod(day("2026-10-29"), "30d"))).toBe("2026-11-28")
+    expect(() => addPeriod(day("2026-10-29"), "0d")).toThrow(/--by/)
+    expect(() => addPeriod(day("2026-10-29"), "1q")).toThrow(/--by/)
+  })
+
+  test("--by counts from the expiry, or from today once it has passed", () => {
+    expect(newExpiry("2026-11-06", { by: "1y" }, at("2026-10-29 09:00"))).toBe("2027-11-06")
+    expect(newExpiry("2026-10-01", { by: "1y" }, at("2026-10-29 09:00"))).toBe("2027-10-29")
+    expect(newExpiry("2026-11-06", { date: "2027-01-05" }, at("2026-10-29 09:00"))).toBe("2027-01-05")
+  })
+
+  test("only the expires: line changes, comment kept", () => {
+    const text = "---\nid: x\nexpires: 2026-10-28   # stop after the audit\nkind: script\n---\necho hi\n"
+    expect(setHeaderValue(text, "expires", "2027-10-28")).toBe("---\nid: x\nexpires: 2027-10-28   # stop after the audit\nkind: script\n---\necho hi\n")
+    expect(() => setHeaderValue("---\nid: x\n---\nbody", "expires", "2027-01-01")).toThrow(/no expires/)
+    // A body line that looks like a header isn't touched.
+    expect(setHeaderValue("---\nexpires: 2026-01-01\n---\nexpires: keep\n", "expires", "2027-01-01")).toBe("---\nexpires: 2027-01-01\n---\nexpires: keep\n")
+  })
+
+  const job = "---\nid: nightly\nkind: script\nevery: daily 22:00\nexpires: 2026-11-06\ncreated: 2026-10-20 09:00\ncreated_by: test\n---\necho hi\n"
+
+  test("a local source: rewritten in place, and an earlier date is refused", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "extend-"))
+    mkdirSync(join(dir, "jobs"))
+    writeFile(join(dir, "jobs", "nightly.md"), job)
+    const s: Source = { name: "local", path: dir, gitRoot: null, git: false, queueOnly: false }
+    const r = await extendJob(s, "nightly", { by: "1y" }, { now: at("2026-10-29 09:00") })
+    expect(r).toMatchObject({ ok: true, from: "2026-11-06", to: "2027-11-06", pushed: null })
+    expect(readFile(join(dir, "jobs", "nightly.md"), "utf8")).toBe(job.replace("2026-11-06", "2027-11-06"))
+    expect(await extendJob(s, "nightly", { date: "2027-01-01" })).toMatchObject({ ok: false, reason: "not_later" })
+    expect(await extendJob(s, "nope", { by: "1y" })).toMatchObject({ ok: false, reason: "unknown_job" })
+  })
+
+  test("a git source: one commit, pushed, seen by the other clone", async () => {
+    const { a, b } = await twoStations()
+    mkdirSync(join(a.path, "jobs"))
+    writeFile(join(a.path, "jobs", "nightly.md"), job)
+    await sh(a.path, "git", "add", "jobs")
+    await sh(a.path, "git", "commit", "-q", "-m", "add")
+    await sh(a.path, "git", "push", "-q")
+    // Queued from the other clone, which hasn't pulled the job yet.
+    const r = await extendJob(b, "nightly", { by: "1y" }, { now: at("2026-10-29 09:00") })
+    expect(r).toMatchObject({ ok: true, to: "2027-11-06", pushed: true })
+    expect(await sh(b.path, "git", "log", "-1", "--format=%s")).toBe("job: extend nightly to 2027-11-06")
+    await sh(a.path, "git", "pull", "-q")
+    expect(readFile(join(a.path, "jobs", "nightly.md"), "utf8")).toContain("expires: 2027-11-06")
+  })
+})
+
+// ---- /jobs on the pager ------------------------------------------------------------
+
+import { extendReply, jobsReply } from "../modules/scheduler.ts"
+
+describe("/jobs", () => {
+  const write = (dir: string, id: string, schedule: string, expires: string) =>
+    writeFile(join(dir, `${id}.md`), `---\nid: ${id}\nkind: script\n${schedule}\nexpires: ${expires}\ncreated: 2026-10-01 09:00\ncreated_by: test\n---\necho hi\n`)
+
+  test("lists jobs by expiry, flags the soon ones, and offers Extend on recurring ones", async () => {
+    process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "jobs-cfg-"))
+    process.env.SPINUPTUI_HOME = mkdtempSync(join(tmpdir(), "jobs-home-"))
+    const jobs = join(process.env.SPINUPTUI_HOME, "scheduler", "jobs")
+    mkdirSync(jobs, { recursive: true })
+    write(jobs, "nightly", "every: daily 22:00", "2026-11-06")
+    write(jobs, "audit", "when: 2026-10-30 09:00", "2026-11-02")
+    write(jobs, "longterm", "every: weekdays 08:00", "2028-10-29")
+    write(jobs, "ancient", "every: daily 08:00", "2026-01-01")
+    const now = at("2026-10-29 12:00")
+    const r = await jobsReply({ now, pull: false })
+    expect(r.html).toBe(true)
+    expect(r.text).toContain("</b> (3)")
+    const order = ["audit", "nightly", "longterm"].map((id) => r.text.indexOf(`<b>${id}</b>`))
+    expect([...order].sort((a, b) => a - b)).toEqual(order)
+    expect(r.text).toContain("⚠️ <b>nightly</b>\nExpires Nov 6 (in 8 days)\nscript · daily 22:00 · next tonight 22:00")
+    expect(r.text).toContain("⚠️ <b>audit</b>\nExpires Nov 2 (in 4 days)\nscript · once, tomorrow 09:00")
+    expect(r.text).toContain("<b>longterm</b>\nExpires Oct 29, 2028\nscript · weekdays 08:00 · next tomorrow 08:00")
+    expect(r.text).toContain("1 finished or long-expired not shown.")
+    // A one-shot isn't offered a year of nothing.
+    expect(r.buttons).toEqual([[{ text: "Extend nightly 1 year", action: "scheduler.extend", payload: { source: "local", id: "nightly", from: "2026-11-06" } }]])
+
+    const done = await extendReply(r.buttons![0]![0]!.payload, now)
+    expect(done.text).toBe("✅ Extended nightly: it now expires 2027-11-06 (was 2026-11-06).")
+    // The same button again (say, from an older /jobs reply) doesn't stack a second year.
+    expect((await extendReply(r.buttons![0]![0]!.payload, now)).text).toMatch(/^Couldn't extend nightly: nightly already expires 2027-11-06/)
+    delete process.env.SPINUPTUI_HOME
+  })
+})
+
+describe("blocked", () => {
+  test("an agent that exits 0 saying it's blocked did no work", () => {
+    expect(outcomeOf(true, 0, false, "SUMMARY: login lapsed.\nSTATUS: blocked\nNeeds a re-login.")).toBe("blocked")
+    expect(outcomeOf(true, 0, false, "SUMMARY: all fine.\n\nThe status: blocked queue is empty.")).toBe("ok")
+  })
+
+  test("a script says so with its exit code", () => {
+    expect(outcomeOf(false, BLOCKED_EXIT, false, "")).toBe("blocked")
+    expect(outcomeOf(false, 1, false, "")).toBe("failed")
+    expect(outcomeOf(false, 0, false, "STATUS: blocked")).toBe("ok")
+  })
+
+  test("a lapsed login and a timeout keep their own statuses", () => {
+    expect(outcomeOf(true, 1, false, "Please run /login")).toBe("auth")
+    expect(outcomeOf(true, null, true, "working")).toBe("timeout")
+    expect(outcomeOf(true, 1, false, "boom")).toBe("failed")
+  })
+
+  test("a blocked one-shot isn't done", () => {
+    const job = { when: "2026-10-20 08:00", expires: "2026-10-30" }
+    const now = at("2026-10-21 08:00")
+    expect(nextRunText(job, { last_scheduled: "2026-10-20 08:00", last_status: "blocked" }, now)).toBe("blocked")
+    expect(nextRunText(job, { last_scheduled: "2026-10-20 08:00", last_status: "ok" }, now)).toBe("done")
+    // It waits for the operator: a blocked run doesn't retry by itself.
+    expect(dueOccurrence(job, { last_scheduled: "2026-10-20 08:00", last_status: "blocked" }, now)).toBeNull()
+  })
+
+  test("a module job pages once when blocked, and again when it recovers", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "blocked-"))
+    const pages: string[] = []
+    const step = (result: { ok: boolean; output: string; blocked?: boolean }, minute: string) =>
+      runModuleJobs([{ id: "t", every: "5m", command: ["x"] }], { stateDir: dir, now: at(`2026-10-20 10:${minute}`), run: async () => result, page: async (t) => (pages.push(t), "sent") })
+    await step({ ok: false, output: "login", blocked: true }, "00")
+    await step({ ok: false, output: "login", blocked: true }, "05")
+    await step({ ok: true, output: "" }, "10")
+    expect(pages.length).toBe(2)
+    expect(pages[0]).toContain("blocked")
+    expect(pages[1]).toContain("working again")
+  })
+})
+
+describe("the agent adapter", () => {
+  test("carries the always-deny list and options, for any caller", () => {
+    const cmd = agentCommand({ agent: "claude", prompt: "p", workdir: "/w", allow: "Read", addDirs: "/a,/b", model: "m" }, { PATH: `/bin:${process.env.PATH}` })
+    if (typeof cmd === "string") return // no claude here; the string is the reason
+    expect(cmd).toContain("--disallowedTools")
+    expect(cmd.filter((a) => a === "--add-dir").length).toBe(2)
+  })
+
+  test("says why when the binary is missing", () => {
+    expect(agentCommand({ agent: "codex", prompt: "p", workdir: "/w" }, { PATH: "/nonexistent" })).toBe("codex not found on PATH")
+  })
+})
+
+describe("a dispatcher tick that finds the lock held", () => {
+  test("tells Kuma the station is alive, unless it can't page", () => {
+    expect(stillRunningHeartbeat(null)).toEqual({ status: "up", msg: "tick still running" })
+    expect(stillRunningHeartbeat("Beacon's last page failed").status).toBe("down")
+  })
+
+  test("pings and records itself; a manual one doesn't", async () => {
+    process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "stilltick-"))
+    const { schedulerStateDir, readLastTick } = await import("./schedulerJobs.ts")
+    const { saveConfig } = await import("../config.ts")
+    const { tick } = await import("./schedulerTick.ts")
+    const pings: string[] = []
+    const server = Bun.serve({ port: 0, fetch: (r) => (pings.push(r.url), Response.json({ ok: true })) })
+    try {
+      await saveConfig({
+        scheduler: { heartbeat: { url: `http://localhost:${server.port}/api/push/x`, setAt: "now" } },
+        beacon: { channels: { pager: { type: "telegram", botToken: "1:a", chatId: "2" } } },
+      })
+      const lock = tryLock(join(schedulerStateDir(), "tick.lock"))!
+      expect(await tick({ via: "manual" })).toMatchObject({ skipped: "locked" })
+      expect(pings.length).toBe(0)
+      expect(await tick({ via: "dispatcher" })).toMatchObject({ skipped: "locked" })
+      lock.release()
+      expect(pings.length).toBe(1)
+      expect(pings[0]).toContain("still")
+      expect(readLastTick()).toMatchObject({ stillRunning: true, via: "dispatcher", heartbeat: { ok: true } })
+    } finally {
+      server.stop(true)
+    }
+  })
+})

package/src/lib/schedulerExtend.ts

@@ -0,0 +1,105 @@
+// Moving a job's `expires:` later — `spinuptui scheduler extend`, and the
+// "Extend 1 year" button on Beacon's /jobs reply. Both go through extendJob(),
+// so a tap and a command commit the same change the same way.
+//
+// The job file is edited in place: only the `expires:` line changes, keeping the
+// header's order and any trailing " # comment", so the commit is a one-line diff.
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { fmtDate, parseDate } from "./schedule.ts"
+import { jobsDir, parseJobText, validateJob, type Source } from "./schedulerJobs.ts"
+import { git, gitPull } from "./schedulerGit.ts"
+
+export const PERIOD_RE = /^([1-9]\d{0,2})([dwmy])$/
+
+// `date` moved forward by a period like 30d, 2w, 6m or 1y. Months and years
+// clamp to the month's last day, so 2028-02-29 + 1y is 2029-02-28.
+export function addPeriod(date: Date, period: string): Date {
+  const m = period.trim().toLowerCase().match(PERIOD_RE)
+  if (!m || +m[1]! === 0) throw new Error(`--by takes a period like 30d, 2w, 6m or 1y, got "${period}"`)
+  const n = +m[1]!
+  const unit = m[2]!
+  if (unit === "d" || unit === "w") return new Date(date.getFullYear(), date.getMonth(), date.getDate() + n * (unit === "w" ? 7 : 1))
+  const months = unit === "y" ? n * 12 : n
+  const target = new Date(date.getFullYear(), date.getMonth() + months, 1)
+  const last = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate()
+  return new Date(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), last))
+}
+
+// The new expiry: an explicit date, or a period added to the current expiry —
+// or to today, when the job has already expired, so "1y" always means a year
+// of runs from now on.
+export function newExpiry(current: string, to: { date?: string; by?: string }, today: Date): string {
+  if (to.date) return fmtDate(parseDate(to.date))
+  const cur = parseDate(current)
+  const day = new Date(today.getFullYear(), today.getMonth(), today.getDate())
+  return fmtDate(addPeriod(cur < day ? day : cur, to.by!))
+}
+
+// The job file's text with one header value replaced, everything else as written.
+export function setHeaderValue(text: string, key: string, value: string): string {
+  const lines = text.split("\n")
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i]!
+    if (line.trim() === "---") break
+    const colon = line.indexOf(":")
+    if (colon === -1 || line.slice(0, colon).trim().toLowerCase() !== key) continue
+    const hash = line.indexOf(" #", colon)
+    const comment = hash === -1 ? "" : line.slice(hash).replace(/^\s*/, "   ")
+    lines[i] = `${line.slice(0, colon + 1)} ${value}${comment}`
+    return lines.join("\n")
+  }
+  throw new Error(`the header has no ${key}: line`)
+}
+
+export type ExtendResult =
+  | { ok: true; source: string; id: string; from: string; to: string; path: string; pushed: boolean | null }
+  | { ok: false; reason: string; message: string; remedy?: string }
+
+export async function extendJob(s: Source, id: string, to: { date?: string; by?: string }, opts: { now?: Date; push?: boolean } = {}): Promise<ExtendResult> {
+  const push = opts.push ?? true
+  if (s.git && push) {
+    const e = await gitPull(s.path)
+    if (e) return { ok: false, reason: "git_failed", message: `${s.name}: ${e}` }
+  }
+  const path = join(jobsDir(s), `${id}.md`)
+  if (!existsSync(path)) return { ok: false, reason: "unknown_job", message: `No ${s.name}/jobs/${id}.md.` }
+  const text = readFileSync(path, "utf8")
+  let from: string
+  let next: string
+  let updated: string
+  try {
+    from = parseJobText(text).header.expires ?? ""
+    if (!from) throw new Error("the header has no expires: line")
+    next = newExpiry(from, to, opts.now ?? new Date())
+    updated = setHeaderValue(text, "expires", next)
+  } catch (err) {
+    return { ok: false, reason: "invalid_job", message: `${s.name}/jobs/${id}.md: ${(err as Error).message}` }
+  }
+  if (parseDate(next) <= parseDate(from)) {
+    return {
+      ok: false,
+      reason: "not_later",
+      message: `${id} already expires ${from}; ${next} isn't later.`,
+      remedy: "Give a later date. To stop a job sooner, cancel it.",
+    }
+  }
+  const parsed = parseJobText(updated)
+  const problems = validateJob(parsed.header, parsed.body, `${id}.md`)
+  if (problems.length) return { ok: false, reason: "invalid_job", message: `Not extended: ${problems.join("; ")}` }
+
+  writeFileSync(`${path}.tmp`, updated)
+  renameSync(`${path}.tmp`, path)
+  let pushed: boolean | null = null
+  if (s.git && push) {
+    await git(s.path, "add", "--", path)
+    await git(s.path, "commit", "--quiet", "-m", `job: extend ${id} to ${next}`, "--", path)
+    const r = await git(s.path, "push", "--quiet")
+    if (r.code !== 0) {
+      return { ok: false, reason: "push_failed", message: `Extended ${s.name}/jobs/${id}.md to ${next} and committed it, but the push failed, so other machines won't see it until it's pushed:\n${r.out}` }
+    }
+    pushed = true
+  }
+  return { ok: true, source: s.name, id, from, to: next, path, pushed }
+}

package/src/lib/schedulerInstall.ts

@@ -110,10 +110,21 @@ export function renderSystemd(p: { label: string; programArguments: string[]; en
   }
 }
 
-export function planInstall(opts: { bin?: string | null } = {}): PlanResult {
+// The release binary a station unit runs, and the PATH it runs with. Shared by
+// Scheduler's dispatcher and Beacon's listener so both run the same install.
+export interface Runner {
+  bin: string
+  checkout: string | null
+  // The command line up to the subcommand: [bun, bin] or [bin].
+  prefix: string[]
+  env: Record<string, string>
+  missingTools: string[]
+}
+
+export function resolveRunner(opts: { bin?: string | null } = {}): ({ ok: true } & Runner) | { ok: false; reason: string; message: string; remedy?: string } {
   const platform = process.platform
   if (platform !== "darwin" && platform !== "linux") {
-    return { ok: false, reason: "unsupported_platform", message: `Scheduler's dispatcher supports macOS and Linux, not ${platform}.` }
+    return { ok: false, reason: "unsupported_platform", message: `SpinupTUI's station units support macOS and Linux, not ${platform}.` }
   }
   const searchPath = [process.env.PATH ?? "", join(homedir(), ".bun/bin")].join(":")
   const bin = opts.bin ?? Bun.which("spinuptui", { PATH: searchPath })
@@ -121,7 +132,7 @@ export function planInstall(opts: { bin?: string | null } = {}): PlanResult {
     return {
       ok: false,
       reason: "spinuptui_not_found",
-      message: opts.bin ? `--bin ${opts.bin} does not exist.` : "No global `spinuptui` on the PATH for the dispatcher to run.",
+      message: opts.bin ? `--bin ${opts.bin} does not exist.` : "No global `spinuptui` on the PATH for the unit to run.",
       remedy: "Install it globally first: bun add -g spinuptui",
     }
   }
@@ -136,13 +147,13 @@ export function planInstall(opts: { bin?: string | null } = {}): PlanResult {
     return {
       ok: false,
       reason: "checkout_bin",
-      message: `The \`spinuptui\` on the PATH (${bin}) runs a development checkout (${checkout}). The dispatcher must run a release, so an unattended tick never runs whatever is checked out.`,
+      message: `The \`spinuptui\` on the PATH (${bin}) runs a development checkout (${checkout}). A station unit must run a release, so nothing unattended ever runs whatever is checked out.`,
       remedy: "Install a release globally (bun add -g spinuptui), or pass --bin <path> to override deliberately.",
     }
   }
   const shebang = shebangOf(real)
   const bun = /\bbun(\.exe)?$/.test(process.execPath) ? process.execPath : (Bun.which("bun", { PATH: searchPath }) ?? "bun")
-  const programArguments = shebang?.includes("bun") ? [bun, bin, "scheduler", "tick"] : [bin, "scheduler", "tick"]
+  const prefix = shebang?.includes("bun") ? [bun, bin] : [bin]
 
   const dirs: string[] = [dirname(bun), dirname(bin)]
   for (const t of TOOLS) {
@@ -152,12 +163,19 @@ export function planInstall(opts: { bin?: string | null } = {}): PlanResult {
     if (p && !SYSTEM_PATH.includes(dirname(p))) dirs.push(dirname(p))
   }
   for (const d of SYSTEM_PATH) if (existsSync(d)) dirs.push(d)
-  const env: Record<string, string> = {
-    PATH: [...new Set(dirs)].join(":"),
-    SPINUPTUI_SCHEDULER_DISPATCHER: "1",
-  }
+  const env: Record<string, string> = { PATH: [...new Set(dirs)].join(":") }
   if (process.env.XDG_CONFIG_HOME) env.XDG_CONFIG_HOME = process.env.XDG_CONFIG_HOME
   if (process.env.SPINUPTUI_HOME) env.SPINUPTUI_HOME = process.env.SPINUPTUI_HOME
+  return { ok: true, bin, checkout, prefix, env, missingTools: TOOLS.filter((t) => !Bun.which(t, { PATH: env.PATH })) }
+}
+
+export function planInstall(opts: { bin?: string | null } = {}): PlanResult {
+  const runner = resolveRunner(opts)
+  if (!runner.ok) return runner
+  const platform = process.platform as "darwin" | "linux"
+  const { bin, checkout } = runner
+  const programArguments = [...runner.prefix, "scheduler", "tick"]
+  const env: Record<string, string> = { ...runner.env, SPINUPTUI_SCHEDULER_DISPATCHER: "1" }
   const label = schedulerLabel()
   // One clock per machine: a dispatcher installed under another label would
   // tick the same jobs alongside this one.
@@ -172,8 +190,7 @@ export function planInstall(opts: { bin?: string | null } = {}): PlanResult {
   }
   const notes: string[] = [`Jobs and reports live in ${moduleWorkDir("scheduler")} (created on first use).`]
   if (checkout) notes.push(`--bin points into a checkout (${checkout}); fine for testing, never for a station.`)
-  const missing = TOOLS.filter((t) => !Bun.which(t, { PATH: env.PATH }))
-  if (missing.length) notes.push(`Not found, so jobs that need them will fail: ${missing.join(", ")}.`)
+  if (runner.missingTools.length) notes.push(`Not found, so jobs that need them will fail: ${runner.missingTools.join(", ")}.`)
 
   if (platform === "darwin") {
     const unitPath = join(homedir(), "Library/LaunchAgents", `${label}.plist`)
@@ -216,18 +233,22 @@ export function planInstall(opts: { bin?: string | null } = {}): PlanResult {
 // treats `scheduler tick` as an unknown subcommand and would launch the TUI
 // under launchd every 5 minutes.
 export async function binHasScheduler(plan: Pick<InstallPlan, "programArguments" | "env">): Promise<boolean> {
+  return helpIncludes(plan.programArguments.slice(0, -2), plan.env.PATH ?? "", "spinuptui scheduler")
+}
+
+export async function helpIncludes(prefix: string[], path: string, needle: string): Promise<boolean> {
   try {
-    const p = spawn([...plan.programArguments.slice(0, -2), "--help"], {
+    const p = spawn([...prefix, "--help"], {
       stdin: "ignore",
       stdout: "pipe",
       stderr: "ignore",
-      env: { ...process.env, PATH: plan.env.PATH ?? "" },
+      env: { ...process.env, PATH: path },
     })
     const timer = setTimeout(() => p.kill(), 30_000)
     const out = await new Response(p.stdout).text()
     await p.exited
     clearTimeout(timer)
-    return out.includes("spinuptui scheduler")
+    return out.includes(needle)
   } catch {
     return false
   }
@@ -240,7 +261,7 @@ export const NO_SCHEDULER = {
   remedy: "Install a release that has it first: bun add -g spinuptui@next --no-cache",
 }
 
-async function launchctl(...args: string[]): Promise<{ code: number; out: string }> {
+export async function launchctl(...args: string[]): Promise<{ code: number; out: string }> {
   const p = spawn(["launchctl", ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe" })
   const [out, err] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()])
   return { code: await p.exited, out: (out + err).trim() }

package/src/lib/schedulerJobs.ts

@@ -191,7 +191,6 @@ export function agentOf(header: JobHeader): "claude" | "codex" | null {
 
 export interface JobState extends ScheduleState {
   runs?: number
-  last_status?: string
   last_report?: string
   auth_alerted_for?: string
   invalid?: string
@@ -222,7 +221,7 @@ export function saveState(s: Source, id: string, state: JobState): void {
 export interface TickRun {
   source: string
   id: string
-  status: "ok" | "failed" | "timeout" | "error" | "auth" | "invalid" | "skipped"
+  status: "ok" | "failed" | "blocked" | "timeout" | "error" | "auth" | "invalid" | "skipped"
   report?: string
   notified?: string
 }
@@ -235,6 +234,9 @@ export interface TickRecord {
   errors: string[]
   // Git sources another station runs (or released here): expected, not errors.
   notRunHere?: string[]
+  // This dispatcher tick found the previous one still running, so it did nothing
+  // but say the station is alive.
+  stillRunning?: boolean
   // The station heartbeat's ping at the end of this tick, when one is set.
   heartbeat?: { ok: boolean; status: "up" | "down"; error?: string }
 }

package/src/lib/schedulerRun.ts

@@ -6,11 +6,13 @@
 // rather than counted as a run) carry over from the git-backed job runner; see
 // docs/2026-10-20_scheduler-spec.md.
 
-import { existsSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { hostname, homedir } from "node:os"
 import { join } from "node:path"
 import { loadConfig } from "../config.ts"
 import { beaconFromConfig, beaconSend } from "./beacon.ts"
+import { pageMarkup } from "./beaconListenInstall.ts"
+import type { BeaconButton } from "../modules/contract.ts"
 import { spawn } from "./spawn.ts"
 import { prepareWorkDir } from "./home.ts"
 import { fmt } from "./schedule.ts"
@@ -19,19 +21,24 @@ import { agentOf, DEFAULT_TIMEOUT_MIN, expandHome, loadState, runsDir, saveState
 export const DEFAULT_ALLOW = "Read,Grep,Glob"
 // Never allowed in a claude job, whatever its allow: line says.
 export const ALWAYS_DENY = "Bash(git push *),Bash(git reset *),Bash(git clean *),Bash(rm -rf *),Bash(sudo *)"
-const AUTH_FAIL_RE =
+// A script (or a `spinuptui` job) that exits with this ran but couldn't do its
+// work because of something outside it: EX_TEMPFAIL. An agent says so in text.
+export const BLOCKED_EXIT = 75
+export const BLOCKED_RE = /^\s*STATUS:\s*blocked\b/im
+export const AUTH_FAIL_RE =
   /Failed to authenticate|OAuth (session|token)|could not be refreshed|Invalid API key|API key.*(expired|invalid)|Please run .?\/login|not (logged in|authenticated)/i
 const REPORT_CAP = 200_000
 // Tools a launchd PATH doesn't include by default.
 const EXTRA_PATH = [join(homedir(), ".local/bin"), join(homedir(), ".bun/bin"), "/opt/homebrew/bin", "/usr/local/bin"]
 
-export type RunStatus = "ok" | "failed" | "timeout" | "error" | "auth"
+export type RunStatus = "ok" | "failed" | "blocked" | "timeout" | "error" | "auth"
 
 function preamble(id: string, kind: string, createdBy: string, runs: string): string {
   return `You are running unattended on ${hostname().split(".")[0]} as scheduled job \`${id}\` (kind: ${kind}), queued by: ${createdBy}.
 Nobody is watching this run and nobody can answer questions. Do the task below, then stop.
 Rules: report, don't act. Do not modify files outside ${runs}, do not push, deploy, post to clients or email anyone, unless the task explicitly says to.
 Your final message is the report. Start it with a line \`SUMMARY:\` followed by one short paragraph (under 600 characters, plain text) that stands on its own in a chat message. Then give the details in Markdown.
+If you couldn't do the work because of something outside this job that a person has to fix (a lapsed login, a missing permission, a service refusing you), put a line \`STATUS: blocked\` straight after the summary and say what's needed. Don't use it for a finding, however bad.
 
 --- TASK ---
 `
@@ -55,6 +62,15 @@ export function jobEnv(): Record<string, string> {
   return env
 }
 
+// Starts a process that outlives this one: its own session (launchd reaps a
+// job's process group, not this), and no inherited pipes, since whoever reads
+// this process's stdout would otherwise wait for the child to finish too.
+export function spawnDetached(cmd: string[], opts: { cwd: string; env: Record<string, string> }): void {
+  mkdirSync(opts.cwd, { recursive: true })
+  const proc = spawn(cmd, { cwd: opts.cwd, env: opts.env, stdin: "ignore", stdout: "ignore", stderr: "ignore", detached: true } as Parameters<typeof spawn>[1])
+  proc.unref()
+}
+
 export interface ProcResult {
   code: number | null
   output: string
@@ -112,6 +128,28 @@ export function summaryOf(job: Job, output: string): string {
   return text.split("\n").slice(-15).join("\n").slice(-900)
 }
 
+export interface AgentRun {
+  agent: "claude" | "codex"
+  prompt: string
+  workdir: string
+  allow?: string
+  addDirs?: string
+  model?: string
+  sandbox?: string
+}
+
+// The adapters: a binary name and how to build its argv. Scheduler's agent jobs
+// and Sentinel's worker share them. Returns why it can't run, as a string.
+export function agentCommand(run: AgentRun, env: Record<string, string>): string[] | string {
+  const bin = Bun.which(run.agent, { PATH: env.PATH })
+  if (!bin) return `${run.agent} not found on PATH`
+  if (run.agent === "codex") return [bin, "exec", "-s", run.sandbox || "read-only", "-C", run.workdir, "--skip-git-repo-check", run.prompt]
+  const cmd = [bin, "-p", run.prompt, "--output-format", "text", "--permission-mode", "default", "--allowedTools", run.allow || DEFAULT_ALLOW, "--disallowedTools", ALWAYS_DENY]
+  for (const d of (run.addDirs ?? "").split(",")) if (d.trim()) cmd.push("--add-dir", expandHome(d.trim()))
+  if (run.model) cmd.push("--model", run.model)
+  return cmd
+}
+
 function buildCommand(job: Job, workdir: string, env: Record<string, string>, runs: string): string[] | string {
   const h = job.header
   const kind = h.kind!
@@ -119,13 +157,16 @@ function buildCommand(job: Job, workdir: string, env: Record<string, string>, ru
   if (kind === "spinuptui") return [...selfCommand(), ...splitArgs(job.body)]
   const agent = agentOf(h)!
   const prompt = preamble(h.id!, agent === "codex" ? "agent/codex" : "agent/claude", h.created_by!, runs) + job.body
-  const bin = Bun.which(agent, { PATH: env.PATH })
-  if (!bin) return `${agent} not found on PATH`
-  if (agent === "codex") return [bin, "exec", "-s", h.sandbox || "read-only", "-C", workdir, "--skip-git-repo-check", prompt]
-  const cmd = [bin, "-p", prompt, "--output-format", "text", "--permission-mode", "default", "--allowedTools", h.allow || DEFAULT_ALLOW, "--disallowedTools", ALWAYS_DENY]
-  for (const d of (h.add_dirs ?? "").split(",")) if (d.trim()) cmd.push("--add-dir", expandHome(d.trim()))
-  if (h.model) cmd.push("--model", h.model)
-  return cmd
+  return agentCommand({ agent, prompt, workdir, allow: h.allow, addDirs: h.add_dirs, model: h.model, sandbox: h.sandbox }, env)
+}
+
+// What a finished process means. An agent that exits 0 after saying it's blocked
+// did no work, whatever its exit code says.
+export function outcomeOf(agent: boolean, code: number | null, timedOut: boolean, output: string): RunStatus {
+  if (agent && code !== 0 && AUTH_FAIL_RE.test(output)) return "auth"
+  if (timedOut) return "timeout"
+  if (code === 0) return agent && BLOCKED_RE.test(output) ? "blocked" : "ok"
+  return !agent && code === BLOCKED_EXIT ? "blocked" : "failed"
 }
 
 export interface RunOutcome {
@@ -161,14 +202,13 @@ export async function runJob(source: Source, job: Job, occurrence: Date, now = n
       const r = await runProcess(cmd, { cwd: workdir, env, timeoutMs })
       code = r.code
       output = r.output
-      status = r.timedOut ? "timeout" : r.code === 0 ? "ok" : "failed"
+      status = outcomeOf(!!agentOf(h), r.code, r.timedOut, r.output)
       if (r.timedOut) output += `\n\n[scheduler] killed after ${timeoutMs / 60_000} minutes`
     } catch (err) {
       status = "error"
       output = `could not start: ${(err as Error).message}`
     }
   }
-  if (agentOf(h) && status !== "ok" && AUTH_FAIL_RE.test(output)) status = "auth"
   return finish(source, job, occurrence, started, new Date(), status, code, output, reportRel)
 }
 
@@ -227,19 +267,25 @@ async function finish(
 
   let notified: RunOutcome["notified"] = "skipped"
   if ((h.notify || "beacon") !== "none") {
-    const icon = { ok: "✅", failed: "❌", timeout: "⏱️", error: "❌" }[status as Exclude<RunStatus, "auth">] ?? "•"
+    const icon = { ok: "✅", failed: "❌", blocked: "🚧", timeout: "⏱️", error: "❌" }[status as Exclude<RunStatus, "auth">] ?? "•"
     notified = await notify(
       `${icon} Job ${id} (${status}, ${duration(seconds)})\n\n${summaryOf(job, output) || "(no output)"}\n\nReport: ${source.name}/${reportRel}\nQueued by: ${h.created_by}`,
       h.to,
+      status === "ok" ? undefined : [[runAgainButton(source.name, id)]],
     )
   }
   return { status, report: reportRel, notified }
 }
 
+// A tap re-runs the job exactly as written: it can't add permissions.
+export function runAgainButton(source: string, id: string): BeaconButton {
+  return { text: `Run ${id} again`, action: "scheduler.run", payload: { source, id } }
+}
+
 // In-process Beacon send. Never throws; returns "sent" or why it wasn't.
-export async function notify(text: string, to?: string): Promise<string> {
+export async function notify(text: string, to?: string, buttons?: BeaconButton[][], silent = false): Promise<string> {
   try {
-    const r = await beaconSend(beaconFromConfig(loadConfig()), text, { to: to || null, silent: false })
+    const r = await beaconSend(beaconFromConfig(loadConfig()), text, { to: to || null, silent, ...(buttons ? { replyMarkup: pageMarkup(buttons) } : {}) })
     return r.ok ? "sent" : `${r.reason}: ${r.message}`
   } catch (err) {
     return `error: ${(err as Error).message}`