@loops-adk/core 0.1.1 → 0.3.0

package/README.md

@@ -1,6 +1,18 @@
-# loops
-
-**Stop prompting agents. Write the loop that prompts them. Make "done" mean _converged_, not _claimed_.**
+<p align="center">
+  <img src="assets/logo.png" alt="loops" width="320">
+</p>
+
+<p align="center">
+  <strong>Stop prompting agents. Write the loop that prompts them. Make "done" mean <em>converged</em>, not <em>claimed</em>.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@loops-adk/core"><img src="https://img.shields.io/npm/v/@loops-adk/core" alt="npm"></a>
+  <img src="https://img.shields.io/badge/status-alpha-orange" alt="status: alpha">
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178c6" alt="TypeScript">
+  <img src="https://img.shields.io/badge/node-%3E%3D20-3c873a" alt="node &gt;=20">
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="license: MIT">
+</p>
 
 `loops` is a small, nestable library for running an agent in a convergence loop. The loop finds the work, hands it to an agent, checks the result, records what it learned, and goes again until a gate _you_ define says the work is finished. You write the loop once and it drives the agent, rather than prompting the agent by hand. Compose loops and DAGs both ways, run them against any model behind a one-method `Engine`, and watch a run in a live terminal UI.
 
@@ -8,10 +20,31 @@ Every iteration runs with a **fresh context**, so a long run never rots. Progres
 
 Where most "agent memory" recalls a _conversation_, this keeps your _decisions_ consistent across long work. No vector database, no embeddings, no index to sync or let go stale. **Git is the memory.**
 
