Harness spec 2.0.0: background work is a job — commands and subagents alike, seen and steered

One registry per process, every job owned by a session: bash's background commands (and a command
still running at its timeout, which now goes to the background instead of being killed) and
subagents started with task background: true. job_list, job_output, job_stop (the former
bash_list, bash_output, bash_kill) and the new job_send and report; a finished job wakes the owning
session in every front end with its marked note. The TUI counts jobs, lists them (/jobs), opens a
command's output, enters a subagent and messages it, moves a command to the background (ctrl+b)
and asks before quitting with jobs running. The link gains the jobs capability. Subagents get a
session row of their own, the spec's preamble and agent texts, and their errors reach the report.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

tests/jobs-wake.test.ts

@@ -1,15 +1,15 @@
-// A background job that ends wakes the session (after LLeMbas's jobs): the exit is heard,
-// the note says which job, how it ended and the output not yet read; mid-task the model gets it at
-// its next step, and a model that had finished carries on with it rather than stopping.
+// A background job that ends wakes the session that owns it (harness spec loop.json `jobs`): mid-task
+// the model gets the note at its next step, under its mark; idle, the note starts a turn of its own,
+// marked `machine`; a model that had finished carries on with a note that arrived meanwhile.
 import { afterEach, expect, test } from "bun:test"
 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { createApp } from "../src/app.ts"
-import type { AskReply } from "../src/bus/index.ts"
+import type { AskReply, Event } from "../src/bus/index.ts"
 import { paths } from "../src/config/paths.ts"
 import { JOB_MARK } from "../src/session/engine.ts"
-import { jobNote, onJobExit, startJob, type Job } from "../src/tool/jobs.ts"
+import { MARKS } from "../src/jobs/note.ts"
 import { delta, fakeProvider, toolCall, type Fake } from "./fake-provider.ts"
 
 let fake: Fake | undefined
@@ -22,21 +22,12 @@ function app(url: string) {
   return createApp({ cwd: mkdtempSync(join(tmpdir(), "ph-wake-")), mode: "auto", store: false, asker: { ask: async (): Promise<AskReply> => ({ kind: "once" }) } })
 }
 
