@bybrawe/opencode-loop 0.5.33 → 0.5.34

package/commands/loop.md

@@ -1,5 +1,5 @@
 ---
-description: Start an OpenCode auto-continue loop. Usage: /loop 5m <task>
+description: "Auto-continue or schedule work. /loop <task> = every idle; /loop every 5m <task> = recurring; /loop after 5m <task> = once."
 agent: opencode-loop-local
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bybrawe/opencode-loop",
-  "version": "0.5.33",
+  "version": "0.5.34",
   "description": "Claude Code/Codex style /loop and experimental goal mode for OpenCode: heartbeat scheduler, idle-safe loops, scheduled commands, compact scheduling, verification, checkpoints, and persistent coding goals.",
   "type": "module",
   "main": "src/index.js",
@@ -21,8 +21,8 @@
     "build:plugin": "bun build src/source/v1.js --outfile=src/index.js --target=bun --format=esm --external=@opencode-ai/plugin/tool",
     "build:plugin:npm": "npm run build:plugin",
     "prepack": "node --check src/index.js",
-    "check": "node --check src/source/v1.js && node --check src/source/core/args.js && node --check src/source/core/state.js && node --check src/source/core/jobs.js && node --check src/source/core/process.js && node --check src/source/opencode/sdk.js && node --check src/source/opencode/session-context.js && node --check src/source/opencode/command-router.js && node --check src/source/opencode/goal-commands.js && node --check src/source/opencode/loop-commands.js && node --check src/source/opencode/loop-registration.js && node --check src/source/runtime/session-activity.js && node --check src/source/runtime/session-status.js && node --check src/source/runtime/compaction.js && node --check src/source/runtime/action-dispatch.js && node --check src/source/runtime/run-finalization.js && node --check src/source/runtime/run-admission.js && node --check src/source/runtime/executor.js && node --check src/source/runtime/scheduler.js && node --check src/source/runtime/goal-prompt.js && node --check src/source/runtime/goal-report.js && node --check src/source/runtime/goal-evidence.js && node --check src/source/runtime/goal-runtime.js && node --check src/source/runtime/goal-policy.js && node --check src/source/runtime/goal-steering.js && node --check src/source/runtime/job-workspace.js && node --check src/source/opencode2/prompt-runtime.js && node --check src/source/opencode2/diagnostics.js && node --check src/source/opencode2/logging.js && node --check src/source/legacy-v1.js && node --check src/index.js && node --check scripts/install-node.mjs && node --check scripts/install-with-goals.mjs && node --check scripts/loopd.mjs && node --check scripts/install-test.mjs && node --check scripts/goal-companion-test.mjs && node --check scripts/loopd-test.mjs && node --check scripts/smoke-test.mjs && node --check scripts/host-adapter-contract-test.mjs && node --check scripts/command-router-test.mjs && node --check scripts/goal-command-handlers-test.mjs && node --check scripts/loop-command-handlers-test.mjs && node --check scripts/loop-registration-test.mjs && node --check scripts/session-activity-test.mjs && node --check scripts/session-status-test.mjs && node --check scripts/compaction-runtime-test.mjs && node --check scripts/executor-runtime-test.mjs && node --check scripts/scheduler-runtime-test.mjs && node --check scripts/goal-runtime-test.mjs && node --check scripts/goal-policy-test.mjs && node --check scripts/goal-steering-test.mjs && node --check scripts/job-workspace-test.mjs && node --check scripts/v2-prompt-runtime-test.mjs && node --check scripts/v2-prompt-interval-test.mjs && node --check scripts/v2-command-runtime-test.mjs && node --check scripts/v2-command-adapter-test.mjs && node --check scripts/v2-diagnostics-test.mjs && node --check scripts/v2-logging-test.mjs && node --check scripts/comprehensive-watchdog.mjs && node --check scripts/comprehensive-test.mjs && node --check scripts/host-loop-canary.mjs && node --check scripts/host-goal-steering-canary.mjs && node --check scripts/publish-workflow-test.mjs",
-    "test": "node scripts/publish-workflow-test.mjs && node scripts/command-router-test.mjs && node scripts/goal-command-handlers-test.mjs && node scripts/loop-command-handlers-test.mjs && node scripts/loop-registration-test.mjs && node scripts/session-activity-test.mjs && node scripts/session-status-test.mjs && node scripts/compaction-runtime-test.mjs && node scripts/action-dispatch-test.mjs && node scripts/run-finalization-test.mjs && node scripts/run-admission-test.mjs && node scripts/executor-runtime-test.mjs && node scripts/scheduler-runtime-test.mjs && node scripts/goal-runtime-test.mjs && node scripts/goal-policy-test.mjs && node scripts/goal-steering-test.mjs && node scripts/job-workspace-test.mjs && node scripts/v2-prompt-runtime-test.mjs && node scripts/v2-prompt-interval-test.mjs && node scripts/v2-command-runtime-test.mjs && node scripts/v2-command-adapter-test.mjs && node scripts/v2-diagnostics-test.mjs && node scripts/v2-logging-test.mjs && node scripts/install-test.mjs && node scripts/goal-companion-test.mjs && node scripts/loopd-test.mjs && node scripts/smoke-test.mjs && node scripts/host-adapter-contract-test.mjs && node scripts/comprehensive-watchdog.mjs",
+    "check": "node --check src/source/v1.js && node --check src/source/core/args.js && node --check src/source/core/continuation.js && node --check src/source/core/schedule-syntax.js && node --check src/source/core/state.js && node --check src/source/core/jobs.js && node --check src/source/core/process.js && node --check src/source/opencode/sdk.js && node --check src/source/opencode/session-context.js && node --check src/source/opencode/command-router.js && node --check src/source/opencode/goal-commands.js && node --check src/source/opencode/loop-commands.js && node --check src/source/opencode/loop-registration.js && node --check src/source/runtime/session-activity.js && node --check src/source/runtime/session-status.js && node --check src/source/runtime/schedule-policy.js && node --check src/source/runtime/scheduler-diagnostics.js && node --check src/source/runtime/companion-goal.js && node --check src/source/runtime/loop-diagnostics.js && node --check src/source/runtime/compaction.js && node --check src/source/runtime/action-dispatch.js && node --check src/source/runtime/run-finalization.js && node --check src/source/runtime/run-admission.js && node --check src/source/runtime/executor.js && node --check src/source/runtime/scheduler.js && node --check src/source/runtime/goal-prompt.js && node --check src/source/runtime/goal-report.js && node --check src/source/runtime/goal-evidence.js && node --check src/source/runtime/goal-runtime.js && node --check src/source/runtime/goal-policy.js && node --check src/source/runtime/goal-steering.js && node --check src/source/runtime/job-workspace.js && node --check src/source/opencode2/prompt-runtime.js && node --check src/source/opencode2/diagnostics.js && node --check src/source/opencode2/logging.js && node --check src/source/legacy-v1.js && node --check src/index.js && node --check scripts/install-node.mjs && node --check scripts/install-with-goals.mjs && node --check scripts/loopd.mjs && node --check scripts/install-test.mjs && node --check scripts/goal-companion-test.mjs && node --check scripts/loopd-test.mjs && node --check scripts/smoke-test.mjs && node --check scripts/host-adapter-contract-test.mjs && node --check scripts/command-router-test.mjs && node --check scripts/goal-command-handlers-test.mjs && node --check scripts/loop-command-handlers-test.mjs && node --check scripts/loop-registration-test.mjs && node --check scripts/schedule-syntax-test.mjs && node --check scripts/schedule-policy-test.mjs && node --check scripts/session-activity-test.mjs && node --check scripts/session-status-test.mjs && node --check scripts/session-status-idle-recovery-test.mjs && node --check scripts/compaction-runtime-test.mjs && node --check scripts/executor-runtime-test.mjs && node --check scripts/scheduler-runtime-test.mjs && node --check scripts/goal-runtime-test.mjs && node --check scripts/goal-policy-test.mjs && node --check scripts/goal-steering-test.mjs && node --check scripts/job-workspace-test.mjs && node --check scripts/v2-prompt-runtime-test.mjs && node --check scripts/v2-prompt-interval-test.mjs && node --check scripts/v2-command-runtime-test.mjs && node --check scripts/v2-command-adapter-test.mjs && node --check scripts/v2-diagnostics-test.mjs && node --check scripts/v2-logging-test.mjs && node --check scripts/comprehensive-watchdog.mjs && node --check scripts/comprehensive-test.mjs && node --check scripts/host-loop-canary.mjs && node --check scripts/host-goal-steering-canary.mjs && node --check scripts/publish-workflow-test.mjs",
+    "test": "node scripts/publish-workflow-test.mjs && node scripts/command-router-test.mjs && node scripts/goal-command-handlers-test.mjs && node scripts/loop-command-handlers-test.mjs && node scripts/loop-registration-test.mjs && node scripts/schedule-syntax-test.mjs && node scripts/schedule-policy-test.mjs && node scripts/session-activity-test.mjs && node scripts/session-status-test.mjs && node scripts/session-status-idle-recovery-test.mjs && node scripts/compaction-runtime-test.mjs && node scripts/action-dispatch-test.mjs && node scripts/run-finalization-test.mjs && node scripts/run-admission-test.mjs && node scripts/executor-runtime-test.mjs && node scripts/scheduler-runtime-test.mjs && node scripts/goal-runtime-test.mjs && node scripts/goal-policy-test.mjs && node scripts/goal-steering-test.mjs && node scripts/job-workspace-test.mjs && node scripts/v2-prompt-runtime-test.mjs && node scripts/v2-prompt-interval-test.mjs && node scripts/v2-command-runtime-test.mjs && node scripts/v2-command-adapter-test.mjs && node scripts/v2-diagnostics-test.mjs && node scripts/v2-logging-test.mjs && node scripts/install-test.mjs && node scripts/goal-companion-test.mjs && node scripts/loopd-test.mjs && node scripts/smoke-test.mjs && node scripts/host-adapter-contract-test.mjs && node scripts/comprehensive-watchdog.mjs",
     "canary:host": "node scripts/host-loop-canary.mjs && node scripts/host-goal-steering-canary.mjs",
     "install:global": "node scripts/install-with-goals.mjs",
     "pack:zip": "node scripts/make-zip.mjs"