-![status: alpha](https://img.shields.io/badge/status-alpha-orange)
-![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)
-![node >=20](https://img.shields.io/badge/node-%3E%3D20-3c873a)
-![license MIT](https://img.shields.io/badge/license-MIT-blue)
+## The fastest proof
+
+A downstream agent had to preserve one upstream decision: snapshots must start
+with the exact wire tag `SSv1|`. That decision lived only in a git commit body,
+not in the source files or the downstream task prompt. The commit was not just a
+fact store; it was the thread back through the journey, what was decided, why it
+was decided, and what downstream work had to honour.
+
+| Runner | What it could read | Result |
+| --- | --- | --- |
+| Memoryless graph | files plus task prompt | 0/10 preserved the contract |
+| Loops Ledger | gated commit bodies plus grounding | 9/10 preserved the contract |
+| Raw git dump | full git log pasted into every prompt | 10/10 on a toy log, not a real-repo operating mode |
+
+That is the honest shape of the claim. Loops is not just `git log`: it is the
+deterministic enforcement layer that makes agents write useful commit bodies when
+work converges, then the grounding layer that reads those verified reasons back
+into later fresh contexts. The value is not bare recall. A fresh agent can pull
+on one thread and reconstruct how and why the repository got here. Full-log dump
+is a useful sanity check on tiny histories, but on a repo with significant
+history it is context rot and cost.
+
+```bash
+npm run bench:compare
+```
 
 ```ts
 import { loop, agentJob, commandSucceeds, agentCheck } from '@loops-adk/core';
@@ -110,7 +143,7 @@ A loop is easy to start and hard to keep honest. Four parts decide whether it ea
 | **The gate.** Knowing the work is actually done, not just that the agent stopped. | A deterministic check (`commandSucceeds`) and a separate judge (`agentCheck`) in its own context, hardened with a k-of-n `quorum` and a geometric-mean rubric so one weak dimension sinks the verdict. The model that did the work never grades it. |
 | **Memory.** Carrying what was learned across a run without dragging a transcript along. | The git commit log is the memory: a structured handoff per milestone, read back before the next turn. No `STATE.md` the model is trusted to keep tidy, no vector store to sync. |
 | **Parallelism.** Running several agents without collisions on the same files. | `isolation: 'worktree'` gives each writer its own branch and worktree, landed back on pass with a `--no-ff` merge. |
-| **Hard stops.** Bounding a loop so it cannot run forever or empty your account. | `max` caps iterations and `budget` caps tokens, a non-retryable stop the engine calls refuse to cross. |
+| **Hard stops.** Bounding a loop so it cannot run forever or empty your account. | `max` caps iterations, `budget` caps tokens (a non-retryable stop the engine calls refuse to cross), and `noProgress` stalls out a loop whose iterations reach no new state, with the evidence on the outcome. |
 
 Three things `loops` does that most loop libraries do not:
 
@@ -151,6 +184,7 @@ loops run \
 ```bash
 loops validate examples/confidence-gate.loop.ts      # offline pre-flight: load + print the shape, no model calls
 loops describe examples/confidence-gate.loop.ts      # print the loop's shape (gate, body, nodes) without running
+loops describe examples/confidence-gate.loop.ts --json # machine-readable shape for agents
 loops run examples/confidence-gate.loop.ts           # live Ink TUI
 loops run examples/confidence-gate.loop.ts --no-tui  # plain streamed logs
 loops run examples/confidence-gate.loop.ts --json    # NDJSON event stream
@@ -160,6 +194,19 @@ loops run examples/confidence-gate.loop.ts --json    # NDJSON event stream
 
 **Authoring is agent-native.** Both commands work from any repo, including one that consumes `loops` as a submodule or dependency (the recipe's folder just needs an ES module scope, which such repos already have). `loops validate <file>` is the cheap, no-model pre-flight an agent runs before `loops run`: it loads the loop, reports a fix-oriented error if anything is wrong, and prints the loop's shape (its gate, body, and dag nodes), all without spending a single agent turn. `loops describe <file>` prints that same shape on its own, so an agent can see exactly what it just authored. The authoring guide an agent reads to compose a loop is [`skills/author-loop/SKILL.md`](skills/author-loop/SKILL.md).
 
+The end-to-end agent workflow, from authoring through reading a supervised run's decisions back as structured records rather than a raw event stream:
+
+```bash
+loops validate feature.loop.ts --json                 # pre-flight: loads, no spend
+loops describe feature.loop.ts --json                 # the shape, incl. each agent node's contract
+loops run feature.loop.ts --no-tui --supervise        # run it, registered for observation
+loops list                                            # find the runId
+loops tail <runId>                                    # follow live events
+loops records <runId> --kind revision --path ship/implementation --json  # the semantic decision stream, filtered
+```
+
+Two supervision skills go deeper: [`skills/supervise-loop-run/SKILL.md`](skills/supervise-loop-run/SKILL.md) (monitor a run) and [`skills/design-agent-team/SKILL.md`](skills/design-agent-team/SKILL.md) (compose a specialist team).
+
 **Offline demo** (no network, no key; uses the mock engine):
 
 ```bash
@@ -194,6 +241,7 @@ loop({
   stopOn, // hard early-exit each iteration; met ⇒ aborted
   review, // runs when until is met; non-pass re-enters the loop (folds back as ctx.lastReview)
   max, // iteration cap; reached without passing ⇒ exhausted
+  noProgress, // stall out after n consecutive iterations with no observable progress
   maxReviewRestarts, // cap the worker/reviewer standoff independently of max
   delayMs, // delay between iterations (polling); interruptible by abort
   retry, // { onError: 'continue' | 'fail', maxConsecutive?, backoffMs? }
@@ -232,6 +280,30 @@ agentCheck({
 
 **Builders:** `predicate`, `bodyPassed`, `minConfidence`, `commandSucceeds` (a shell command exits 0), `all`, `any`, `not`, `quorum` (k-of-n), `agentCheck` (small-model judge), `always`, `never`, and `gateJob` (lift a condition into a `Job`, e.g. a reviewer).
 
+## No progress: the third hard stop
+
+The gate detects success; nothing above detects a loop that is failing to converge. `max` bounds the attempt count and `budget` bounds the cost, but both fire only after the waste, and neither can tell slow-but-real convergence from the same failure five turns running. `noProgress` is that sensor: the loop ends `exhausted` once `n` consecutive iterations reach no state the run has not already seen.
+
+```ts
+loop({
+  name: 'build',
+  body: agentJob({ prompt: '…', ground: true }),
+  until: commandSucceeds('npm', ['test']),
+  max: 50, // generous runway for hard work…
+  noProgress: 3, // …because the doomed case exits after 3 flat iterations
+});
+```
+
+Progress means **novelty**, not change. An iteration counts as progress when any evidence channel reaches something new:
+
+- **the workspace fingerprint** (HEAD, pending diff, untracked content) is a state this run has never visited, so an agent oscillating A→B→A gets no credit for the return trip;
+- **the gate confidence** beats its previous best by `minConfidenceDelta` (default 0.02), a high-water mark, so judge jitter is not progress but slow steady improvement accumulates until it clears the bar;
+- **a custom `signal`** returns a value not already seen, the escape hatch for progress the worktree cannot show (a queue length, a passing-test count): `noProgress: { window: 3, signal: (ctx) => queueDepth() }`.
+
+The default is conservative: one channel showing novelty keeps the loop alive, so real-but-slow work is never cut short. And the exit is a diagnosis, not just a stop: the outcome carries `Outcome.stall` (the flat iterations, the repeated gate reason, the per-channel evidence) and a `loop:stall` event fires for supervisors, so "stalled since iteration 5 on the same scope error" replaces "reached max iterations" and a fleet watcher can re-brief the loop instead of shrugging at it. This is also what makes a generous `max` safe to grant: the safety net and the runway stop being the same number.
+
+Off by default, like `commit`: a polling loop legitimately makes no progress until the outside world changes. Flags mode: `--stall-after <n>`. Offline demo: `npm run example:stall`.
+
 ## Ledger: memory built on git
 
 Fresh context kills _rot_; on its own it would cause _amnesia_. **Ledger** is the core that closes the gap: the loop writes its reasoning to git as it works and reads it back before the next turn. No parallel database, no vector store; git _is_ the index: nothing to build, embed, sync, or let go stale (the commit log can't drift out of sync with the code; it _is_ the code's history). (`Ledger` is the engine; the **commit log** is the durable memory it reads and writes; `.loops/ledger.md` and `.loops/prompt.md` are the live scratch files for work in flight.)
@@ -276,10 +348,10 @@ The agent launch only ever touches the `Engine` interface, so the loop knows not
 
 | name            | backend                          | notes                                                       |
 | --------------- | -------------------------------- | ----------------------------------------------------------- |
-| `claude-cli`    | `claude` subprocess (`execa`)    | fresh process per call; uses host Claude auth, no key       |
-| `agent-sdk`     | `@anthropic-ai/claude-agent-sdk` | fresh `query()` per call; host Claude auth                  |
-| `anthropic-api` | `@anthropic-ai/sdk`              | token-level streaming; cheapest for judges; needs a key     |
-| `codex`         | `codex exec` subprocess (GPT-5)  | a genuinely different model for a second-model reviewer; read-only |
+| `codex`         | `codex exec` subprocess (`execa`) | fresh process per call; read-only unless `bypassPermissions` |
+| `claude-cli`    | `claude` subprocess (`execa`)     | fresh process per call; uses host Claude auth, no key        |
+| `agent-sdk`     | `@anthropic-ai/claude-agent-sdk`  | fresh `query()` per call; host Claude auth                   |
+| `anthropic-api` | `@anthropic-ai/sdk`               | token-level streaming; cheapest for judges; needs a key      |
 | `mock`          | scripted, offline                | for tests and examples                                      |
 
 Select per-run (`--engine`, `RunOptions.engine`) or per-job/condition (`engine:` takes a name **or** a ready-made `Engine`). Bring your own in ~10 lines:
@@ -314,15 +386,23 @@ const storeEngineer = defineAgent({
   system: fromFile(new URL('./agents/store-engineer.md', import.meta.url)), // the persona, as markdown
   model: 'sonnet',
   tools: ['edit', 'bash'],
+  tier: 'worker',
   capabilities: ['storage engine', 'id stability'],
+  outputs: [{ name: 'patch' }, { name: 'test-report' }],
+  requiresSkills: ['contract-first'],
   skills: [tdd],                                  // methodologies fold into the system
+  usesSkills: ['small-diff'],
+  humanGates: [{ name: 'prod-approval', when: 'deploying production changes' }],
   failureModes: [{ mode: 'tests-flaky', recovery: 'isolate the flake, retry once' }],
 });
 
 agentJob({ agent: storeEngineer, prompt: 'Build the store to its tests.', ground: true });
 ```
 
-`agentJob` resolves the def into the engine request (`system` = persona + skills, plus `model`/`tools`); inline `system`/`model`/`tools` still override it. A **skill** is a methodology (how to work: TDD, writing-plans), not a worker. This is what turns a `dag` into a named **team** (`storeEngineer`, `apiEngineer`, `securityReviewer` as small files) orchestrated by the DAG and gated by `quorum(...)`.
+For a small runnable contract plus feedback example, see
+[`examples/contracted-agent.loop.ts`](examples/contracted-agent.loop.ts).
+
+`agentJob` resolves the def into the engine request (`system` = persona + skills, plus `model`/`tools`); inline `system`/`model`/`tools` still override it. A **skill** is a methodology (how to work: TDD, writing-plans), not a worker. The extra contract fields are optional metadata for validation, `loops describe`, docs, and future discovery. They do not give an agent dispatch authority. This is what turns a `dag` into a named **team** (`storeEngineer`, `apiEngineer`, `securityReviewer` as small files) orchestrated by the DAG and gated by `quorum(...)`.
 
 ## Environments: test the running thing
 
@@ -381,6 +461,43 @@ dag({
 
 `needs` = dependencies; a non-`pass` required dependency blocks its dependents; `optional` nodes never block or fail the DAG; an unmet `when` skips a node (counts green); cycles are detected before any work runs. `sequence(name, ...jobs)` and `parallel(name, jobs, concurrency?)` are sugar over `dag`.
 
+### Feedback between nodes
+
+Review feedback is a structured revision request. In a loop, a failing `review`
+outcome is threaded into the next body turn as `ctx.lastReview`; with
+`consumeFeedback: true`, `agentJob` appends it to the implementation prompt in a
+standard block.
+
+```ts
+const implement = agentJob({
+  label: 'implementation',
+  prompt: brief,
+  consumeFeedback: true,
+});
+```
+
+For several reviewers, use `reviewPanel` to aggregate their verdicts into one
+outcome. Every reviewer is a gate: the panel passes when all of them clear (or
+`pass: N` of them, k-of-n), and each failing reviewer's concern is surfaced as a
+blocking finding threaded into the next pass. An empty panel is a construction
+error, not a vacuous pass.
+
+```ts
+const review = reviewPanel({
+  // pass: 2,  // optional: k-of-n instead of all
+  reviewers: [
+    { name: 'security', review: agentCheck({ question: 'Is it safe?', context: reviewContext({ diff: true, ledger: true }) }) },
+    { name: 'correctness', review: agentCheck({ question: 'Is it correct?' }) },
+    { name: 'simplicity', review: agentCheck({ question: 'Is it simple?', context: reviewContext({ files: ['src/**'] }) }) },
+  ],
+});
+```
+
+In a DAG, a targeted `revisionRequest({ target, findings })` reruns the target
+node and its dependents when `maxKickbacks` allows it. `kickback(to, reason)` is
+the terse compatibility helper for the same routed feedback. Agents can opt into
+a small graph-position prompt block with `graphContext: true`.
+
 **Worktree isolation: branches as teams.** A concurrent node can run in its own git worktree on a fork branch (`isolation: 'worktree'` on the DAG, or `isolate: true` per node), so parallel writers never collide on files or the index. On pass, its committed work lands back into the line with a `--no-ff` merge; a conflict fails the node honestly (loops does not auto-resolve; that's a separate layer). Each team gets its own branch, its own scratch files, and (with `DagConfig.environment`) its own stage, all born and torn down together.
 
 For **dynamic** dispatch (a loop that discovers each unit at runtime and routes it to its own isolated sub-loop), `isolated(job)` is the same boundary as a composable wrapper rather than a predeclared node (fork, run, land back on pass):
@@ -458,7 +575,7 @@ loops status <runId>                   # its shape plus where it is now: iterati
 loops tail <runId>                     # stream its events live
 ```
 
-`list` marks a run dead if its process is gone. The read side is also on the public surface (`listRuns`, `readRunStatus`, `runEventsPath`), so an agent supervising a fleet of loops, killing the ones that drift and kicking work back into the ones that hit a problem, reads the same files. Out-of-process control (pause, abort, and kickback from outside) is the next step.
+Each run keeps the raw event stream in `events.jsonl` and a smaller semantic stream in `semantic.jsonl` with dispatch, completion, surfacing, `revision-emitted`, and `revision-routed` records. Use `loops records <runId>` to inspect those records without knowing the registry path; add `--kind revision-routed`, `--kind revision` (both revision kinds), `--path ship/implementation`, `--since <time>`, `--last <n>`, or `--json` when an agent needs a filtered machine-readable stream. `list` marks a run dead if its process is gone. The read side is also on the public surface (`listRuns`, `readRunStatus`, `runEventsPath`, `runSemanticRecordsPath`), so an agent supervising a fleet of loops, killing the ones that drift and kicking work back into the ones that hit a problem, reads the same files. Out-of-process control (pause, abort, and kickback from outside) is the next step.
 
 ## What `loops` is (and isn't)
 
@@ -481,7 +598,7 @@ It deliberately does **not** do durable mid-run replay (re-running a half-finish
 - [x] Supervision: a file-based run registry with `loops list` / `status` / `tail`
 - [ ] Out-of-process control: `pause` / `abort` / `kickback` a running loop from outside
 - [ ] Optional `wip:` autosave tier (per-iteration recovery, squashed on convergence)
-- [ ] No-progress / stall detection: the third hard stop, alongside `max` and `budget`
+- [x] No-progress / stall detection (`noProgress`): the third hard stop, alongside `max` and `budget`
 - [ ] `cost per accepted change` as a first-class reported metric
 - [ ] Calibration helpers for agent judges
 - [ ] More engine adapters (OpenAI, local models)

package/dist/{agent-sdk-RF5VJZAT.js → agent-sdk-4QJDWM7N.js}

@@ -1,5 +1,5 @@
 import { newAccumulator, mapMessage } from './chunk-CXEPZHSR.js';
-import { SUBAGENT_TOOLS } from './chunk-XC46B4FD.js';
+import { SUBAGENT_TOOLS } from './chunk-MA6NDQMO.js';
 import { LoopError } from './chunk-I3STY7U6.js';
 import pTimeout from 'p-timeout';
 
@@ -91,5 +91,5 @@ var AgentSdkEngine = class {
 };
 
 export { AgentSdkEngine };
-//# sourceMappingURL=agent-sdk-RF5VJZAT.js.map
-//# sourceMappingURL=agent-sdk-RF5VJZAT.js.map
+//# sourceMappingURL=agent-sdk-4QJDWM7N.js.map
+//# sourceMappingURL=agent-sdk-4QJDWM7N.js.map

package/dist/{agent-sdk-RF5VJZAT.js.map → agent-sdk-4QJDWM7N.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/engines/agent-sdk.ts"],"names":[],"mappings":"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","file":"agent-sdk-RF5VJZAT.js","sourcesContent":["/**\n * Engine adapter: the Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`).\n * Each `run` is a fresh `query()` — a clean context per loop iteration, which\n * is the whole point. Uses the host's Claude Code auth, so it needs no API key.\n */\n\nimport pTimeout from 'p-timeout';\n\nimport {\n  SUBAGENT_TOOLS,\n  type AgentRequest,\n  type AgentResult,\n  type Engine,\n  type EngineEventSink,\n  type EngineOptions,\n} from './engine.ts';\nimport { mapMessage, newAccumulator } from './message-map.ts';\nimport { LoopError } from '../core/errors.ts';\n\n/**\n * Best-effort classification of an Agent SDK error into a provider-limit\n * `LoopError`, or `undefined` to fall through to the generic ENGINE mapping.\n * The SDK exposes limit state in a few shapes (a thrown error message, an\n * `error` field carrying an `SDKAssistantMessageError` string, and a\n * `rate_limit_info.resetsAt` epoch). We read defensively rather than depend on\n * an exact internal shape:\n *   - a rate-limit / overloaded signal → RATE_LIMIT (resets on its own).\n *   - a billing / usage / credits signal → QUOTA. A `resetsAt` (when present)\n *     makes it auto-waitable; otherwise QUOTA has no reset.\n */\nfunction classifySdkLimit(error: unknown): LoopError | undefined {\n  const err = (error ?? {}) as Record<string, unknown>;\n  const tag = typeof err.error === 'string' ? err.error : '';\n  const message = error instanceof Error ? error.message : String(error);\n  const haystack = `${tag} ${message}`.toLowerCase();\n\n  const info = (err.rate_limit_info ?? {}) as Record<string, unknown>;\n  const resetAt =\n    typeof info.resetsAt === 'number'\n      ? info.resetsAt\n      : typeof info.overageResetsAt === 'number'\n        ? info.overageResetsAt\n        : undefined;\n\n  const isUsage =\n    tag === 'billing_error' ||\n    info.errorCode === 'credits_required' ||\n    /billing|credit|usage limit|quota/.test(haystack);\n  if (isUsage) {\n    return new LoopError({\n      code: 'QUOTA',\n      phase: 'engine',\n      message: `agent-sdk usage/billing limit: ${message}`,\n      cause: error,\n      resetAt,\n    });\n  }\n  const isRate =\n    tag === 'rate_limit' ||\n    tag === 'overloaded' ||\n    /rate limit|rate-limit|too many requests|overloaded/.test(haystack);\n  if (isRate) {\n    return new LoopError({\n      code: 'RATE_LIMIT',\n      phase: 'engine',\n      message: `agent-sdk rate limited: ${message}`,\n      cause: error,\n      resetAt,\n    });\n  }\n  return undefined;\n}\n\nexport class AgentSdkEngine implements Engine {\n  readonly name = 'agent-sdk';\n  constructor(private readonly opts: EngineOptions = {}) {}\n\n  async run(\n    req: AgentRequest,\n    onEvent: EngineEventSink,\n    signal: AbortSignal,\n  ): Promise<AgentResult> {\n    // Lazy import so installs/runs that never touch this engine don't pay for it.\n    const { query } = await import('@anthropic-ai/claude-agent-sdk');\n\n    const acc = newAccumulator(\n      req.model ?? this.opts.defaultModel ?? 'unknown',\n    );\n    const abort = new AbortController();\n    const onAbort = () => abort.abort();\n    if (signal.aborted) abort.abort();\n    else signal.addEventListener('abort', onAbort, { once: true });\n\n    // The SDK option surface drifts across versions; cast at this boundary.\n    const options = {\n      model: req.model ?? this.opts.defaultModel,\n      systemPrompt: req.system,\n      cwd: req.cwd,\n      allowedTools: req.allowedTools,\n      // A leaf agent may not spawn sub-agents — disallow the spawn tool.\n      disallowedTools: req.leaf ? SUBAGENT_TOOLS : undefined,\n      permissionMode: this.opts.permissionMode,\n      includePartialMessages: true,\n      abortController: abort,\n    } as Record<string, unknown>;\n\n    try {\n      const response = query({\n        prompt: req.prompt,\n        options,\n      } as never) as AsyncIterable<unknown>;\n      const consume = (async () => {\n        for await (const message of response) mapMessage(message, acc, onEvent);\n      })();\n      await (req.timeoutMs\n        ? pTimeout(consume, { milliseconds: req.timeoutMs })\n        : consume);\n    } catch (e) {\n      if (signal.aborted)\n        throw new LoopError({\n          code: 'ABORTED',\n          phase: 'engine',\n          message: 'agent-sdk run aborted',\n        });\n      const limit = classifySdkLimit(e);\n      if (limit) throw limit;\n      throw LoopError.from(e, { code: 'ENGINE', phase: 'engine' });\n    } finally {\n      signal.removeEventListener('abort', onAbort);\n    }\n\n    onEvent({ type: 'usage', usage: acc.usage, model: acc.model });\n    return {\n      text: acc.text,\n      usage: acc.usage,\n      model: acc.model,\n      stopReason: acc.stopReason,\n    };\n  }\n}\n"]}
+{"version":3,"sources":["../src/engines/agent-sdk.ts"],"names":[],"mappings":"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","file":"agent-sdk-4QJDWM7N.js","sourcesContent":["/**\n * Engine adapter: the Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`).\n * Each `run` is a fresh `query()` — a clean context per loop iteration, which\n * is the whole point. Uses the host's Claude Code auth, so it needs no API key.\n */\n\nimport pTimeout from 'p-timeout';\n\nimport {\n  SUBAGENT_TOOLS,\n  type AgentRequest,\n  type AgentResult,\n  type Engine,\n  type EngineEventSink,\n  type EngineOptions,\n} from './engine.ts';\nimport { mapMessage, newAccumulator } from './message-map.ts';\nimport { LoopError } from '../core/errors.ts';\n\n/**\n * Best-effort classification of an Agent SDK error into a provider-limit\n * `LoopError`, or `undefined` to fall through to the generic ENGINE mapping.\n * The SDK exposes limit state in a few shapes (a thrown error message, an\n * `error` field carrying an `SDKAssistantMessageError` string, and a\n * `rate_limit_info.resetsAt` epoch). We read defensively rather than depend on\n * an exact internal shape:\n *   - a rate-limit / overloaded signal → RATE_LIMIT (resets on its own).\n *   - a billing / usage / credits signal → QUOTA. A `resetsAt` (when present)\n *     makes it auto-waitable; otherwise QUOTA has no reset.\n */\nfunction classifySdkLimit(error: unknown): LoopError | undefined {\n  const err = (error ?? {}) as Record<string, unknown>;\n  const tag = typeof err.error === 'string' ? err.error : '';\n  const message = error instanceof Error ? error.message : String(error);\n  const haystack = `${tag} ${message}`.toLowerCase();\n\n  const info = (err.rate_limit_info ?? {}) as Record<string, unknown>;\n  const resetAt =\n    typeof info.resetsAt === 'number'\n      ? info.resetsAt\n      : typeof info.overageResetsAt === 'number'\n        ? info.overageResetsAt\n        : undefined;\n\n  const isUsage =\n    tag === 'billing_error' ||\n    info.errorCode === 'credits_required' ||\n    /billing|credit|usage limit|quota/.test(haystack);\n  if (isUsage) {\n    return new LoopError({\n      code: 'QUOTA',\n      phase: 'engine',\n      message: `agent-sdk usage/billing limit: ${message}`,\n      cause: error,\n      resetAt,\n    });\n  }\n  const isRate =\n    tag === 'rate_limit' ||\n    tag === 'overloaded' ||\n    /rate limit|rate-limit|too many requests|overloaded/.test(haystack);\n  if (isRate) {\n    return new LoopError({\n      code: 'RATE_LIMIT',\n      phase: 'engine',\n      message: `agent-sdk rate limited: ${message}`,\n      cause: error,\n      resetAt,\n    });\n  }\n  return undefined;\n}\n\nexport class AgentSdkEngine implements Engine {\n  readonly name = 'agent-sdk';\n  constructor(private readonly opts: EngineOptions = {}) {}\n\n  async run(\n    req: AgentRequest,\n    onEvent: EngineEventSink,\n    signal: AbortSignal,\n  ): Promise<AgentResult> {\n    // Lazy import so installs/runs that never touch this engine don't pay for it.\n    const { query } = await import('@anthropic-ai/claude-agent-sdk');\n\n    const acc = newAccumulator(\n      req.model ?? this.opts.defaultModel ?? 'unknown',\n    );\n    const abort = new AbortController();\n    const onAbort = () => abort.abort();\n    if (signal.aborted) abort.abort();\n    else signal.addEventListener('abort', onAbort, { once: true });\n\n    // The SDK option surface drifts across versions; cast at this boundary.\n    const options = {\n      model: req.model ?? this.opts.defaultModel,\n      systemPrompt: req.system,\n      cwd: req.cwd,\n      allowedTools: req.allowedTools,\n      // A leaf agent may not spawn sub-agents — disallow the spawn tool.\n      disallowedTools: req.leaf ? SUBAGENT_TOOLS : undefined,\n      permissionMode: this.opts.permissionMode,\n      includePartialMessages: true,\n      abortController: abort,\n    } as Record<string, unknown>;\n\n    try {\n      const response = query({\n        prompt: req.prompt,\n        options,\n      } as never) as AsyncIterable<unknown>;\n      const consume = (async () => {\n        for await (const message of response) mapMessage(message, acc, onEvent);\n      })();\n      await (req.timeoutMs\n        ? pTimeout(consume, { milliseconds: req.timeoutMs })\n        : consume);\n    } catch (e) {\n      if (signal.aborted)\n        throw new LoopError({\n          code: 'ABORTED',\n          phase: 'engine',\n          message: 'agent-sdk run aborted',\n        });\n      const limit = classifySdkLimit(e);\n      if (limit) throw limit;\n      throw LoopError.from(e, { code: 'ENGINE', phase: 'engine' });\n    } finally {\n      signal.removeEventListener('abort', onAbort);\n    }\n\n    onEvent({ type: 'usage', usage: acc.usage, model: acc.model });\n    return {\n      text: acc.text,\n      usage: acc.usage,\n      model: acc.model,\n      stopReason: acc.stopReason,\n    };\n  }\n}\n"]}

package/dist/api.d.ts

@@ -1,5 +1,56 @@
-import { L as LoopConfig, J as Job, D as DagConfig, O as Outcome, a as JobContext, C as ConditionInput, b as JobMeta, c as EngineRef, W as Workspace, A as AgentDef, d as Condition, e as EngineOptions, f as Engine, g as EngineName, h as AgentRequest, U as Usage, i as EngineEventSink, j as AgentResult, E as Environment, k as EnvHandle, l as LoopEvent, F as Forge, B as BudgetConfig, m as LimitPolicy } from './types-B4wGVpqo.js';
-export { n as AgentJobConfig, o as Budget, p as CommitJobConfig, q as ConditionResult, r as DagNode, s as EngineStreamEvent, t as ForgeOpts, G as GhForge, u as GroundConfig, v as LogLevel, w as LoopError, x as LoopErrorCode, M as MergeOptions, y as MockForge, z as MockForgeOptions, H as OutcomeStatus, P as PrInput, I as PrPatch, K as PrRef, R as RawPredicate, N as RetryPolicy, S as SUBAGENT_TOOLS, Q as Skill, T as agentJob, V as buildChecksArgs, X as buildCreateArgs, Y as buildEditArgs, Z as buildMergeArgs, _ as buildViewArgs, $ as commitJob, a0 as defineAgent, a1 as defineSkill, a2 as fnJob, a3 as fromFile, a4 as isEngine, a5 as isEnvironment, a6 as isForge, a7 as kickback, a8 as resolveSystem } from './types-B4wGVpqo.js';
+import { C as ConditionInput, J as Job, R as RevisionRerun, F as FeedbackFinding, a as FeedbackDecision, O as Outcome, G as GraphPosition, b as FeedbackSeverity, c as FeedbackActionSeverity, d as JobContext, e as RevisionRequest, L as LoopConfig, D as DagConfig, f as JobMeta, g as EngineRef, W as Workspace, A as AgentDef, h as Condition, i as EngineOptions, j as Engine, k as EngineName, l as AgentRequest, U as Usage, m as EngineEventSink, n as AgentResult, E as Environment, o as EnvHandle, p as LoopEvent, q as Forge, B as BudgetConfig, r as LimitPolicy } from './types-CpB03Jj4.js';
+export { s as AgentContractSummary, t as AgentFailureMode, u as AgentHumanGate, v as AgentJobConfig, w as AgentOutputContract, x as AgentSkillRef, y as AgentTier, z as Budget, H as CommitJobConfig, I as ConditionResult, K as DagNode, M as EngineStreamEvent, N as ForgeOpts, P as GhForge, Q as GroundConfig, S as LogLevel, T as LoopError, V as LoopErrorCode, X as MergeOptions, Y as MockForge, Z as MockForgeOptions, _ as NoProgressConfig, $ as NoProgressInput, a0 as OutcomeStatus, a1 as PrInput, a2 as PrPatch, a3 as PrRef, a4 as ProgressSample, a5 as ProgressTracker, a6 as RawPredicate, a7 as RetryPolicy, a8 as SUBAGENT_TOOLS, a9 as Skill, aa as StallReport, ab as agentContract, ac as agentJob, ad as buildChecksArgs, ae as buildCreateArgs, af as buildEditArgs, ag as buildMergeArgs, ah as buildViewArgs, ai as commitJob, aj as defineAgent, ak as defineSkill, al as fnJob, am as fromFile, an as isEngine, ao as isEnvironment, ap as isForge, aq as resolveNoProgress, ar as resolveSystem } from './types-CpB03Jj4.js';
+
+interface RevisionRequestInput {
+    target?: string;
+    reason?: string;
+    findings?: FeedbackFinding[];
+    rerun?: RevisionRerun;
+    source?: string;
+    decision?: FeedbackDecision;
+}
+declare function normalizeFeedbackSeverity(severity: FeedbackSeverity | undefined): FeedbackActionSeverity;
+declare function isRequiredFeedbackSeverity(severity: FeedbackSeverity | undefined): boolean;
+declare function revisionRequest(input: RevisionRequestInput, over?: Partial<Outcome>): Outcome;
+declare function kickback(to: string, reason: string, over?: Partial<Outcome>): Outcome;
+/**
+ * The single accessor for an outcome's revision request. `Outcome.revision` is
+ * the one channel a producer sets (`revisionRequest`, `kickback`, `reviewPanel`,
+ * dag routing), so there is exactly one place to read it — no parallel `kickback`
+ * field or `data` copy to keep in sync.
+ */
+declare function revisionFromOutcome(outcome: Outcome): RevisionRequest | undefined;
+declare function feedbackBlock(outcome: Outcome): string;
+declare function graphPositionBlock(graph: GraphPosition): string;
+type ReviewTarget = {
+    name?: string;
+    review: ConditionInput;
+} | {
+    name?: string;
+    job: Job;
+};
+interface ReviewPanelConfig {
+    label?: string;
+    reviewers: ReviewTarget[];
+    /** Default `all`: every reviewer must pass. A number means k-of-n over all reviewers. */
+    pass?: 'all' | number;
+    /** When set, a failing panel emits a targeted revision request for dag routing. */
+    target?: string;
+    rerun?: RevisionRerun;
+}
+declare function reviewPanel(config: ReviewPanelConfig): Job;
+interface ReviewContextConfig {
+    diff?: boolean;
+    files?: string[];
+    ledger?: boolean;
+    tests?: boolean | {
+        command: string;
+        args?: string[];
+        cwd?: string;
+    };
+    maxChars?: number;
+}
+declare function reviewContext(config: ReviewContextConfig): (ctx: JobContext, last: Outcome | undefined) => Promise<string>;
 
 /**
  * The loop primitive. `loop(config)` returns a `Job`, so loops nest by simply
@@ -134,6 +185,17 @@ declare function stageAll(opts: GitOpts): Promise<void>;
 declare function hasStagedChanges(opts: GitOpts): Promise<boolean>;
 /** True when the work tree (staged or unstaged) has any change. */
 declare function isDirty(opts: GitOpts): Promise<boolean>;
+/**
+ * A content hash of the workspace's observable state: HEAD, every pending
+ * tracked change (staged + unstaged, with content), the porcelain status, and
+ * the CONTENT of untracked non-ignored files (hashed by git itself, so a
+ * revisit to a byte-identical tree fingerprints identically). This is the
+ * deterministic evidence channel behind `noProgress`: two iterations with the
+ * same fingerprint left the workspace in the same state. Returns undefined
+ * outside a git work tree — the caller treats that channel as absent, never as
+ * "unchanged". Never throws.
+ */
+declare function workspaceFingerprint(opts: GitOpts): Promise<string | undefined>;
 interface CommitInput {
     subject: string;
     /** The structured body — the "way". Joined to the subject with a blank line. */
@@ -1001,9 +1063,63 @@ declare function readRunStatus(runId: string): RunStatus | undefined;
 declare function listRuns(): RunStatus[];
 /** Path to a run's appended event stream (for tailing). */
 declare function runEventsPath(runId: string): string;
+/** Path to a run's semantic record stream. */
+declare function runSemanticRecordsPath(runId: string): string;
 /** A compact one-line rendering of an event, for `loops tail`. */
 declare function formatEvent(event: LoopEvent): string;
 
+type SemanticDecision = FeedbackDecision;
+type SemanticRunRecord = {
+    kind: 'dispatch';
+    ts: number;
+    path: string[];
+    unit: 'job' | 'dag-node';
+    label?: string;
+    node?: string;
+    /** Present for a dag-node: which run this is (1-based; +1 per kickback re-run). */
+    attempt?: number;
+} | {
+    kind: 'completion';
+    ts: number;
+    path: string[];
+    unit: 'job' | 'loop' | 'dag' | 'dag-node';
+    label?: string;
+    outcome: SemanticOutcome;
+    iterations?: number;
+    /** Present for a dag-node: which run this completion is for. */
+    attempt?: number;
+} | {
+    kind: 'surfacing';
+    ts: number;
+    path: string[];
+    source: 'loop-review' | 'dag-kickback';
+    decision: SemanticDecision;
+    severity?: FeedbackActionSeverity;
+    from?: string;
+    to?: string;
+    reason: string;
+    note?: string;
+} | {
+    kind: 'revision-emitted';
+    ts: number;
+    path: string[];
+    sourceEvent: 'job:end';
+    revision: RevisionRequest;
+} | {
+    kind: 'revision-routed';
+    ts: number;
+    path: string[];
+    sourceEvent: 'loop:review' | 'dag:kickback';
+    decision: SemanticDecision;
+    revision: RevisionRequest;
+};
+interface SemanticOutcome {
+    status: Outcome['status'];
+    summary?: string;
+    confidence?: number;
+}
+declare function semanticRecordsFromEvent(event: LoopEvent): SemanticRunRecord[];
+
 /**
  * Public API. A loop-definition file imports from here and `export default`s a
  * `Job` (usually a `loop(...)` or `dag(...)`). The CLI runs that default export.
@@ -1015,4 +1131,4 @@ declare function formatEvent(event: LoopEvent): string;
 /** Identity helper that pins the type of a default export to `Job`. */
 declare function defineJob(job: Job): Job;
 
-export { type AgentCheckConfig, AgentDef, AgentRequest, AgentResult, BudgetConfig, type CommitInput, type CommitRecord, type CompactOptions, Condition, ConditionInput, type ConsolidateJobConfig, type ConsolidateOptions, DagConfig, EXIT_PAUSED, Engine, type EngineFactory, EngineName, EngineOptions, EngineRef, EngineRegistry, EnvHandle, Environment, Forge, type GroundOptions, type IsolatedOptions, Job, JobContext, JobMeta, type LedgerEntry, LimitPolicy, type LogQuery, LoopConfig, LoopEvent, type MergeJobConfig, type MergeResult, type MergeSynthesisConfig, type MergeSynthesisResult, MockEngine, type MockEnvOptions, MockEnvironment, type MockResponder, Outcome, type PromptNote, type PullRequestJobConfig, type PushJobConfig, type PushOptions, type PushResult, type RetrieveOptions, type RunLive, type RunOptions, type RunResult, type RunStatus, Stats, type StatsSnapshot, type TournamentConfig, Usage, Workspace, type WorktreeHandle, addWorktree, agentCheck, all, always, any, appendLedger, appendPrompt, bodyPassed, commandSucceeds, commit, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, dag, defineJob, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, forgeChecks, formatEvent, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isRepo, isolated, jobMeta, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeJob, mergeNoCommit, mergeSynthesis, minConfidence, mockVerdict, never, not, parallel, predicate, promptPath, pullRequestJob, push, pushJob, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, retrieveLedger, run, runEventsPath, runsHome, sequence, stageAll, toCondition, tournament };
+export { type AgentCheckConfig, AgentDef, AgentRequest, AgentResult, BudgetConfig, type CommitInput, type CommitRecord, type CompactOptions, Condition, ConditionInput, type ConsolidateJobConfig, type ConsolidateOptions, DagConfig, EXIT_PAUSED, Engine, type EngineFactory, EngineName, EngineOptions, EngineRef, EngineRegistry, EnvHandle, Environment, FeedbackActionSeverity, FeedbackDecision, FeedbackFinding, FeedbackSeverity, Forge, GraphPosition, type GroundOptions, type IsolatedOptions, Job, JobContext, JobMeta, type LedgerEntry, LimitPolicy, type LogQuery, LoopConfig, LoopEvent, type MergeJobConfig, type MergeResult, type MergeSynthesisConfig, type MergeSynthesisResult, MockEngine, type MockEnvOptions, MockEnvironment, type MockResponder, Outcome, type PromptNote, type PullRequestJobConfig, type PushJobConfig, type PushOptions, type PushResult, type RetrieveOptions, type ReviewContextConfig, type ReviewPanelConfig, RevisionRequest, type RevisionRequestInput, RevisionRerun, type RunLive, type RunOptions, type RunResult, type RunStatus, type SemanticDecision, type SemanticOutcome, type SemanticRunRecord, Stats, type StatsSnapshot, type TournamentConfig, Usage, Workspace, type WorktreeHandle, addWorktree, agentCheck, all, always, any, appendLedger, appendPrompt, bodyPassed, commandSucceeds, commit, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, dag, defineJob, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, feedbackBlock, forgeChecks, formatEvent, gateJob, graphPositionBlock, groundingText, hasStagedChanges, headSha, isDirty, isRepo, isRequiredFeedbackSeverity, isolated, jobMeta, kickback, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeJob, mergeNoCommit, mergeSynthesis, minConfidence, mockVerdict, never, normalizeFeedbackSeverity, not, parallel, predicate, promptPath, pullRequestJob, push, pushJob, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, retrieveLedger, reviewContext, reviewPanel, revisionFromOutcome, revisionRequest, run, runEventsPath, runSemanticRecordsPath, runsHome, semanticRecordsFromEvent, sequence, stageAll, toCondition, tournament, workspaceFingerprint };

package/dist/api.js

@@ -1,7 +1,7 @@
-import { mergeNoCommit, stageAll, commit, mergeAbort, log, setMeta, jobMeta, isRepo, addWorktree, childContext, composeCommitBody, mergeBranch, removeWorktree, deleteBranch, push, consolidate, toCondition, GhForge } from './chunk-6BDWTFOS.js';
-export { Budget, EXIT_PAUSED, EngineRegistry, GhForge, MockForge, Stats, addWorktree, agentCheck, agentJob, all, always, any, appendLedger, appendPrompt, bodyPassed, buildChecksArgs, buildCreateArgs, buildEditArgs, buildMergeArgs, buildViewArgs, commandSucceeds, commit, commitJob, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, defineAgent, defineSkill, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, fnJob, forgeChecks, formatEvent, fromFile, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isForge, isRepo, jobMeta, kickback, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeNoCommit, minConfidence, never, not, predicate, promptPath, push, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, resolveSystem, retrieveLedger, run, runEventsPath, runsHome, stageAll, toCondition } from './chunk-6BDWTFOS.js';
+import { mergeNoCommit, stageAll, commit, mergeAbort, log, setMeta, jobMeta, isRepo, addWorktree, childContext, composeCommitBody, mergeBranch, removeWorktree, deleteBranch, push, consolidate, toCondition, revisionFromOutcome, GhForge } from './chunk-3PMVII43.js';
+export { Budget, EXIT_PAUSED, EngineRegistry, GhForge, MockForge, ProgressTracker, Stats, addWorktree, agentCheck, agentContract, agentJob, all, always, any, appendLedger, appendPrompt, bodyPassed, buildChecksArgs, buildCreateArgs, buildEditArgs, buildMergeArgs, buildViewArgs, commandSucceeds, commit, commitJob, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, defineAgent, defineSkill, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, feedbackBlock, fnJob, forgeChecks, formatEvent, fromFile, gateJob, graphPositionBlock, groundingText, hasStagedChanges, headSha, isDirty, isForge, isRepo, isRequiredFeedbackSeverity, jobMeta, kickback, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeNoCommit, minConfidence, never, normalizeFeedbackSeverity, not, predicate, promptPath, push, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, resolveNoProgress, resolveSystem, retrieveLedger, reviewContext, reviewPanel, revisionFromOutcome, revisionRequest, run, runEventsPath, runSemanticRecordsPath, runsHome, semanticRecordsFromEvent, stageAll, toCondition, workspaceFingerprint } from './chunk-3PMVII43.js';
 import './chunk-JFTXJ7I2.js';
-export { SUBAGENT_TOOLS, isEngine } from './chunk-XC46B4FD.js';
+export { SUBAGENT_TOOLS, isEngine } from './chunk-MA6NDQMO.js';
 import './chunk-Y2SD7GBL.js';
 import { LoopError } from './chunk-I3STY7U6.js';
 export { LoopError } from './chunk-I3STY7U6.js';
@@ -160,6 +160,7 @@ function dag(config) {
     const limit = pLimit(limitN);
     const results = /* @__PURE__ */ new Map();
     const memo = /* @__PURE__ */ new Map();
+    const attempts = /* @__PURE__ */ new Map();
     let stopped = false;
     const pendingKickback = /* @__PURE__ */ new Map();
     const nodeCtx = (name, workspace, environment) => childContext(parent, {
@@ -167,7 +168,14 @@ function dag(config) {
       path: [...path, name],
       workspace,
       environment,
-      lastReview: pendingKickback.get(name)
+      lastReview: pendingKickback.get(name),
+      graph: {
+        dag: config.name,
+        node: name,
+        path: [...path, name],
+        needs: nodes.get(name).needs ?? [],
+        dependents: dependents.get(name) ?? []
+      }
     });
     const mergeLimit = pLimit(1);
     let forkSeq2 = 0;
@@ -264,11 +272,12 @@ function dag(config) {
         path,
         node: name,
         phase,
-        outcome: outcome2
+        outcome: outcome2,
+        attempt: attempts.get(name)
       });
       if (phase === "done" && outcome2.status !== "pass" && nodes.get(name).optional !== true && stopOnError && // A node requesting a kickback is going to be re-run — don't let its
       // (provisional) non-pass abort siblings before the feedback is resolved.
-      !(maxKickbacks > 0 && outcome2.kickback)) {
+      !(maxKickbacks > 0 && revisionFromOutcome(outcome2)?.target)) {
         stopped = true;
       }
       return outcome2;
@@ -278,6 +287,7 @@ function dag(config) {
       if (existing) return existing;
       const node = nodes.get(name);
       const promise = (async () => {
+        attempts.set(name, (attempts.get(name) ?? 0) + 1);
         try {
           const needs = node.needs ?? [];
           const deps = await Promise.all(needs.map(run2));
@@ -324,7 +334,8 @@ function dag(config) {
                 ts: ts(),
                 path,
                 node: name,
-                phase: "start"
+                phase: "start",
+                attempt: attempts.get(name)
               });
               return { outcome: await runNodeJob(name, node), phase: "done" };
             }
@@ -369,10 +380,15 @@ function dag(config) {
       });
       for (; ; ) {
         const from = order.find(
-          (n) => results.get(n)?.kickback && !rejected.has(n)
+          (n) => {
+            const result = results.get(n);
+            return result !== void 0 && revisionFromOutcome(result)?.target !== void 0 && !rejected.has(n);
+          }
         );
         if (!from) break;
-        const { to, reason } = results.get(from).kickback;
+        const request = revisionFromOutcome(results.get(from));
+        const to = request.target;
+        const { reason } = request;
         const allow = nodes.get(from).acceptsKickbackTo;
         const note = !nodes.has(to) ? `unknown node "${to}"` : !ancestorsOf(from).has(to) ? `"${to}" is not an ancestor of "${from}"` : allow && !allow.includes(to) ? `"${from}" does not accept kickback to "${to}"` : void 0;
         if (note) {
@@ -401,7 +417,7 @@ function dag(config) {
         pendingKickback.set(to, {
           status: "fail",
           summary: `Kicked back from "${from}": ${reason}`,
-          data: { kickback: true, from }
+          revision: { ...request, source: request.source ?? from }
         });
         stopped = false;
         await Promise.all(names.map(run2));