-test("a job's end is heard, with what it printed that nobody has read", async () => {
-  const ended = new Promise<Job>((resolve) => {
-    const stop = onJobExit((j) => (stop(), resolve(j)))
-  })
-  startJob("echo built; exit 3", tmpdir(), process.env)
-  const job = await ended
-  const note = jobNote(job)
-  expect(note).toContain(`Background job ${job.id}`)
-  expect(note).toContain("exited with 3")
-  expect(note).toContain("built")
-  job.read = job.output.length
-  expect(jobNote(job)).toContain("printed nothing you had not read")
+test("the command mark is the spec's", () => {
+  expect(JOB_MARK).toBe(MARKS.command)
+  expect(JOB_MARK).toBe("[A background job you started has finished:]")
 })
 
-test("mid-task, the note reaches the model at its next step", async () => {
+test("mid-task, the note reaches the model at its next step, with its mark", async () => {
   fake = fakeProvider([
     { chunks: [toolCall(0, "t1", "bash", JSON.stringify({ command: "true", description: "check" }))] },
     { chunks: [delta({ content: "Seen it." })] },
@@ -46,10 +37,10 @@ test("mid-task, the note reaches the model at its next step", async () => {
   a.bus.on((e) => {
     if (e.type === "tool_start" && !noted) {
       noted = true
-      a.engine.note("Background job job7 (bun run build) exited with 0 after 4s.")
+      a.wake(`${MARKS.command}\njob7 (bun run build) exited with 0 after 4s.`, "⏎ job7")
     }
   })
-  await a.engine.prompt("build it")
+  await a.turns.prompt("build it")
   const second = fake.requests[1].messages as { role: string; content: string }[]
   const told = second.find((m) => m.role === "user" && String(m.content).startsWith(JOB_MARK))
   expect(told?.content).toContain("job7")
@@ -62,11 +53,58 @@ test("a model that had finished carries on with a job that ended meanwhile", asy
   a.bus.on((e) => {
     if (e.type === "text" && !noted) {
       noted = true
-      a.engine.note("Background job job2 (bun test) exited with 0 after 30s.")
+      a.wake(`${MARKS.command}\njob2 (bun test) exited with 0 after 30s.`, "⏎ job2")
     }
   })
-  const reason = await a.engine.prompt("run the tests in the background")
+  const reason = await a.turns.prompt("run the tests in the background")
   expect(reason).toBe("stop")
   expect(fake.requests.length).toBe(2)
   expect(a.engine.takeNotes()).toEqual([])
 })
+
+test("idle, a note is a turn of its own: marked machine on the prompt event and the stored message", async () => {
+  fake = fakeProvider([{ chunks: [delta({ content: "Noted." })] }])
+  const a = app(fake.url)
+  const events: Event[] = []
+  a.bus.on((e) => events.push(e))
+  a.wake(`${MARKS.command}\njob1 (make) exited with 0 after 2s.`, "⏎ job1 (make) exited with 0 after 2s.")
+  while (a.turns.current) await Bun.sleep(20)
+  const prompt = events.find((e) => e.type === "prompt")
+  expect(prompt).toMatchObject({ type: "prompt", text: "⏎ job1 (make) exited with 0 after 2s.", machine: true })
+  expect(a.engine.messages[0]).toMatchObject({ role: "user", machine: true })
+  expect(fake.requests[0].messages.at(-1).content).toStartWith(JOB_MARK)
+})
+
+test("a real job: ended during the turn it goes in at the next step; ended after it, it starts a turn of its own", async () => {
+  fake = fakeProvider([
+    // Ends at once: the note is in the turn's next step.
+    { chunks: [toolCall(0, "t1", "bash", JSON.stringify({ command: "echo built; exit 3", background: true, description: "build" }))] },
+    { chunks: [delta({ content: "Seen the quick one." })] },
+    // Ends after the turn: a machine turn of its own.
+    { chunks: [toolCall(0, "t2", "bash", JSON.stringify({ command: "sleep 0.4; echo late", background: true, description: "later" }))] },
+    { chunks: [delta({ content: "Running in the background." })] },
+    { chunks: [delta({ content: "It printed late." })] },
+  ])
+  const a = app(fake.url)
+  const events: Event[] = []
+  a.bus.on((e) => events.push(e))
+  await a.turns.prompt("build in the background")
+  const quick = fake.requests[1].messages.filter((m: any) => m.role === "user").at(-1).content as string
+  expect(quick).toStartWith(JOB_MARK)
+  expect(quick).toContain("job1 (echo built; exit 3) exited with 3")
+  expect(quick).toContain("built")
+  await a.turns.prompt("and a slow one")
+  expect(fake.requests.length).toBe(4)
+  const until = Date.now() + 5000
+  while (Date.now() < until && (fake.requests.length < 5 || a.turns.current)) await Bun.sleep(20)
+  const note = fake.requests[4].messages.at(-1).content as string
+  expect(note).toStartWith(JOB_MARK)
+  expect(note).toContain("job2 (sleep 0.4; echo late) exited with 0")
+  expect(note).toContain("late")
+  // The prompt, the quick note, the second prompt, the late note.
+  expect(fake.requests[4].messages.filter((m: any) => m.role === "user").length).toBe(4)
+  expect(events.filter((e) => e.type === "prompt" && e.machine)).toHaveLength(1)
+  expect(events.filter((e) => e.type === "job_note").map((e) => e.type === "job_note" && e.jobId)).toEqual(["job1", "job2"])
+  expect(events.filter((e) => e.type === "job" && e.state !== "update").map((e) => e.type === "job" && `${e.job.id} ${e.state}`)).toEqual(["job1 start", "job1 end", "job2 start", "job2 end"])
+  expect(a.jobs().map((j) => [j.id, j.state, j.exit])).toEqual([["job1", "error", 3], ["job2", "done", 0]])
+})