package/scripts/comprehensive-test.mjs

@@ -243,7 +243,7 @@ async function testParserAndPresets() {
     assert.match(preset.action, /Test command hint: npm run ci/)
 
     const toastCount = h.records.toasts.length
-    await h.command("loop", "nonsense")
+    await h.command("loop", "every nope continue")
     await h.command("loop", "5m")
     assert.equal(h.records.toasts.length, toastCount + 2)
     assert.ok(h.records.toasts.slice(-2).every((item) => item.variant === "warning"))

package/scripts/host-loop-canary.mjs

@@ -10,7 +10,7 @@ import { fileURLToPath, pathToFileURL } from "node:url"
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
 const isWindows = process.platform === "win32"
-const LOOP_OBJECTIVE = "real host loop canary"
+const LOOP_OBJECTIVE = "devam et"
 const RUN_NOW_NATURAL_OBJECTIVE = "real host loop-now natural canary"
 const RUN_NOW_TARGET_OBJECTIVE = "real host loop-now target canary"
 
@@ -332,7 +332,9 @@ async function main() {
       signal: AbortSignal.timeout(timeoutMs),
     })
 
-    const command = sendCommand("loop", `0s --max-runs 3 ${LOOP_OBJECTIVE}`).catch((error) => {
+    // No duration token on purpose: this proves `/loop devam et` is the real idle-loop
+    // shorthand on a live OpenCode host, not only a parser-unit-test behavior.
+    const command = sendCommand("loop", `--max-runs 3 ${LOOP_OBJECTIVE}`).catch((error) => {
       commandError = error
       return null
     })
@@ -356,7 +358,10 @@ async function main() {
     try { persisted = JSON.parse(await readFile(stateFile, "utf8")) } catch {}
     if (persisted?.jobs?.length) {
       const loop = persisted.jobs.find((item) => item.name === "default" || item.action === LOOP_OBJECTIVE)
-      if (loop) assert.ok((loop.runCount || 0) >= 3, `persisted Loop run count was lower than provider turn count: ${JSON.stringify(loop)}`)
+      if (loop) {
+        assert.equal(loop.scheduleMode, "idle", `durationless continuation must persist as idle mode: ${JSON.stringify(loop)}`)
+        assert.ok((loop.runCount || 0) >= 3, `persisted Loop run count was lower than provider turn count: ${JSON.stringify(loop)}`)
+      }
     }
 
     await sendCommand("loop", `10m --no-now --name natural --multi --max-runs 1 ${RUN_NOW_NATURAL_OBJECTIVE}`)

package/scripts/loop-command-handlers-test.mjs

@@ -53,6 +53,8 @@ function harness(initialStates = {}, overrides = {}) {
     appendLoopLog: async (...args) => { logs.push(args) },
     readFile: overrides.readFile || (async () => { throw new Error("missing") }),
     writeFile: async (...args) => { fileWrites.push(args) },
+    listPersistedLoopSessions: overrides.listPersistedLoopSessions || (async () => []),
+    findDedicatedGoalForSession: overrides.findDedicatedGoalForSession || (async () => undefined),
     runtimeVersion: "v-test",
     runtimePlatform: "test-platform",
   })
@@ -148,7 +150,9 @@ assert.throws(() => createLoopCommandHandlers({ clearActiveRun() {} }), /cancelD
   const text = h.messages[0][2]
   assert.match(text, /OpenCode loop status:/)
   assert.match(text, /1\. dev \(dev\): dev: 10s \[prompt\] -> Work on dev/)
-  assert.match(text, /runs=3 \| failures=1 \| due in 5s/)
+  assert.match(text, /schedule=every 10s, starts on next idle/)
+  assert.match(text, /state=due in 5s/)
+  assert.match(text, /runs=3 \| failures=1/)
   assert.match(text, /active,safe,ask-never,no-overlap/)
   assert.match(text, /goal:blocked,paused,checkpoint-only,git-checkpoint/)
 }
@@ -166,7 +170,19 @@ assert.throws(() => createLoopCommandHandlers({ clearActiveRun() {} }), /cancelD
     },
   }, { now: () => 10_000 })
   await h.handlers.statusLoop("/work", {}, sessionID)
