Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
10add6b
loops: freeze lessons-file, prompt-rules, stall-probes bundles (Harne…
dancingteeth Oct 21, 2026
ff365c6
loops: judge follows worker runtime (opencode default judge model)
dancingteeth Oct 21, 2026
d840100
loops: run harness2-ideas loops on the Cursor runtime
dancingteeth Oct 21, 2026
e65dd76
feat(loop): prompt rules — Facts head, deliverable guard, plain-text …
dancingteeth Oct 21, 2026
e4f10b2
fix(loop): route worker faults in deliverable nudges through one faul…
dancingteeth Oct 21, 2026
8a7b40a
fix(loop): confine deliverable paths to the repo
dancingteeth Oct 21, 2026
e6af195
test(doctor): scope the Telegram env reset to the one test that needs it
dancingteeth Oct 21, 2026
c366aa0
fix(cursor): treat Connect-node 'http/2 stream closed with error code…
dancingteeth Oct 21, 2026
4209773
fix(loop): own-line Facts heading in the stable head; exact verify co…
dancingteeth Oct 21, 2026
bea858e
feat(loop): lessons.md from green runs (Harness² lessons-file)
dancingteeth Oct 21, 2026
1faf3e0
feat(loop): stall probes — two guided workers on the first hard stall…
dancingteeth Oct 21, 2026
da02b88
fix(loop): stall probes — git-object workspace snapshots and probe-ro…
dancingteeth Oct 21, 2026
10df420
Merge origin/main (#46 squash) into feat/harness2-ideas
dancingteeth Oct 21, 2026
23fdcd2
fix(loop): stall-probe restore keeps ignored files and the branch; pa…
dancingteeth Oct 21, 2026
ee9e9d4
fix(loop): lessons.md opt-in, quoted as data, informative failure lines
dancingteeth Oct 21, 2026
c24c7b9
docs: CHANGELOG/README for #47 review — snapshot limits, lessons opt-…
dancingteeth Oct 21, 2026
083cc73
loops(lessons-file): GOAL.md — lessons defaults to false (opt-in)
dancingteeth Oct 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .cursor/loops/lessons-file/GOAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,14 @@ line of each verifier failure before green, deduped, newest kept, size-capped).
the same loop reads it and puts it in every worker prompt, in the stable prompt head (before
`## Workspace (git)`) so the provider prefix cache keeps working. Failed or parked runs never
write it. Workers can't edit it: `lessons.md` joins `FROZEN_LOOP_BASENAMES`. A `lessons`
boolean in `loop.json` (default `true`) turns read and write off together.
boolean in `loop.json` turns read and write on or off together. It defaults to `false`
(opt-in: set `"lessons": true`), per Paul in chat 2026-10-21 19:15 (review of #47); it was
originally specified as default `true`.

Canonical paths: new `src/loop/loopLessons.ts` (+ `src/loop/loopLessons.test.ts`),
`src/loop/loopPrompt.ts` (`LoopPromptInput.lessons?: string`), `src/loop/agentLoop.ts`
(read before iteration 1, write on the `complete: true` path only), `src/loop/loopConfig.ts`
(`lessons: z.boolean().default(true)`), `src/loop/loopFrozenFiles.ts`, `README.md`
(`lessons: z.boolean().default(false)` — opt-in, per Paul in chat 2026-10-21 19:15), `src/loop/loopFrozenFiles.ts`, `README.md`
(bundle layout + config table), `CHANGELOG.md` (Unreleased).

Code fact that shaped this goal: `failure-context.md` is **not** deleted after every run. It is
Expand Down
6 changes: 6 additions & 0 deletions .cursor/loops/lessons-file/acceptance.ts.txt
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,8 @@ function bundle(overrides: Record<string, unknown> = {}) {
exportPack: false,
exportRunReport: false,
exportTranscript: false,
// lessons is opt-in (default off since review of #47); these wiring tests opt in.
lessons: true,
...overrides,
}),
logPath: path.join(loopDir, 'log.ndjson'),
Expand Down Expand Up @@ -105,6 +107,10 @@ describe('lessons-file: module contract', () => {
expect(FROZEN_LOOP_BASENAMES as readonly string[]).toContain('lessons.md')
})

it('is opt-in: lessons defaults to false in loop.json', () => {
expect(loopConfigSchema.parse({ verify: VERIFY_CMD }).lessons).toBe(false)
})

it('reads nothing when the file is absent or blank', () => {
expect(readLessons(loopDir)).toBeUndefined()
fs.writeFileSync(lessonsPath(loopDir), ' \n')
Expand Down
2 changes: 1 addition & 1 deletion .cursor/loops/lessons-file/verify.sh
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ cd "$REPO_ROOT"
LOOP_DIR=".cursor/loops/lessons-file"
BASE_COMMIT="c4e7195"
ACC_SRC="$LOOP_DIR/acceptance.ts.txt"
ACC_SHA="3ee1f55b657e534decb9801eccf211bccc5818a0b2051e52b6fc86097c5d9208"
ACC_SHA="447ea4b525eb07433654c4b787b28002644dcc08a7c3366cf0a9f38613b2c3b1"
ACC_DIR="src/loop/__acceptance__"
ACC_DST="$ACC_DIR/lessonsFile.acceptance.test.ts"
COV_LOG="${TMPDIR:-/tmp}/lessons-file-coverage.log"
Expand Down
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,13 @@ Notable changes to `@dancingteeth/agent-looper`. Dates are UTC.

### Harness² ideas

- **`stallProbes`** — opt-in (`false` by default): on the first hard stall at `escalateAfterStagnation`, run two sequential probe workers with different prompt sections, snapshot/restore the git workspace between them, keep whichever verify result goes green or moves the failure fingerprint, log `probe: { variant, kept }`, then allow model escalation on later stalls. Disabled when `stagnationThreshold` is `0`. Restore puts back the branch (a probe's `git checkout -b` / detached HEAD) and HEAD (a probe's own commits are soft-reset; an unrelated HEAD is refused), restores `.gitignore` files and `info/exclude` first, and never deletes a path the snapshot's ignore rules ignore. A failed restore parks the run (`status: waiting`, failure domain `stall_probe_restore_failed`) with the restore error and the probe's original error.
- **Snapshot limits:** ignored files (`.env`, `node_modules/`, local data) are **not** saved in the snapshot — restore leaves them as they are rather than restoring them. Not safe with concurrent writers: restore reverts *every* change made in the worktree during the probe round (your editor, another loop, another process's commits), not only the probe's. Run one loop per worktree and don't edit it while probes run.
- **`lessons.md`** — **opt-in** (`"lessons": true`; default `false`). After a green verifier run, the harness writes deduped verify gotchas to the loop bundle; the next run injects them before `## Workspace (git)`. Gotchas are the most informative lines of each failure overcome (failing `[verify]` step + `FAIL`/error lines, stderr first; banner, progress and summary lines skipped; at most 3 lines of 240 chars per failure, 6000 chars per file). Verifier output is stored and injected as a fenced block labelled as data, not instructions (the fence is longer than any backtick run in the output). Workers cannot edit the file (frozen).
- **`deliverables`** — optional repo-relative paths in `loop.json`; worker prompts state them in `## Facts`, and the harness nudges the worker before verify when files are missing or empty (`deliverableNudges`, default `2`).
- **`## Facts` block** (#46) — the stable prompt head states the verifier command exactly as configured (not trimmed) and the deliverables, on its own line after the rules; without either, the head is byte-identical to before.
- **Plain-text tool-call warning + safety rule 7** (#46) — when the previous worker reply wrote tool calls as plain text instead of calling tools, the next prompt's volatile tail warns about it; safety rule 7 tells workers to use the tool interface.
- **Fix: HTTP/2 `CANCEL` crash** (#46) — a Connect-node `http/2 stream closed with error code CANCEL (0x8)` rejection nobody awaited (Cursor runtime) is now treated as a detached HTTP/2 transport error instead of crashing the process.

## 0.8.2 — 2026-10-20

Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,7 @@ Per-loop overrides in `loop.json`: `taskwarriorProject`, `taskwarriorUuid`, `hit
verify-logs/ # optional — sidecar verify stdout/stderr (`verifyLogMode`)
failure-domains.ndjson # optional — stagnation / max iterations / gate exhaust
failure-context.md # optional — written by meta-loop probe for fix loop
lessons.md # optional — verify gotchas from prior green runs (harness-owned)
```

### Verification (`verify` / `verifyMode`)
Expand Down Expand Up @@ -236,6 +237,7 @@ Legacy `loop.json` field `syncPostgres` maps to `syncOnSuccess`.
| `mode` | `forward` | `reverse` = clean-room rebuild (`templates/GOAL.reverse.template.md`) |
| `pauseAfterIteration` | `false` | Wait for Enter after each iteration (TTY only) |
| `injectFailureContext` | `false` | Read `failure-context.md` into the prompt (meta-loop fix rounds) |
| `lessons` | `false` | Opt-in: read/write `lessons.md` — bounded verify gotchas from earlier green runs, quoted as data in the stable prompt head |
| `deliverables` | — | Repo-relative files the worker must create (absolute or `..` paths are rejected); harness re-prompts before verify when missing or empty |
| `deliverableNudges` | `2` | Max extra worker calls per iteration when `deliverables` are still missing (`0`–`5`) |
| `syncOnSuccess` | `true` | Run repo profile `syncCommand` after success |
Expand All @@ -253,6 +255,7 @@ Legacy `loop.json` field `syncPostgres` maps to `syncOnSuccess`.
| `reasoningEscalationStep` | `1` | Tiers to step per iteration (`1` or `2`) |
| `escalateModelReasoningEffort` | — | Reasoning tier on escalated model |
| `escalateAfterStagnation` | `2` | Identical-failure count before model switch (after reasoning ceiling). Worker timeout / no-tool stall switches immediately and does not wait for this count. |
| `stallProbes` | `false` | When `true`, the first time identical failures hit `escalateAfterStagnation`, the harness runs two differently guided probe workers (procedure hints vs repo facts), keeps the better workspace, then resumes normal escalation — at most once per run. Workspace snapshots are stored as git objects (worktree + index, no stash); restore puts back the branch and HEAD, rewrites only paths that differ, never follows symlinks, keeps file permissions, never deletes a path the snapshot's ignore rules ignore and never deletes under `.cursor/loops/`. **Limits:** ignored files are not snapshotted; restore reverts every change made during the probe round — one loop per worktree, don't edit while probes run. |
| `skills` | — | Explicit `…/SKILL.md` paths (merged with GOAL refs). Default prompt is an **index** (name, description, path) — worker **Read**s the file when needed. |
| `skillDisclosure` | `index` | `index` = progressive disclosure (0.4.0 default; 0.3.0 always inlined). `inline` = paste full SKILL.md bodies. Pin the field on any loop that must keep the old in-prompt runbook. |
| `plugins` | — | Agent Plugins package dirs — discovers `skills/*/SKILL.md` ([`docs/agent-plugins.md`](./docs/agent-plugins.md)) |
Expand Down
185 changes: 185 additions & 0 deletions src/loop/agentLoop.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -278,6 +278,191 @@ describe('runAgentLoop', () => {
expect(runIterationPrompt).toHaveBeenCalledTimes(3)
})

it('runs finalVerify after a green stall probe passes the inner verifier', async () => {
mockSession()
mockedRunVerify
.mockReturnValueOnce(failVerify('FAIL same'))
.mockReturnValueOnce(failVerify('FAIL same'))
.mockReturnValueOnce(passVerify('inner'))
.mockReturnValueOnce(passVerify('final'))

const result = await runAgentLoop({
ctx: makeCtx(),
bundle: makeBundle({
maxIterations: 4,
stagnationThreshold: 5,
escalateAfterStagnation: 2,
stallProbes: true,
finalVerify: 'pnpm test',
}),
workspacePort: { snapshot: async () => ({}), restore: async () => undefined },
})

expect(result.complete).toBe(true)
expect(mockedRunVerify).toHaveBeenCalledWith('pnpm test', process.cwd())
})

it('escalates after a probe round instead of stopping at the default stagnation threshold', async () => {
const { runIterationPrompt } = mockSession()
mockedRunVerify.mockReturnValue(failVerify('FAIL same signature'))

const result = await runAgentLoop({
ctx: makeCtx(),
bundle: makeBundle({
maxIterations: 6,
stagnationThreshold: 3,
escalateAfterStagnation: 2,
stallProbes: true,
}),
workspacePort: { snapshot: async () => ({}), restore: async () => undefined },
})

expect(result.iterations).toBeGreaterThan(3)
expect(runIterationPrompt.mock.calls.length).toBeGreaterThan(3)
})

it('restores the pre-probe snapshot when the procedure probe worker throws', async () => {
const ops: string[] = []
let snaps = 0
const port = {
snapshot: async () => {
snaps += 1
ops.push(`snapshot:${snaps}`)
return { id: snaps }
},
restore: async (snap: { id: number }) => {
ops.push(`restore:${snap.id}`)
},
}
let calls = 0
const runIterationPrompt = vi.fn().mockImplementation(async (prompt: string) => {
calls += 1
ops.push(`worker:${calls}`)
if (prompt.includes('## Stall probe: procedure hints')) {
throw new Error('Cursor agent run failed (status=error)')
}
return { text: 'ok' }
})
mockSession(runIterationPrompt)
mockedRunVerify.mockReturnValue(failVerify('FAIL same'))

const result = await runAgentLoop({
ctx: makeCtx(),
bundle: makeBundle({
maxIterations: 4,
stagnationThreshold: 5,
escalateAfterStagnation: 2,
stallProbes: true,
}),
workspacePort: port,
})

expect(result.complete).toBe(false)
// worker 3 is the procedure probe; s0 is restored right after it throws.
expect(ops.slice(ops.indexOf('worker:3'))).toEqual(
expect.arrayContaining(['worker:3', 'restore:1', 'worker:4']),
)
expect(ops.indexOf('restore:1')).toBeLessThan(ops.indexOf('worker:4'))
// Probes are spent for the run; the next worker is a normal one.
expect(runIterationPrompt.mock.calls[3]?.[0]).not.toContain('## Stall probe')
})

it('parks with both errors when the restore after a probe fault fails', async () => {
const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
const runIterationPrompt = vi.fn().mockImplementation(async (prompt: string) => {
if (prompt.includes('## Stall probe: procedure hints')) {
throw new Error('Cursor agent run failed (status=error)')
}
return { text: 'ok' }
})
mockSession(runIterationPrompt)
mockedRunVerify.mockReturnValue(failVerify('FAIL same'))

const result = await runAgentLoop({
ctx: makeCtx(),
bundle: makeBundle({
maxIterations: 4,
stagnationThreshold: 5,
escalateAfterStagnation: 2,
stallProbes: true,
}),
workspacePort: {
snapshot: async () => ({}),
restore: async () => {
throw new Error('HEAD moved from aaa to bbb (not a descendant)')
},
},
})

expect(result.complete).toBe(false)
expect(result.status).toBe('waiting')
expect(result.completionReason).toContain('stall probe workspace restore failed (after procedure probe fault)')
expect(result.completionReason).toContain('HEAD moved from aaa to bbb')
expect(result.completionReason).toContain('Cursor agent run failed (status=error)')
// No further worker after the failed restore.
expect(runIterationPrompt).toHaveBeenCalledTimes(3)
const domains = fs.readFileSync(path.join(tmpLoopDir, 'failure-domains.ndjson'), 'utf8')
expect(domains).toContain('"reason":"stall_probe_restore_failed"')
errSpy.mockRestore()
})

it('parks when the restore that discards both probes fails', async () => {
const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
const { runIterationPrompt } = mockSession()
mockedRunVerify.mockReturnValue(failVerify('FAIL same'))
let restores = 0
const result = await runAgentLoop({
ctx: makeCtx(),
bundle: makeBundle({
maxIterations: 6,
stagnationThreshold: 5,
escalateAfterStagnation: 2,
stallProbes: true,
}),
workspacePort: {
snapshot: async () => ({}),
restore: async () => {
restores += 1
if (restores === 2) throw new Error('disk full')
},
},
})

expect(result.status).toBe('waiting')
expect(result.completionReason).toContain('stall probe workspace restore failed (no probe kept): disk full')
expect(runIterationPrompt).toHaveBeenCalledTimes(4)
errSpy.mockRestore()
})

it('writes a single iteration line for a green kept probe', async () => {
mockSession()
mockedRunVerify
.mockReturnValueOnce(failVerify('FAIL same'))
.mockReturnValueOnce(failVerify('FAIL same'))
.mockReturnValueOnce(passVerify())

const result = await runAgentLoop({
ctx: makeCtx(),
bundle: makeBundle({
maxIterations: 4,
stagnationThreshold: 5,
escalateAfterStagnation: 2,
stallProbes: true,
}),
workspacePort: { snapshot: async () => ({}), restore: async () => undefined },
})

expect(result.complete).toBe(true)
const lines = fs
.readFileSync(path.join(tmpLoopDir, 'log.ndjson'), 'utf8')
.split('\n')
.filter(Boolean)
.map((l) => JSON.parse(l) as { iteration: number; probe?: { variant: string; kept: boolean } })
const third = lines.filter((l) => l.iteration === 3)
expect(third).toHaveLength(1)
expect(third[0]!.probe).toEqual({ variant: 'procedure', kept: true })
})

it('returns incomplete when max iterations are exhausted', async () => {
mockSession()
mockedRunVerify.mockReturnValue(failVerify('FAIL always'))
Expand Down
Loading
Loading