-  assert.match(h.messages[0][2], /due in 5s/, "--no-now status must count the first interval from createdAt")
+  assert.match(h.messages[0][2], /state=due in 5s/, "--no-now status must count the first interval from createdAt")
+}
+
+{
+  const sessionID = "status-idle"
+  const h = harness({
+    [sessionID]: {
+      jobs: [loopJob("continue", { intervalMs: 0, lastRunAt: 0, scheduleMode: "idle", action: "continue" })],
+    },
+  })
+  await h.handlers.statusLoop("/work", {}, sessionID)
+  assert.match(h.messages[0][2], /schedule=every idle/)
+  assert.match(h.messages[0][2], /state=waiting for idle/)
 }
 
 {
@@ -199,6 +215,9 @@ assert.throws(() => createLoopCommandHandlers({ clearActiveRun() {} }), /cancelD
   await h.handlers.helpLoop({}, "help")
   const text = h.messages[0][2]
   assert.match(text, /OpenCode Loop help:/)
+  assert.match(text, /\/loop continue the project/)
+  assert.match(text, /\/loop every 5m continue the project/)
+  assert.match(text, /\/loop after 5m continue the project/)
   assert.match(text, /\/loop-goal finish the feature/)
   assert.match(text, /\/loop-doctor \| \/loop-init \| \/loop-export/)
 }
@@ -231,13 +250,23 @@ assert.throws(() => createLoopCommandHandlers({ clearActiveRun() {} }), /cancelD
 
 {
   const sessionID = "doctor"
-  const h = harness({ [sessionID]: { jobs: [loopJob("a"), loopJob("b")] } })
+  const h = harness({ [sessionID]: { jobs: [loopJob("a"), loopJob("b")] } }, {
+    listPersistedLoopSessions: async () => [
+      { sessionID, current: true, jobs: 2, enabled: 2, neverRan: 0 },
+      { sessionID: "other-session", current: false, jobs: 1, enabled: 1, neverRan: 1 },
+    ],
+    findDedicatedGoalForSession: async () => ({ id: "goal-abcdef123456", status: "active" }),
+  })
   await h.handlers.doctorLoop("/repo", {}, sessionID)
   const text = h.messages[0][2]
   assert.match(text, /OpenCode Loop doctor:/)
   assert.match(text, /- plugin: opencode-loop/)
   assert.match(text, /- project directory: \/repo/)
-  assert.match(text, /- active jobs: 2/)
+  assert.match(text, /- current session: doctor/)
+  assert.match(text, /- current-session jobs: 2/)
+  assert.match(text, /- dedicated \/goal: active/)
+  assert.match(text, /- other persisted sessions with enabled jobs: 1/)
+  assert.match(text, /other session other-session: jobs=1, enabled=1, never-ran=1/)
   assert.match(text, /- node: v-test/)
   assert.match(text, /- platform: test-platform/)
   assert.match(text, /experimental goal smoke test/)

package/scripts/loop-registration-test.mjs

@@ -11,6 +11,7 @@ function harness(initialStates = {}, overrides = {}) {
   const messages = []
   const logs = []
   const contexts = new Map(Object.entries(overrides.contexts || {}))
+  const dedicatedGoals = new Map(Object.entries(overrides.dedicatedGoals || {}))
 
   const { addLoop } = createLoopRegistration({
     snapshotPaths: async (directory, files) => {
@@ -30,6 +31,7 @@ function harness(initialStates = {}, overrides = {}) {
     appendLoopLog: async (...args) => { logs.push(args) },
     normalizedModelRef: (value) => value ? `normalized:${value}` : undefined,
     getSessionExecutionContext: (sessionID) => contexts.get(sessionID),
+    findDedicatedGoalForSession: async (_directory, sessionID) => dedicatedGoals.get(sessionID),
     defaultActiveGuardMs: overrides.defaultActiveGuardMs ?? 45_000,
   })
 
@@ -50,7 +52,7 @@ assert.equal(sameLoopDefinition(null, {}), false)
   const sessionID = "invalid"
   const h = harness()
   const client = {}
-  await h.addLoop("/work", client, sessionID, "not-a-duration and no defaults")
+  await h.addLoop("/work", client, sessionID, "every nope continue")
   assert.equal(h.writes.length, 0)
   assert.equal(h.due.length, 0)
   assert.equal(h.idle.length, 0)
@@ -58,7 +60,59 @@ assert.equal(sameLoopDefinition(null, {}), false)
   assert.equal(h.toasts.length, 1)
   assert.equal(h.toasts[0][0], client)
   assert.equal(h.toasts[0][2], "warning")
-  assert.match(h.toasts[0][1], /Usage: \/loop/)
+  assert.match(h.toasts[0][1], /Invalid every schedule/)
+}
+
+{
+  const sessionID = "shorthand-idle"
+  const h = harness()
+  await h.addLoop("/work", {}, sessionID, "continue the project")
+  const job = h.states.get(sessionID).jobs[0]
+  assert.equal(job.action, "continue the project")
+  assert.equal(job.intervalMs, 0)
+  assert.equal(job.scheduleMode, "idle")
+  assert.equal(job.scheduleSyntax, "idle-shorthand")
+  assert.equal(job.immediate, true)
+  assert.equal(job.maxRuns, 0)
+  assert.equal(h.idle.length, 1)
+}
+
+{
+  const sessionID = "explicit-idle"
+  const h = harness()
+  await h.addLoop("/work", {}, sessionID, "idle continue forever")
+  const job = h.states.get(sessionID).jobs[0]
+  assert.equal(job.action, "continue forever")
+  assert.equal(job.intervalMs, 0)
+  assert.equal(job.scheduleMode, "idle")
+  assert.equal(job.scheduleSyntax, "idle")
+}
+
+{
+  const sessionID = "every"
+  const h = harness()
+  await h.addLoop("/work", {}, sessionID, "every 5m continue the project")
+  const job = h.states.get(sessionID).jobs[0]
+  assert.equal(job.intervalMs, 300_000)
+  assert.equal(job.scheduleMode, "interval")
+  assert.equal(job.scheduleSyntax, "every")
+  assert.equal(job.immediate, false)
+  assert.equal(job.maxRuns, 0)
+  assert.equal(h.idle.length, 0)
+  assert.equal(h.due.length, 1)
+}
+
+{
+  const sessionID = "after"
+  const h = harness()
+  await h.addLoop("/work", {}, sessionID, "after 5m continue once")
+  const job = h.states.get(sessionID).jobs[0]
+  assert.equal(job.intervalMs, 300_000)
+  assert.equal(job.scheduleMode, "once")
+  assert.equal(job.scheduleSyntax, "after")
+  assert.equal(job.immediate, false)
+  assert.equal(job.maxRuns, 1)
+  assert.equal(h.idle.length, 0)
 }
 
 {
@@ -73,6 +127,7 @@ assert.equal(sameLoopDefinition(null, {}), false)
   assert.equal(job.model, "ctx-model")
   assert.equal(job.activeRecoveryMs, 45_000)
   assert.equal(job.immediate, true)
+  assert.equal(job.scheduleMode, "idle")
   assert.equal(h.writes.length, 1)
   assert.deepEqual(h.due, [["/work", client, sessionID]])
   assert.deepEqual(h.idle, [["/work", client, sessionID]])
@@ -139,6 +194,25 @@ assert.equal(sameLoopDefinition(null, {}), false)
   assert.equal(job.activeRecoveryMs, 180_000)
 }
 
+{
+  const sessionID = "dedicated-goal-conflict"
+  const h = harness({}, { dedicatedGoals: { [sessionID]: { id: "goal-123", status: "active", sessionID } } })
+  await h.addLoop("/work", {}, sessionID, "continue the same work")
+  assert.equal(h.writes.length, 0)
+  assert.equal(h.due.length, 0)
+  assert.equal(h.idle.length, 0)
+  assert.equal(h.logs[0][1], "goal-overlap-blocked")
+  assert.match(h.toasts[0][1], /dedicated \/goal already owns continuation/)
+}
+
+{
+  const sessionID = "dedicated-goal-override"
+  const h = harness({}, { dedicatedGoals: { [sessionID]: { id: "goal-123", status: "active", sessionID } } })
+  await h.addLoop("/work", {}, sessionID, "--allow-goal-overlap continue intentionally")
+  assert.equal(h.writes.length, 1)
+  assert.equal(h.states.get(sessionID).jobs[0].allowGoalOverlap, true)
+}
+
 {
   const sessionID = "long-interval"
   const h = harness()
@@ -195,7 +269,7 @@ assert.equal(sameLoopDefinition(null, {}), false)
   const sessionID = "dry-run"
   const client = {}
   const h = harness()
-  await h.addLoop("/work", client, sessionID, "0s --dry-run inspect only")
+  await h.addLoop("/work", client, sessionID, "--dry-run inspect only")
   assert.equal(h.writes.length, 0)
   assert.equal(h.due.length, 0)
   assert.equal(h.idle.length, 0)

package/scripts/schedule-policy-test.mjs

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict"
+import {
+  dueJobs,
+  inferredScheduleMode,
+  jobDueAt,
+  jobIsDue,
+  nextDueDelay,
+  scheduleDescription,
+  scheduleState,
+} from "../src/source/runtime/schedule-policy.js"
+
+const current = 1_000_000
+const base = {
+  id: "job",
+  enabled: true,
+  paused: false,
+  maxRuns: 0,
+  runCount: 0,
+  intervalMs: 0,
+  immediate: true,
+  lastRunAt: 0,
+  createdAt: new Date(current - 10_000).toISOString(),
+}
+
+{
+  const job = { ...base, scheduleMode: "idle" }
+  assert.equal(inferredScheduleMode(job), "idle")
+  assert.equal(jobDueAt(job, current), current)
+  assert.equal(jobIsDue(job, current), true)
+  assert.equal(scheduleDescription(job), "every idle")
+  assert.equal(scheduleState(job, current), "waiting for idle")
+}
+
+{
+  const job = {
+    ...base,
+    scheduleMode: "interval",
+    intervalMs: 300_000,
+    immediate: false,
+    createdAt: new Date(current).toISOString(),
+  }
+  assert.equal(jobDueAt(job, current), current + 300_000)
+  assert.equal(jobIsDue(job, current), false)
+  assert.equal(scheduleDescription(job), "every 5m, first after 5m")
+  assert.equal(scheduleState(job, current), "due in 5m")
+}
+
+{
+  const job = {
+    ...base,
+    scheduleMode: "interval",
+    intervalMs: 300_000,
+    immediate: true,
+  }
+  assert.equal(jobDueAt(job, current), current)
+  assert.equal(scheduleDescription(job), "every 5m, starts on next idle")
+}
+
+{
+  const job = {
+    ...base,
+    scheduleMode: "once",
+    intervalMs: 300_000,
+    immediate: false,
+    maxRuns: 1,
+    createdAt: new Date(current).toISOString(),
+  }
+  assert.equal(inferredScheduleMode(job), "once")
+  assert.equal(scheduleDescription(job), "once after 5m")
+  assert.equal(jobIsDue(job, current + 299_999), false)
+  assert.equal(jobIsDue(job, current + 300_000), true)
+  const completed = { ...job, runCount: 1 }
+  assert.equal(jobDueAt(completed, current + 300_000), Infinity)
+}
+
+{
+  const watch = { ...base, watchPaths: ["progress.md"], watchTriggered: false }
+  assert.equal(inferredScheduleMode(watch), "watch")
+  assert.equal(jobDueAt(watch, current), Infinity)
+  assert.equal(jobDueAt({ ...watch, watchTriggered: true }, current), current)
+}
+
+{
+  const expired = {
+    ...base,
+    intervalMs: 3_600_000,
+    immediate: false,
+    maxRuntimeMs: 5_000,
+    createdAt: new Date(current - 6_000).toISOString(),
+  }
+  assert.equal(jobDueAt(expired, current), current, "expired max-runtime must wake admission so it can remove the job")
+}
+
+{
+  const dueNow = { ...base, id: "normal" }
+  const targeted = { ...base, id: "targeted", runNowRequestedAt: current }
+  const state = { jobs: [dueNow, targeted] }
+  assert.deepEqual(dueJobs(state, current).map((job) => job.id), ["targeted", "normal"])
+  assert.equal(nextDueDelay(state, current), 0)
+}
+
+{
+  const delayed = {
+    ...base,
+    intervalMs: 60_000,
+    immediate: false,
+    createdAt: new Date(current).toISOString(),
+  }
+  assert.equal(nextDueDelay({ jobs: [delayed] }, current), 60_000)
+  assert.equal(jobIsDue({ ...delayed, paused: true }, current + 60_000), false)
+  assert.equal(jobIsDue({ ...delayed, enabled: false }, current + 60_000), false)
+}
+
+console.log("schedule policy tests passed")

package/scripts/schedule-syntax-test.mjs

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict"
+import { normalizeLoopScheduleArgs } from "../src/source/core/schedule-syntax.js"
+
+{
+  const result = normalizeLoopScheduleArgs("continue the project")
+  assert.equal(result.ok, true)
+  assert.equal(result.args, "continue the project")
+  assert.equal(result.defaults.intervalMs, 0)
+  assert.equal(result.defaults.immediate, true)
+  assert.equal(result.scheduleMode, "idle")
+  assert.equal(result.scheduleSyntax, "idle-shorthand")
+}
+
+{
+  const result = normalizeLoopScheduleArgs("--safe --ask-never continue the project")
+  assert.equal(result.ok, true)
+  assert.equal(result.defaults.intervalMs, 0)
+  assert.equal(result.args, "--safe --ask-never continue the project")
+}
+
+{
+  const result = normalizeLoopScheduleArgs("idle continue forever")
+  assert.equal(result.args, "continue forever")
+  assert.equal(result.defaults.intervalMs, 0)
+  assert.equal(result.defaults.immediate, true)
+  assert.equal(result.scheduleMode, "idle")
+}
+
+{
+  const result = normalizeLoopScheduleArgs("every 5m continue forever")
+  assert.equal(result.args, "continue forever")
+  assert.equal(result.defaults.intervalMs, 300_000)
+  assert.equal(result.defaults.immediate, false)
+  assert.equal(result.scheduleMode, "interval")
+  assert.equal(result.scheduleSyntax, "every")
+}
+
+{
+  const result = normalizeLoopScheduleArgs("after 5m continue once")
+  assert.equal(result.args, "continue once")
+  assert.equal(result.defaults.intervalMs, 300_000)
+  assert.equal(result.defaults.immediate, false)
+  assert.equal(result.defaults.maxRuns, 1)
+  assert.equal(result.scheduleMode, "once")
+}
+
+{
+  const result = normalizeLoopScheduleArgs("in 30s ping once")
+  assert.equal(result.args, "ping once")
+  assert.equal(result.defaults.intervalMs, 30_000)
+  assert.equal(result.defaults.maxRuns, 1)
+  assert.equal(result.scheduleSyntax, "after")
+}
+
+{
+  const result = normalizeLoopScheduleArgs("5m continue legacy")
+  assert.equal(result.args, "5m continue legacy")
+  assert.equal(result.scheduleMode, "interval")
+  assert.equal(result.scheduleSyntax, "legacy")
+}
+
+{
+  const result = normalizeLoopScheduleArgs("--allow-goal-overlap continue")
+  assert.equal(result.args, "continue")
+  assert.equal(result.allowGoalOverlap, true)
+  assert.equal(result.scheduleMode, "idle")
+}
+
+{
+  const result = normalizeLoopScheduleArgs("every nope continue")
+  assert.equal(result.ok, false)
+  assert.match(result.error, /Invalid every schedule/)
+}
+
+console.log("schedule syntax tests passed")

package/scripts/session-status-idle-recovery-test.mjs

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict"
+import { clearSessionActivity } from "../src/source/runtime/session-activity.js"
+import { createSessionStatusRuntime } from "../src/source/runtime/session-status.js"
+
+const activeRuns = new Map()
+const logs = []
+let clock = 100_000
+let completion = "completed"
+
+const runtime = createSessionStatusRuntime({
+  activeRuns,
+  now: () => clock,
+  sessionStatusCacheMs: 0,
+  appendLoopLog: async (...args) => logs.push(args),
+  activeRunCompletionFromMessages: async () => completion,
+})
+
+const busyClient = {
+  session: {
+    status: async () => ({ data: { session: { type: "busy" } } }),
+  },
+}
+
+try {
+  runtime.markSessionStatus("session", "busy", clock - 2_000)
+  assert.equal(await runtime.sessionStatusType(busyClient, "session", "/repo"), "idle")
+  assert.equal(logs.at(-1)[1], "status-message-idle-recovery")
+  assert.equal(logs.at(-1)[2].staleStatus, "busy")
+
+  runtime.clearSessionStatus("session")
+  completion = "incomplete"
+  clock += 5_000
+  assert.equal(await runtime.sessionStatusType(busyClient, "session", "/repo"), "busy", "an unfinished tail must never be force-recovered")
+
+  runtime.clearSessionStatus("session")
+  completion = "unknown"
+  clock += 5_000
+  assert.equal(await runtime.sessionStatusType(busyClient, "session", "/repo"), "busy", "unknown tail completion must remain conservative")
+
+  console.log("session status idle recovery tests passed")
+} finally {
+  activeRuns.clear()
+  clearSessionActivity("session")
+}