P6 plan: asynchronous batch fetch endpoint — phase spec, task plan, given tests

Co-Authored-By: DeepSeek V4 Pro <noreply@deepseek.com>

docs/plans/p6/01-batchstore.md

@@ -0,0 +1,133 @@
+# 01-batchstore — batch tables, lease, GC, byte budget in `internal/dcache`
+
+Add the batch job store to the existing `internal/dcache` SQLite database. No HTTP, no worker —
+this task is storage only. `dcache` owns the single SQLite connection, so the batch tables and
+their accessors live here; the runner (task 02) and API (task 03) call them.
+
+## Context
+
+`dcache.DB` already opens one SQLite connection (`SetMaxOpenConns(1)`, WAL) in `Open`, owns
+`maxBytes`, `evict()`, `Size()`, and `Stats()`. The batch store is a sibling, not a member of the
+content-addressed cache: a batch job is an atomic unit (a row plus its target rows) and must be
+evicted whole by lease, never row-by-row by the content LRU.
+
+## Schema (add to `Open`)
+
+```sql
+CREATE TABLE IF NOT EXISTS batch_job (
+    id            TEXT PRIMARY KEY,
+    caller        TEXT NOT NULL,
+    caller_class  TEXT NOT NULL,          -- 'fleet' | 'restricted'
+    idem_key      TEXT NOT NULL,
+    status        TEXT NOT NULL,          -- queued|running|done|partial|failed|cancelled
+    error         TEXT NOT NULL DEFAULT '',
+    targets_total INTEGER NOT NULL,
+    targets_done  INTEGER NOT NULL DEFAULT 0,
+    created_at    INTEGER NOT NULL,       -- unix seconds
+    lease         INTEGER NOT NULL,       -- unix seconds; bumped on submit/completion/read
+    nbytes        INTEGER NOT NULL DEFAULT 0  -- sum of stored per-target result bytes
+);
+CREATE TABLE IF NOT EXISTS batch_target (
+    job_id  TEXT NOT NULL,
+    idx     INTEGER NOT NULL,             -- order within the job, 0..n-1
+    url     TEXT NOT NULL,
+    options TEXT NOT NULL,                -- JSON: the per-target options
+    status  TEXT NOT NULL,                -- pending|running|done|failed
+    result  TEXT,                         -- JSON result envelope, or NULL
+    error   TEXT,                         -- error message, or NULL
+    hint    TEXT,                         -- error hint, or NULL
+    PRIMARY KEY (job_id, idx)
+);
+CREATE INDEX IF NOT EXISTS batch_job_idem  ON batch_job(caller, idem_key);
+CREATE INDEX IF NOT EXISTS batch_job_lease ON batch_job(lease);
+```
+
+`result`/`error`/`hint` are `NULL` until the target finishes. The `result` JSON is the
+`/v1/fetch`-shaped envelope, bounded by the output cap at write time (task 03 enforces the cap;
+the store just stores what it is given and counts its bytes into `nbytes`).
+
+## Public surface (exact names — the given test compiles against them)
+
+```go
+type BatchJob struct {
+    ID           string
+    Caller       string
+    CallerClass  string
+    IDemKey      string
+    Status       string
+    Error        string
+    TargetsTotal int
+    TargetsDone  int
+    CreatedAt    int64
+    Lease        int64
+    NBytes       int64
+}
+
+type BatchTarget struct {
+    JobID   string
+    Idx     int
+    URL     string
+    Options string
+    Status  string
+    Result  *string
+    Error   *string
+    Hint    *string
+}
+
+func (d *DB) CreateBatchJob(j BatchJob) error
+func (d *DB) BatchJob(id string) (BatchJob, bool)
+func (d *DB) BatchJobByIDem(caller, idemKey string, now int64, ttl time.Duration) (string, bool)
+func (d *DB) LiveBatchJobs(caller string) int
+func (d *DB) LiveBatchJobsTotal() int
+func (d *DB) PutBatchTargets(jobID string, targets []BatchTarget) error
+func (d *DB) BatchTargets(jobID string) ([]BatchTarget, bool)
+func (d *DB) UpdateBatchTarget(jobID string, idx int, now int64, status string, result, errMsg, hint *string) error
+func (d *DB) SetBatchJobStatus(id, status, errMsg string, now int64) error
+func (d *DB) TouchBatchJob(id string, now int64) error
+func (d *DB) SweepBatch(now int64, ttl time.Duration) int
+func (d *DB) EvictBatchOldest(maxBytes int64) int
+func (d *DB) MarkInFlightFailed(reason string, now int64) int
+func (d *DB) BatchNbytes() int64
+```
+
+Every method that touches time takes an explicit `now` (unix seconds) — the store is pure and the
+caller decides the clock, so the given test asserts exact lease values.
+
+## Rules
+
+1. **Sliding lease.** `CreateBatchJob` stores the job as given (the caller sets `Lease`/`CreatedAt`).
+   `UpdateBatchTarget`, `SetBatchJobStatus`, `TouchBatchJob`, and `MarkInFlightFailed` bump the job
+   lease to their `now`. `BatchJob` (a read) also bumps the lease to the current wall-clock time so
+   a slow consumer's reads keep the job alive.
+2. **No partial-job reads leak a competing caller.** Every accessor is keyed by `job_id` only; the
+   caller filter is the API layer's job (task 03). The store stores what it is told and returns
+   what is asked.
+3. `BatchTargets` returns targets in `idx` order. `UpdateBatchTarget` increments `targets_done`
+   exactly once per target that transitions *into* `done`/`failed` (a re-write of the same target
+   does not double-count), bumps the job lease to `now`, and adds `len(result)` to `nbytes` when a
+   result is written.
+4. `SweepBatch(now, ttl)` deletes every job whose `lease + ttl <= now`, and its target rows, and
+   returns the number of jobs deleted. It is the only thing that removes a finished job by time.
+5. `EvictBatchOldest(maxBytes)` evicts **whole jobs** (oldest `lease` first) until `BatchNbytes()`
+   is `<= maxBytes`, and returns the number evicted. A job in `queued`/`running` is never
+   byte-evicted (only lease-GC, cancel, or restart removes an active job). It runs after a target
+   result is written and is separate from the content-cache `evict()`.
+6. `MarkInFlightFailed(reason, now)` marks every `queued`/`running` job `failed` with
+   `error=reason`, bumps their lease to `now`, and returns the count. This is the restart
+   reconciliation hook; `main` calls it on startup (task 03).
+7. `BatchNbytes()` sums `nbytes` over `batch_job`. Batch bytes are **not** included in `Size()` or
+   the content `evict()` union; batch is a coherent unit with its own budget.
+8. Accessors follow the existing `dcache` style: return `(value, bool)` or `error`, never panic,
+   count a miss in the appropriate `*M` counter. Reuse the existing `ClassFleet`/`ClassRestricted`
+   constants for `caller_class`.
+
+## Given
+
+Copy `_files/dcache/batch_test.go` → `internal/dcache/batch_test.go`. It opens an in-memory `DB`
+and asserts the create/read round trip, `BatchJobByIDem` lease expiry + caller scoping, live-job
+counts, ordered targets, the exactly-once `targets_done`/lease-bump rules, `SweepBatch`,
+`EvictBatchOldest` (oldest-first, never a live job), `MarkInFlightFailed`, and `BatchNbytes`.
+
+## Gate
+
+`make gate` green; `go test ./internal/dcache/` green under `-race`.

docs/plans/p6/02-runner.md

@@ -0,0 +1,126 @@
+# 02-runner — serial job runner in `internal/batch`
+
+Add a new package `internal/batch`: the job lifecycle and the serial state machine. It knows how
+to create a job, drain its targets one at a time, write each target's outcome, bump the lease,
+handle cancellation, and enforce the caps and idempotency. It knows **nothing** about HTTP, the
+guard, or the real fetch pipeline: the per-target work is an injected function, and persistence is
+the `*dcache.DB` from task 01.
+
+## Context
+
+`internal/pdfpool` is the wrong shape (in-memory, coalescing, forgets results). The runner is the
+opposite: store-backed, persistent, one job = many distinct targets, results written to the store
+as they complete. It is deliberately serial.
+
+## Public surface (exact names — the given test compiles against them)
+
+```go
+package batch
+
+type Options struct {
+    Mode     string `json:"mode,omitempty"`
+    Question string `json:"question,omitempty"`
+    Pages    string `json:"pages,omitempty"`
+    Grep     string `json:"grep,omitempty"`
+    JQ       string `json:"jq,omitempty"`
+    Context  bool   `json:"context,omitempty"`
+    Recover  bool   `json:"recover,omitempty"`
+}
+
+type Target struct {
+    URL     string  `json:"url"`
+    Options Options `json:"options,omitempty"`
+}
+
+// Result is a completed target's outcome. The runner JSON-encodes it into the
+// store's target.result column and decodes it back in Status.
+type Result struct {
+    Content string         `json:"content"`
+    Meta    map[string]any `json:"meta,omitempty"`
+}
+
+type FetchFunc func(ctx context.Context, t Target) (Result, error)
+
+// Status views returned by Status (mapped from the store rows).
+type Job struct {
+    ID           string
+    Status       string
+    Error        string
+    TargetsTotal int
+    TargetsDone  int
+}
+
+type TargetStatus struct {
+    Idx    int
+    URL    string
+    Status string
+    Result *Result
+    Error  string
+    Hint   string
+}
+
+type Config struct {
+    TTL           time.Duration // 0 → 24h
+    TargetsPerJob int           // 0 → 32
+    JobsPerCaller int           // 0 → 1
+    JobsTotal     int           // 0 → 8
+}
+
+var (
+    ErrTooManyTargets = errors.New("too many targets")
+    ErrCallerBusy     = errors.New("busy")
+    ErrBusy           = errors.New("jobs busy")
+)
+
+func New(db *dcache.DB, fetch FetchFunc, cfg Config, log *slog.Logger) *Runner
+func (r *Runner) Submit(ctx context.Context, caller, callerClass string, targets []Target) (id string, reused bool, err error)
+func (r *Runner) Cancel(id string) bool
+func (r *Runner) Status(id string) (Job, []TargetStatus, bool)
+```
+
+The runner depends on `*dcache.DB` (task 01) for persistence; the `FetchFunc` is the only injected
+behavior. Zero `Config` fields fall back to the defaults above.
+
+## Rules
+
+1. **Idempotency first.** `Submit` derives `idem_key = SHA256(caller + "\x00" + canonical(targets))`
+   where `canonical` is `json.Marshal` of the decoded targets (so field order and whitespace don't
+   matter). If a job whose lease has not expired (`BatchJobByIDem`) exists for the same
+   `(caller, idem_key)` — any status — return it with `reused=true` and do **not** create a new job
+   or enforce the caps. Idempotency is lease-scoped, so it is "reuse within TTL, fresh after".
+2. **Caps second.** targets/job > `TargetsPerJob` → `ErrTooManyTargets`; a live (`queued`/`running`)
+   job already exists for the caller → `ErrCallerBusy`; live jobs total >= `JobsTotal` → `ErrBusy`.
+   "Live" is by status, not lease — read from `LiveBatchJobs`/`LiveBatchJobsTotal`. The typed errors
+   map to `422`/`429` in the API layer.
+3. **Submit transitions to `running` synchronously** (before the drain goroutine starts) so a
+   caller-busy check against a just-submitted job is deterministic. The job is created `queued`
+   then immediately `running`; `queued` is only ever persisted as the crash-window state that
+   `MarkInFlightFailed` reaps.
+4. **Serial drain.** The worker iterates targets in `idx` order, one at a time, and does not start
+   target `i+1` until `i` is written to the store. Each target's `FetchFunc` result or error is
+   written immediately (JSON-encoded); a target failure does not stop the job.
+5. **Lease on completion.** Each target write bumps the job lease (task 01); the first and last
+   target therefore share one expiry.
+6. **Cancellation.** `Cancel` flips the job to `cancelled` and signals the worker; the worker
+   finishes the in-flight target, stores it, and stops before the next. A `cancelled` job's
+   completed targets stay readable until the lease lapses. `Cancel` returns false for an unknown id
+   or a job already in a terminal state.
+7. **Terminal statuses.** When the last target is written: all `done` → `done`; all `failed` →
+   `failed`; a mix → `partial`. Set exactly once.
+8. **No restart concept in the runner.** It is created fresh each process start; `main` (task 03)
+   calls `dcache.MarkInFlightFailed("restart", now)` before constructing the runner. Completed
+   targets on a restart-killed job stay readable; the job is never resumed.
+9. **No panic on input.** Library code never panics: bad ids, missing targets, a `FetchFunc` panic
+   is recovered into a target error and the job continues. The drain runs under
+   `context.WithoutCancel` of a background context; only the per-job cancellation stops it.
+
+## Given
+
+Copy `_files/batch/runner_test.go` → `internal/batch/runner_test.go`. It uses an in-memory `dcache`
+plus a `FetchFunc` that records call order and can fail or panic. Asserts serial order (peak
+in-flight 1), failure isolation (`partial`), idempotent resubmit (`reused`, no double-drain), the
+three caps, cancel (in-flight stored, later targets `pending`), and panic recovery.
+
+## Gate
+
+`make gate` green; `go test ./internal/batch/` green under `-race`.

docs/plans/p6/03-api.md

@@ -0,0 +1,110 @@
+# 03-api — `/v1/batch` endpoints in `internal/api`
+
+Wire the batch runner into the API server. This is the HTTP surface and the only place the guard,
+auth, caps-as-HTTP-statuses, and restricted-caller redaction meet the runner. New code goes in a
+new file `internal/api/batch.go`; do **not** grow `api.go`.
+
+## Endpoints
+
+| Method | Path | Result |
+|---|---|---|
+| `POST /v1/batch` | submit a list of targets | `202` job created/reused, `400` malformed, `422` a target refused up front or over a cap, `429` caller/jobs busy |
+| `GET /v1/batch/{id}` | status + per-target results | `200` (results inline), `401`/`404` |
+| `DELETE /v1/batch/{id}` | cancel | `200` cancelled, `401`/`404` |
+
+Register them in `New` and add `/v1/batch`, `/v1/batch/` to the `ServeHTTP` fast-path switch
+(no `requestDeadline` — submit/poll are quick; the worker is not under any request context).
+
+## Request/response shapes (exact JSON — the given test compares these)
+
+`POST /v1/batch`:
+```json
+{"targets": [{"url": "…", "mode": "clean", "question": "…", "pages": "…", "grep": "…",
+              "jq": "…", "context": true, "recover": false}, …]}
+```
+Each target carries the same fields as `/v1/fetch` minus the outer `url` semantics (each target is
+its own URL). A `targets` list is required and non-empty; otherwise `400`.
+
+Response `202`:
+```json
+{"success": true, "job_id": "…", "status": "queued", "targets": 3, "reused": false}
+```
+
+`GET /v1/batch/{id}`:
+```json
+{"job_id": "…", "status": "done", "targets_total": 3, "targets_done": 3,
+ "created_at": "…", "targets": [
+   {"idx": 0, "url": "…", "status": "done", "result": { …/v1/fetch envelope… }},
+   {"idx": 1, "url": "…", "status": "failed", "error": "blocked: private address …", "hint": "browser"}
+ ]}
+```
+`result` is the `/v1/fetch`-shaped envelope (content, mode, untrusted, source, warnings, sizes,
+timings, and pdf/digest/context when present), written by the runner's `FetchFunc` adapter. A
+`failed` target carries `error` and optional `hint` instead of `result`. Results are inline
+regardless of status, once a target is finished; a pending target has `status: "pending"` and no
+`result`/`error`.
+
+`DELETE /v1/batch/{id}` → `200 {"success": true, "status": "cancelled"}`.
+
+## Refactor of existing code (explicit — this is the one task that edits working code)
+
+`v1fetch` today inlines the whole per-target pipeline: guard → `doFetch` → `recover` →
+render/digest → context → envelope. The batch worker needs the *same* pipeline for one target. Do
+**not** copy-paste that pipeline into the batch adapter — extract it into one shared method that
+both `v1fetch` and the runner's `FetchFunc` call:
+
+```go
+func (s *Server) fetchTarget(ctx context.Context, c *auth.Caller, t batch.Target) (batch.Result, error)
+```
+
+`v1fetch` is refactored to call it, keeping its exact response shape and behavior — the existing
+`v1fetch` tests must pass unchanged. The runner is wired as a new field `s.Batch *batch.Runner`,
+and its `FetchFunc` is a closure over `s.fetchTarget` bound to the authenticated caller. This
+refactor is called out explicitly for reviewer attention: flag any behavioral drift between the
+two callers. The per-target result is capped by the output cap before it is stored.
+
+## Rules
+
+1. **Guard pre-check at submit.** Run `guard.ParseURL` (the no-resolution pre-check) on every
+   target URL before accepting. If any target fails, refuse the **whole** submit with `422` and
+   the offending index + reason (`blocked: …`). This is the "refused up front" gate — the
+   connect-time guard (private IP, rebinding) cannot run until fetch time and surfaces as a
+   per-target `failed`, not a submit refusal.
+2. **Body cap.** The global `MaxBytesReader` caps bodies at `maxReqBody` (64 KiB); `/v1/batch`
+   gets its own larger limit (256 KiB) so 32 targets with questions fit. Apply it in the handler.
+3. **Caps → statuses.** Map the runner's typed errors: `ErrTooManyTargets` → `422`; `ErrCallerBusy`
+   and `ErrBusy` → `429` with a `Retry-After` when sensible. Idempotent reuse returns `202` with
+   `reused: true`.
+4. **Ownership.** `GET`/`DELETE` resolve the job by id, then require `job.caller == c.Name`; else
+   `404` (not `403` — do not reveal that another caller's job exists). The job id is the random
+   opaque token; `idem_key` is never returned or logged.
+5. **Restricted redaction.** Pass the caller (not just its name) into the runner so each target's
+   fetch goes through `doFetch` with the real `*auth.Caller`; the existing `logHost`/`logReason`/
+   `logErr` then blank host, reason, and error detail automatically. The batch handler's own log
+   line logs `caller`, `job_id`, target count, and status — **never** a target URL or hostname, for
+   any caller.
+6. **The adapter.** The runner's `FetchFunc` is the shared `s.fetchTarget` (see the refactor
+   section above), bound to the authenticated `*auth.Caller`. It wraps `doFetch` + `recover` +
+   digest + context + envelope, keyed to one `batch.Target`, returning `batch.Result` (whose `Meta`
+   carries the envelope's source/digest/pdf/context/warnings/sizes/timings). The per-target result
+   is capped by the output cap before it is stored.
+7. **Job status on the wire** uses the runner's vocabulary (`queued|running|done|partial|failed|
+   cancelled`); unknown id → `404`. All three endpoints require a bearer key via the existing
+   `caller` helper (`MetricsOnly` → `403`).
+
+## Given
+
+Copy `_files/api/batch_test.go` → `internal/api/batch_test.go`. It builds a Server with `s.Batch`
+wired over an in-memory `dcache` (pinning the `s.Batch *batch.Runner` field and the
+`s.fetchTarget` adapter), then drives the endpoints. Asserts, at least:
+
+- submit → `202` with a `job_id`; resubmit of the same body → same id, `reused: true`;
+- a target the guard pre-check rejects (non-80/443 port) → `422` and no job created;
+- 33 targets → `422`;
+- a private-address target (passes pre-check, blocked at connect) → per-target `failed` with
+  `error` containing `blocked`, job aggregate `partial`;
+- `GET` by another caller's key → `404`; `DELETE` by the owner → `200`, then `GET` → `cancelled`;
+
+## Gate
+
+`make gate` green; `go test ./internal/api/` green under `-race`.

docs/plans/p6/04-metrics.md

@@ -0,0 +1,73 @@
+# 04-metrics — `sift_batch_*` series in `internal/metrics`
+
+Add the batch series and wire them from the runner and API, so the caps (32 targets, 1 job/caller,
+8 jobs total) and the byte budget can be re-sized from observed data.
+
+## Series (names and label values exact — the given test asserts these)
+
+| Metric | Type | Labels / meaning |
+|---|---|---|
+| `sift_batch_jobs_total` | counter | `outcome` ∈ `created`, `reused`, `done`, `partial`, `failed`, `cancelled`, `restart` |
+| `sift_batch_targets_total` | counter | `outcome` ∈ `ok`, `blocked`, `timeout`, `busy`, `upstream_4xx`, `upstream_5xx`, `unsupported`, `too_long`, `cancel` |
+| `sift_batch_queue_depth` | gauge | live jobs (`queued`+`running`) |
+| `sift_batch_targets_inflight` | gauge | targets currently being fetched |
+| `sift_batch_job_seconds` | histogram | wall time from submit to terminal status |
+| `sift_batch_target_seconds` | histogram | wall time per target |
+| `sift_batch_result_bytes` | histogram | stored bytes per target result |
+
+`outcome` labels on `sift_batch_targets_total` are derived from the fetch error classification the
+same way `coarseReason` does (`blocked` for a guard block, `busy` for `429`, `timeout` for `504`,
+`unsupported` for `415`, `too_long` for the question-too-long `422`, `upstream_4xx`/`upstream_5xx`
+otherwise; `ok` on success; `cancel` when the target was skipped by a cancel).
+
+## Public surface (exact names — the given test compiles against them)
+
+```go
+// fields added to metrics.Set (registered in New)
+BatchJobsTotal       *prometheus.CounterVec // label "outcome"
+BatchTargetsTotal    *prometheus.CounterVec // label "outcome"
+BatchQueueDepth      prometheus.Gauge
+BatchTargetsInflight prometheus.Gauge
+BatchJobSeconds      prometheus.Histogram
+BatchTargetSeconds   prometheus.Histogram
+BatchResultBytes     prometheus.Histogram
+
+// methods (nil-guarded, like ObservePDF)
+func (s *Set) ObserveBatchJob(outcome string)
+func (s *Set) ObserveBatchTarget(outcome string)
+func (s *Set) SetBatchQueueDepth(n int)
+func (s *Set) SetBatchTargetsInflight(n int)
+func (s *Set) ObserveBatchJobSeconds(d time.Duration)
+func (s *Set) ObserveBatchTargetSeconds(d time.Duration)
+func (s *Set) ObserveBatchResultBytes(n int)
+```
+
+Both `outcome` counters fold any value outside their known set to `other` — the same "a raw string
+never becomes a label" guard as `ObservePDF`. Job outcomes: `created, reused, done, partial,
+failed, cancelled, restart`. Target outcomes: `ok, blocked, timeout, busy, upstream_4xx,
+upstream_5xx, unsupported, too_long, cancel`.
+
+## Rules
+
+1. Follow the existing `internal/metrics` pattern: a new `internal/metrics/batch.go` that adds the
+   series to `metrics.Set`, with `Observe…` methods mirroring `ObservePDF`/`ObserveDigest`.
+2. `sift_batch_jobs_total{outcome}` is incremented exactly once per job, at its terminal
+   transition (or `created`/`reused` at submit, `restart` at reconciliation).
+3. `sift_batch_targets_total{outcome}` is incremented exactly once per target.
+4. Gauges reflect the runner's live state: `queue_depth` = live job count; `targets_inflight` = the
+   one in-flight target across jobs (0 or 1 while a job is running, summed over jobs).
+5. Histograms record durations/bytes regardless of outcome; `result_bytes` is the stored target
+   size, which is what sizes the byte budget.
+6. The metrics are exposed through the existing `/metrics` and `/metrics.json` paths — no new
+   endpoint. The API server's `Snapshot`/`writeMetricsJSON` do not need to enumerate them (the
+   Prometheus text handler covers them), but the given test reads the `metrics.Set` values directly.
+
+## Given
+
+Copy `_files/metrics/batch_test.go` → `internal/metrics/batch_test.go`. It drives the `Observe…`
+methods, serves the `/metrics` handler (as `pdf_test.go` does), and asserts the exact series names,
+label values, gauge values, histogram counts, and that a raw outcome string is folded to `other`.
+
+## Gate
+
+`make gate` green; `go test ./internal/metrics/` green under `-race`.

docs/plans/p6/05-cli-docs.md

@@ -0,0 +1,70 @@
+# 05-cli-docs — `sift batch`, skill, README, config
+
+Expose the batch endpoint from the CLI and document it for agents. No Hermes plugin — the CLI is
+the agent surface, same rationale as `sift fetch`/`sift search`.
+
+## CLI
+
+Add a `sift batch` subcommand with three verbs. It reads `url` and `key_file` from `client.toml`
+exactly as `fetch`/`search` do, and never puts a key on the command line.
+
+```
+sift batch submit <targets.json>      # '-' reads stdin; prints the job_id (and reused) as JSON
+sift batch status <job_id>            # prints status + per-target results as JSON
+sift batch cancel <job_id>            # prints the cancelled status as JSON
+```
+
+`submit` takes the same JSON as `POST /v1/batch` (a `{"targets":[…]}` object) and prints
+`{"job_id": …, "reused": …}`. `status` prints the full `GET /v1/batch/{id}` body. All three
+propagate the server's error envelope and exit non-zero on a non-2xx.
+
+The dispatch/validation is a pure function pinned by the given test:
+
+```go
+func parseBatchArgs(args []string) (verb, arg string, err error)
+```
+
+`verb` is `submit`/`status`/`cancel`; `arg` is the targets file (submit, `-` for stdin) or the
+`job_id` (status/cancel). No verb, a missing arg, an extra arg, or an unknown verb is an error.
+
+## Config
+
+Add a `[batch]` block to `internal/config` (`File`), with:
+
+```toml
+[batch]
+targets_per_job = 32
+jobs_per_caller = 1
+jobs_total      = 8
+ttl             = "24h"
+max_bytes       = "64MiB"
+```
+
+The runner and API read these instead of hard-coding; the defaults match the settled caps. The
+body-cap knob for `/v1/batch` (256 KiB) is a constant, not config.
+
+## Docs
+
+- `README.md`: add a short "Batch" section (the three endpoints, the serial/background model, caps,
+  idempotency, lease/TTL semantics, restricted-caller redaction, and the `sift_batch_*` metrics).
+- `skill/SKILL.md`: add a batch section telling agents to use `sift batch submit` for a list of
+  targets rather than a loop of `sift fetch`, and to `sift batch status` to collect.
+- `dist/sift.toml.example`: add the `[batch]` block with its defaults and a comment.
+
+## Rules
+
+1. The CLI reuses the existing client plumbing (`client.toml`, bearer header, JSON envelope
+   handling) — no new HTTP client.
+2. `submit` validates its input locally (a non-empty `targets` array) before calling the server.
+3. `status`/`cancel` require exactly one `job_id` argument.
+4. Keep each verb a small function; do not grow `main.go` — add `cmd/sift/batchcmd.go`.
+
+## Given
+
+Copy `_files/cmd_sift/batch_test.go` → `cmd/sift/batch_test.go`. It pins `parseBatchArgs` — the
+valid verb+arg pairs (including `-` as a stdin target file) and the error cases (no verb, missing
+arg, extra arg, unknown verb).
+
+## Gate
+
+`make gate` green; `go test ./cmd/sift/` green under `-race`; `go test ./internal/config/` green.

docs/plans/p6/README.md

@@ -0,0 +1,46 @@
+# P6 implementation plan: asynchronous batch fetch
+
+> **For the implementing model:** do not work from this file. The owner gives you one task file
+> at a time. This file is the index for the owner and the reviewer.
+
+**Goal:** an agent that has collected a series of targets (URLs) and wants them fetched without
+holding a request open per target submits them as one batch, gets a job ID back immediately, and
+polls for per-target results later. A batch is **deliberate and slow** — serial, one target at a
+time — so it is the tool for research threads, not for interactive fetches.
+
+Decisions (settled with the owner, 2026-09-26):
+
+- **Serial.** One target drains at a time per job, in the background. Each target still goes
+  through the normal `acquire` gate (8 global / 2 per-host); on `429 busy` the worker waits and
+  retries rather than failing, because nobody is holding a socket open. Interactive requests win
+  by construction: they are served by HTTP handlers that grab slots immediately.
+- **Caps.** targets/job 32; live jobs/caller 1; live jobs total 8; per-target result bounded by
+  the output cap. All instrumented (`sift_batch_*`) so the numbers can be re-sized empirically.
+- **Idempotency in v1.** A job has a random opaque `id` plus a derived `idem_key`; resubmitting
+  the same (caller, targets) while the job is live returns the existing job instead of a new one.
+- **Storage.** `batch_job` + `batch_target` tables in the existing `dcache` SQLite.
+- **Retention / TTL.** A job carries a single sliding **lease**, bumped on submit, on every target
+  completion, and on every status/collect read. All targets therefore share one expiry, and a slow
+  consumer's reads keep a finished batch alive. GC deletes a job (and its targets) once its lease
+  is older than the TTL. Batch storage is a coherent whole: it is bounded by the lease GC plus a
+  separate byte budget (oldest-lease jobs evicted whole), not by the content cache's LRU.
+- **Restart.** Completed results survive restart and stay readable until the lease lapses.
+  `queued`/`running` jobs are marked `failed` (reason `restart`) on startup; never resumed.
+- **Restricted callers.** Compartmentalized-access systems: their usage is redacted as much as
+  possible (host, error reason, error detail — the existing `logHost`/`logReason`/`logErr`
+  machinery), and no other caller may read their jobs or results. The worker passes the caller
+  through, so this happens automatically; batch log lines never carry a target URL or hostname.
+
+| Task | Package | Given |
+|---|---|---|
+| 01-batchstore | `internal/dcache` | `dcache/batch_test.go` |
+| 02-runner | `internal/batch` | `batch/runner_test.go` |
+| 03-api | `internal/api` | `api/batch_test.go` |
+| 04-metrics | `internal/metrics` | `metrics/batch_test.go` |
+| 05-cli-docs | `cmd/sift`, `README.md`, `skill/SKILL.md`, config | `cmd/sift/batch_test.go` |
+
+**How this plan was made:** design worked through with the owner from `docs/PLAN.md` §13 (future
+work) on top of the P5 pool (`internal/pdfpool`), cache (`internal/dcache`), and gate
+(`global`/`per` in `internal/api`) infrastructure. Acceptance tests first: the given tests are
+authored against this spec and compiled against a panic-only skeleton so they fail for the
+intended reasons before each task is implemented.

docs/plans/p6/_files/api/batch_test.go

@@ -0,0 +1,254 @@
+package api
+
+import (
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/sift/internal/auth"
+	"git.wntrmute.dev/kyle/sift/internal/batch"
+	"git.wntrmute.dev/kyle/sift/internal/dcache"
+	"git.wntrmute.dev/kyle/sift/internal/fetch"
+	"git.wntrmute.dev/kyle/sift/internal/guard"
+)
+
+// newBatchServer builds a Server with the batch runner wired over an in-memory
+// dcache, exactly as serve does in production. callers are the caller names to
+// provision (each with a bearer key).
+func newBatchServer(t *testing.T, g *guard.Guard, callers ...string) (*Server, map[string]string) {
+	t.Helper()
+	dir := t.TempDir()
+	keysPath := filepath.Join(dir, "keys.toml")
+	keys := map[string]string{}
+	for _, name := range callers {
+		out := filepath.Join(dir, name)
+		if err := auth.Add(keysPath, name, "hermes-fleet", out); err != nil {
+			t.Fatal(err)
+		}
+		b, err := os.ReadFile(out)
+		if err != nil {
+			t.Fatal(err)
+		}
+		keys[name] = strings.TrimSpace(string(b))
+	}
+	store, err := auth.Load(keysPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if g == nil {
+		g = &guard.Guard{}
+	}
+	f := &fetch.Fetcher{Guard: g, UA: "sift-test"}
+	s := New("test", g, f, store, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	db, err := dcache.Open("", 1<<20, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	s.Batch = batch.New(db, s.fetchTarget, batch.Config{}, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	return s, keys
+}
+
+func submitBatch(t *testing.T, s *Server, key string, targets []map[string]string) *httptest.ResponseRecorder {
+	t.Helper()
+	return postJSON(t, s, "/v1/batch", key, map[string]any{"targets": targets})
+}
+
+func getBatch(t *testing.T, s *Server, key, id string) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, "/v1/batch/"+id, nil)
+	req.Header.Set("Authorization", "Bearer "+key)
+	rec := httptest.NewRecorder()
+	s.ServeHTTP(rec, req)
+	return rec
+}
+
+func batchStatus(t *testing.T, s *Server, key, id string) map[string]any {
+	t.Helper()
+	rec := getBatch(t, s, key, id)
+	var env map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &env); err != nil {
+		t.Fatalf("status decode: %v (%s)", err, rec.Body.String())
+	}
+	return env
+}
+
+// waitBatchTerminal polls until the job reaches a terminal status.
+func waitBatchTerminal(t *testing.T, s *Server, key, id string) map[string]any {
+	t.Helper()
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		env := batchStatus(t, s, key, id)
+		if st, _ := env["status"].(string); st == "done" || st == "partial" || st == "failed" || st == "cancelled" {
+			return env
+		}
+		time.Sleep(time.Millisecond)
+	}
+	t.Fatal("batch never reached a terminal status")
+	return nil
+}
+
+func TestBatchSubmitAndCollect(t *testing.T) {
+	g := &guard.Guard{AllowPrefixes: []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")}}
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, _ = w.Write([]byte(`<html><head><title>T</title></head><body><article><p>hello batch</p></article></body></html>`))
+	}))
+	defer ts.Close()
+	s, keys := newBatchServer(t, g, "test")
+	rec := submitBatch(t, s, keys["test"], []map[string]string{{"url": ts.URL}, {"url": ts.URL + "/2"}})
+	if rec.Code != 202 {
+		t.Fatalf("submit %d %s", rec.Code, rec.Body.String())
+	}
+	var sub map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &sub); err != nil {
+		t.Fatal(err)
+	}
+	if sub["success"] != true {
+		t.Fatalf("success %v", sub["success"])
+	}
+	id, _ := sub["job_id"].(string)
+	if id == "" {
+		t.Fatal("missing job_id")
+	}
+	if reused, _ := sub["reused"].(bool); reused {
+		t.Fatal("first submit must not be reused")
+	}
+	env := waitBatchTerminal(t, s, keys["test"], id)
+	if env["status"] != "done" {
+		t.Fatalf("status %v", env["status"])
+	}
+	targets, _ := env["targets"].([]any)
+	if len(targets) != 2 {
+		t.Fatalf("targets %d", len(targets))
+	}
+	first := targets[0].(map[string]any)
+	if first["status"] != "done" {
+		t.Fatalf("target0 %v", first["status"])
+	}
+	res, _ := first["result"].(map[string]any)
+	if res == nil || !strings.Contains(res["content"].(string), "hello batch") {
+		t.Fatalf("target0 result %v", res)
+	}
+}
+
+func TestBatchIdempotentResubmit(t *testing.T) {
+	g := &guard.Guard{AllowPrefixes: []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")}}
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/plain")
+		_, _ = w.Write([]byte("ok"))
+	}))
+	defer ts.Close()
+	s, keys := newBatchServer(t, g, "test")
+	targets := []map[string]string{{"url": ts.URL}}
+	first := submitBatch(t, s, keys["test"], targets)
+	second := submitBatch(t, s, keys["test"], targets)
+	var a, b map[string]any
+	_ = json.Unmarshal(first.Body.Bytes(), &a)
+	_ = json.Unmarshal(second.Body.Bytes(), &b)
+	if a["job_id"] != b["job_id"] {
+		t.Fatalf("ids differ: %v vs %v", a["job_id"], b["job_id"])
+	}
+	if reused, _ := b["reused"].(bool); !reused {
+		t.Fatal("resubmit must be reused=true")
+	}
+}
+
+func TestBatchGuardRefusedUpFront(t *testing.T) {
+	s, keys := newBatchServer(t, nil, "test")
+	rec := submitBatch(t, s, keys["test"], []map[string]string{{"url": "http://example.com:8080/"}})
+	if rec.Code != 422 {
+		t.Fatalf("want 422, got %d %s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "blocked") {
+		t.Fatalf("body %s", rec.Body.String())
+	}
+}
+
+func TestBatchTooManyTargets(t *testing.T) {
+	s, keys := newBatchServer(t, nil, "test")
+	var targets []map[string]string
+	for i := 0; i < 33; i++ {
+		targets = append(targets, map[string]string{"url": "https://example.com/"})
+	}
+	rec := submitBatch(t, s, keys["test"], targets)
+	if rec.Code != 422 {
+		t.Fatalf("want 422, got %d %s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestBatchPartialFailure(t *testing.T) {
+	g := &guard.Guard{AllowPrefixes: []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")}}
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/plain")
+		_, _ = w.Write([]byte("ok"))
+	}))
+	defer ts.Close()
+	s, keys := newBatchServer(t, g, "test")
+	// target 1 is a private address: passes the submit pre-check (valid URL) but
+	// is blocked by the connect-time guard, surfacing as a per-target failure.
+	rec := submitBatch(t, s, keys["test"], []map[string]string{{"url": ts.URL}, {"url": "http://10.0.0.5/"}})
+	if rec.Code != 202 {
+		t.Fatalf("submit %d %s", rec.Code, rec.Body.String())
+	}
+	var sub map[string]any
+	_ = json.Unmarshal(rec.Body.Bytes(), &sub)
+	id := sub["job_id"].(string)
+	env := waitBatchTerminal(t, s, keys["test"], id)
+	if env["status"] != "partial" {
+		t.Fatalf("status %v", env["status"])
+	}
+	targets := env["targets"].([]any)
+	second := targets[1].(map[string]any)
+	if second["status"] != "failed" {
+		t.Fatalf("target1 status %v", second["status"])
+	}
+	if err, _ := second["error"].(string); !strings.Contains(err, "blocked") {
+		t.Fatalf("target1 error %q", err)
+	}
+}
+
+func TestBatchOwnership404(t *testing.T) {
+	s, keys := newBatchServer(t, nil, "test", "other")
+	rec := submitBatch(t, s, keys["test"], []map[string]string{{"url": "https://example.com/"}})
+	if rec.Code != 202 {
+		t.Fatalf("submit %d", rec.Code)
+	}
+	var sub map[string]any
+	_ = json.Unmarshal(rec.Body.Bytes(), &sub)
+	id := sub["job_id"].(string)
+	if got := getBatch(t, s, keys["other"], id); got.Code != 404 {
+		t.Fatalf("other caller GET: %d (must not reveal the job)", got.Code)
+	}
+	if got := getBatch(t, s, keys["test"], id); got.Code != 200 {
+		t.Fatalf("owner GET: %d", got.Code)
+	}
+}
+
+func TestBatchCancel(t *testing.T) {
+	g := &guard.Guard{AllowPrefixes: []netip.Prefix{netip.MustParsePrefix("127.0.0.0/8")}}
+	s, keys := newBatchServer(t, g, "test")
+	rec := submitBatch(t, s, keys["test"], []map[string]string{{"url": "https://example.com/"}})
+	var sub map[string]any
+	_ = json.Unmarshal(rec.Body.Bytes(), &sub)
+	id := sub["job_id"].(string)
+	req := httptest.NewRequest(http.MethodDelete, "/v1/batch/"+id, nil)
+	req.Header.Set("Authorization", "Bearer "+keys["test"])
+	drec := httptest.NewRecorder()
+	s.ServeHTTP(drec, req)
+	if drec.Code != 200 {
+		t.Fatalf("cancel %d %s", drec.Code, drec.Body.String())
+	}
+	env := waitBatchTerminal(t, s, keys["test"], id)
+	if env["status"] != "cancelled" {
+		t.Fatalf("status %v", env["status"])
+	}
+}

docs/plans/p6/_files/batch/runner_test.go

@@ -0,0 +1,234 @@
+package batch
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"sync"
+	"testing"
+	"time"
+
+	"git.wntrmute.dev/kyle/sift/internal/dcache"
+)
+
+func newRunner(t *testing.T, fetch FetchFunc, cfg Config) *Runner {
+	t.Helper()
+	db, err := dcache.Open("", 1<<20, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	return New(db, fetch, cfg, slog.New(slog.NewTextHandler(io.Discard, nil)))
+}
+
+func waitStatus(t *testing.T, r *Runner, id, want string) {
+	t.Helper()
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		j, _, ok := r.Status(id)
+		if ok && j.Status == want {
+			return
+		}
+		time.Sleep(time.Millisecond)
+	}
+	j, _, _ := r.Status(id)
+	t.Fatalf("job %s never reached %q (now %q)", id, want, j.Status)
+}
+
+func TestSerialOrder(t *testing.T) {
+	var mu sync.Mutex
+	var calls []string
+	inflight, peak := 0, 0
+	fetch := func(_ context.Context, tgt Target) (Result, error) {
+		mu.Lock()
+		inflight++
+		if inflight > peak {
+			peak = inflight
+		}
+		calls = append(calls, tgt.URL)
+		mu.Unlock()
+		time.Sleep(time.Millisecond)
+		mu.Lock()
+		inflight--
+		mu.Unlock()
+		return Result{Content: "ok " + tgt.URL}, nil
+	}
+	r := newRunner(t, fetch, Config{})
+	id, reused, err := r.Submit(context.Background(), "alice", "fleet", []Target{
+		{URL: "https://a.example/"}, {URL: "https://b.example/"}, {URL: "https://c.example/"},
+	})
+	if err != nil || reused {
+		t.Fatalf("submit err=%v reused=%v", err, reused)
+	}
+	waitStatus(t, r, id, "done")
+	mu.Lock()
+	order := append([]string(nil), calls...)
+	p := peak
+	mu.Unlock()
+	if len(order) != 3 || order[0] != "https://a.example/" || order[1] != "https://b.example/" || order[2] != "https://c.example/" {
+		t.Fatalf("order %v", order)
+	}
+	if p != 1 {
+		t.Fatalf("peak inflight %d, want 1 (serial)", p)
+	}
+}
+
+func TestFailureIsolation(t *testing.T) {
+	fetch := func(_ context.Context, tgt Target) (Result, error) {
+		if tgt.URL == "https://b.example/" {
+			return Result{}, errors.New("upstream 500")
+		}
+		return Result{Content: "ok " + tgt.URL}, nil
+	}
+	r := newRunner(t, fetch, Config{})
+	id, _, err := r.Submit(context.Background(), "alice", "fleet", []Target{
+		{URL: "https://a.example/"}, {URL: "https://b.example/"}, {URL: "https://c.example/"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitStatus(t, r, id, "partial")
+	j, ts, ok := r.Status(id)
+	if !ok {
+		t.Fatal("no job")
+	}
+	if j.Status != "partial" || j.TargetsDone != 3 {
+		t.Fatalf("job %+v", j)
+	}
+	if ts[0].Status != "done" || ts[1].Status != "failed" || ts[2].Status != "done" {
+		t.Fatalf("statuses %+v", ts)
+	}
+	if ts[1].Error == "" {
+		t.Fatal("failed target missing error")
+	}
+	if ts[0].Result == nil || ts[0].Result.Content != "ok https://a.example/" {
+		t.Fatalf("result %+v", ts[0].Result)
+	}
+}
+
+func TestIdempotentResubmit(t *testing.T) {
+	var mu sync.Mutex
+	n := 0
+	fetch := func(_ context.Context, tgt Target) (Result, error) {
+		mu.Lock()
+		n++
+		mu.Unlock()
+		return Result{Content: "ok"}, nil
+	}
+	r := newRunner(t, fetch, Config{})
+	targets := []Target{{URL: "https://a.example/"}, {URL: "https://b.example/"}}
+	id1, reused1, err := r.Submit(context.Background(), "alice", "fleet", targets)
+	if err != nil || reused1 {
+		t.Fatalf("first submit err=%v reused=%v", err, reused1)
+	}
+	id2, reused2, err := r.Submit(context.Background(), "alice", "fleet", targets)
+	if err != nil || !reused2 || id2 != id1 {
+		t.Fatalf("resubmit id=%q reused=%v err=%v", id2, reused2, err)
+	}
+	waitStatus(t, r, id1, "done")
+	mu.Lock()
+	calls := n
+	mu.Unlock()
+	if calls != 2 {
+		t.Fatalf("fetched %d times, want 2 (idempotent)", calls)
+	}
+}
+
+func TestTooManyTargets(t *testing.T) {
+	fetch := func(_ context.Context, tgt Target) (Result, error) { return Result{Content: "ok"}, nil }
+	r := newRunner(t, fetch, Config{TargetsPerJob: 2})
+	three := []Target{{URL: "https://a.example/"}, {URL: "https://b.example/"}, {URL: "https://c.example/"}}
+	if _, _, err := r.Submit(context.Background(), "alice", "fleet", three); !errors.Is(err, ErrTooManyTargets) {
+		t.Fatalf("want ErrTooManyTargets, got %v", err)
+	}
+}
+
+func TestCallerBusy(t *testing.T) {
+	release := make(chan struct{})
+	fetch := func(_ context.Context, tgt Target) (Result, error) {
+		<-release // hold the job in the running state
+		return Result{Content: "ok"}, nil
+	}
+	r := newRunner(t, fetch, Config{})
+	id, _, err := r.Submit(context.Background(), "alice", "fleet", []Target{{URL: "https://a.example/"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitStatus(t, r, id, "running")
+	if _, _, err := r.Submit(context.Background(), "alice", "fleet", []Target{{URL: "https://b.example/"}}); !errors.Is(err, ErrCallerBusy) {
+		t.Fatalf("want ErrCallerBusy, got %v", err)
+	}
+	close(release)
+}
+
+func TestCancel(t *testing.T) {
+	started := make(chan struct{}, 1)
+	release := make(chan struct{})
+	var mu sync.Mutex
+	var calls []string
+	fetch := func(_ context.Context, tgt Target) (Result, error) {
+		mu.Lock()
+		calls = append(calls, tgt.URL)
+		mu.Unlock()
+		select {
+		case started <- struct{}{}:
+		default:
+		}
+		<-release
+		return Result{Content: "ok"}, nil
+	}
+	r := newRunner(t, fetch, Config{})
+	id, _, err := r.Submit(context.Background(), "alice", "fleet", []Target{
+		{URL: "https://a.example/"}, {URL: "https://b.example/"}, {URL: "https://c.example/"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	<-started // first target is in flight
+	if !r.Cancel(id) {
+		t.Fatal("cancel returned false")
+	}
+	close(release) // let the in-flight target finish
+	waitStatus(t, r, id, "cancelled")
+	mu.Lock()
+	n := len(calls)
+	mu.Unlock()
+	if n != 1 {
+		t.Fatalf("cancelled after %d fetches, want 1", n)
+	}
+	_, ts, ok := r.Status(id)
+	if !ok {
+		t.Fatal("no job")
+	}
+	if ts[0].Status != "done" {
+		t.Fatalf("in-flight target should be stored done: %+v", ts[0])
+	}
+	if ts[1].Status != "pending" || ts[2].Status != "pending" {
+		t.Fatalf("later targets must stay pending: %+v", ts[1:])
+	}
+}
+
+func TestPanicRecovered(t *testing.T) {
+	fetch := func(_ context.Context, tgt Target) (Result, error) {
+		if tgt.URL == "https://b.example/" {
+			panic("boom")
+		}
+		return Result{Content: "ok"}, nil
+	}
+	r := newRunner(t, fetch, Config{})
+	id, _, err := r.Submit(context.Background(), "alice", "fleet", []Target{
+		{URL: "https://a.example/"}, {URL: "https://b.example/"}, {URL: "https://c.example/"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitStatus(t, r, id, "partial")
+	_, ts, _ := r.Status(id)
+	if ts[0].Status != "done" || ts[1].Status != "failed" || ts[2].Status != "done" {
+		t.Fatalf("statuses %+v", ts)
+	}
+	if ts[1].Error == "" {
+		t.Fatal("panic target missing error")
+	}
+}

docs/plans/p6/_files/cmd_sift/batch_test.go

@@ -0,0 +1,34 @@
+package main
+
+import "testing"
+
+func TestParseBatchArgs(t *testing.T) {
+	cases := []struct {
+		args []string
+		verb string
+		arg  string
+		ok   bool
+	}{
+		{[]string{"submit", "targets.json"}, "submit", "targets.json", true},
+		{[]string{"submit", "-"}, "submit", "-", true},
+		{[]string{"status", "job-123"}, "status", "job-123", true},
+		{[]string{"cancel", "job-123"}, "cancel", "job-123", true},
+		{[]string{}, "", "", false},
+		{[]string{"status"}, "", "", false},
+		{[]string{"status", "a", "b"}, "", "", false},
+		{[]string{"bogus", "x"}, "", "", false},
+	}
+	for _, c := range cases {
+		verb, arg, err := parseBatchArgs(c.args)
+		if c.ok {
+			if err != nil {
+				t.Fatalf("%v: unexpected error %v", c.args, err)
+			}
+			if verb != c.verb || arg != c.arg {
+				t.Fatalf("%v: got verb=%q arg=%q", c.args, verb, arg)
+			}
+		} else if err == nil {
+			t.Fatalf("%v: want error", c.args)
+		}
+	}
+}

docs/plans/p6/_files/dcache/batch_test.go

@@ -0,0 +1,240 @@
+package dcache
+
+import (
+	"io"
+	"log/slog"
+	"strings"
+	"testing"
+	"time"
+)
+
+func newBatchDB(t *testing.T) *DB {
+	t.Helper()
+	db, err := Open("", 1<<20, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	return db
+}
+
+func strp(s string) *string { return &s }
+
+func TestBatchJobRoundTrip(t *testing.T) {
+	db := newBatchDB(t)
+	j := BatchJob{
+		ID: "j1", Caller: "alice", CallerClass: ClassFleet, IDemKey: "k1",
+		Status: "queued", TargetsTotal: 3, CreatedAt: 100, Lease: 100,
+	}
+	if err := db.CreateBatchJob(j); err != nil {
+		t.Fatal(err)
+	}
+	got, ok := db.BatchJob("j1")
+	if !ok {
+		t.Fatal("missing job")
+	}
+	if got.ID != j.ID || got.Caller != "alice" || got.CallerClass != ClassFleet ||
+		got.Status != "queued" || got.TargetsTotal != 3 || got.Lease != 100 || got.CreatedAt != 100 {
+		t.Fatalf("round trip mismatch: %+v", got)
+	}
+	if _, ok := db.BatchJob("nope"); ok {
+		t.Fatal("unknown id must be ok=false")
+	}
+}
+
+func TestBatchIDemLookup(t *testing.T) {
+	db := newBatchDB(t)
+	if err := db.CreateBatchJob(BatchJob{ID: "j1", Caller: "a", CallerClass: ClassFleet, IDemKey: "k", Status: "running", TargetsTotal: 1, CreatedAt: 100, Lease: 1000}); err != nil {
+		t.Fatal(err)
+	}
+	if id, ok := db.BatchJobByIDem("a", "k", 2000, time.Hour); !ok || id != "j1" {
+		t.Fatalf("live idem: %q %v", id, ok)
+	}
+	if _, ok := db.BatchJobByIDem("a", "k", 5000, time.Hour); ok {
+		t.Fatal("lease-expired job must not match")
+	}
+	if _, ok := db.BatchJobByIDem("b", "k", 2000, time.Hour); ok {
+		t.Fatal("other caller must not match")
+	}
+}
+
+func TestBatchLiveCounts(t *testing.T) {
+	db := newBatchDB(t)
+	mk := func(id, caller, status string) {
+		if err := db.CreateBatchJob(BatchJob{ID: id, Caller: caller, CallerClass: ClassFleet, IDemKey: id, Status: status, TargetsTotal: 1, CreatedAt: 1, Lease: 1}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	mk("j1", "a", "queued")
+	mk("j2", "a", "running")
+	mk("j3", "a", "done")
+	mk("j4", "b", "running")
+	if n := db.LiveBatchJobs("a"); n != 2 {
+		t.Fatalf("caller a live=%d want 2", n)
+	}
+	if n := db.LiveBatchJobsTotal(); n != 3 {
+		t.Fatalf("total live=%d want 3", n)
+	}
+}
+
+func TestBatchTargetsOrderedAndUpdate(t *testing.T) {
+	db := newBatchDB(t)
+	must := func(err error) {
+		t.Helper()
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	must(db.CreateBatchJob(BatchJob{ID: "j1", Caller: "a", CallerClass: ClassFleet, IDemKey: "k", Status: "running", TargetsTotal: 3, CreatedAt: 100, Lease: 100}))
+	must(db.PutBatchTargets("j1", []BatchTarget{
+		{JobID: "j1", Idx: 0, URL: "https://a.example/", Options: `{"mode":"clean"}`, Status: "pending"},
+		{JobID: "j1", Idx: 1, URL: "https://b.example/", Status: "pending"},
+		{JobID: "j1", Idx: 2, URL: "https://c.example/", Status: "pending"},
+	}))
+	got, ok := db.BatchTargets("j1")
+	if !ok || len(got) != 3 {
+		t.Fatalf("targets len=%d ok=%v", len(got), ok)
+	}
+	for i := range got {
+		if got[i].Idx != i {
+			t.Fatalf("order broken: got[%d].Idx=%d", i, got[i].Idx)
+		}
+	}
+
+	// A done write bumps the lease to now and counts the target once.
+	res := strp(`{"content":"ok"}`)
+	must(db.UpdateBatchTarget("j1", 0, 200, "done", res, nil, nil))
+	j, _ := db.BatchJob("j1")
+	if j.Lease != 200 || j.TargetsDone != 1 {
+		t.Fatalf("after first write lease=%d done=%d", j.Lease, j.TargetsDone)
+	}
+	// Re-writing the same target (still a done transition) must not double-count.
+	must(db.UpdateBatchTarget("j1", 0, 201, "done", res, nil, nil))
+	j, _ = db.BatchJob("j1")
+	if j.TargetsDone != 1 {
+		t.Fatalf("double-counted: done=%d", j.TargetsDone)
+	}
+	// A failed write counts too.
+	must(db.UpdateBatchTarget("j1", 1, 202, "failed", nil, strp("upstream 500"), strp("browser")))
+	j, _ = db.BatchJob("j1")
+	if j.TargetsDone != 2 || j.Lease != 202 {
+		t.Fatalf("after failed write lease=%d done=%d", j.Lease, j.TargetsDone)
+	}
+}
+
+func TestBatchTouchAndStatus(t *testing.T) {
+	db := newBatchDB(t)
+	if err := db.CreateBatchJob(BatchJob{ID: "j1", Caller: "a", CallerClass: ClassFleet, IDemKey: "k", Status: "running", TargetsTotal: 1, CreatedAt: 100, Lease: 100}); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.TouchBatchJob("j1", 500); err != nil {
+		t.Fatal(err)
+	}
+	if j, _ := db.BatchJob("j1"); j.Lease != 500 {
+		t.Fatalf("touch lease=%d want 500", j.Lease)
+	}
+	if err := db.SetBatchJobStatus("j1", "cancelled", "", 600); err != nil {
+		t.Fatal(err)
+	}
+	if j, _ := db.BatchJob("j1"); j.Status != "cancelled" || j.Lease != 600 {
+		t.Fatalf("status=%q lease=%d", j.Status, j.Lease)
+	}
+}
+
+func TestSweepBatch(t *testing.T) {
+	db := newBatchDB(t)
+	mk := func(id string, lease int64) {
+		if err := db.CreateBatchJob(BatchJob{ID: id, Caller: "a", CallerClass: ClassFleet, IDemKey: id, Status: "done", TargetsTotal: 1, CreatedAt: 1, Lease: lease}); err != nil {
+			t.Fatal(err)
+		}
+		if err := db.PutBatchTargets(id, []BatchTarget{{JobID: id, Idx: 0, URL: "https://x.example/", Status: "done", Result: strp("x")}}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	mk("old", 100)
+	mk("new", 1000)
+	n := db.SweepBatch(300, 100*time.Second) // old: 100+100=200<=300 expired; new: 1100>300 kept
+	if n != 1 {
+		t.Fatalf("swept %d want 1", n)
+	}
+	if _, ok := db.BatchJob("old"); ok {
+		t.Fatal("old job must be gone")
+	}
+	if _, ok := db.BatchJob("new"); !ok {
+		t.Fatal("new job must remain")
+	}
+	if _, ok := db.BatchTargets("old"); ok {
+		t.Fatal("old targets must be gone")
+	}
+}
+
+func TestEvictBatchOldest(t *testing.T) {
+	db := newBatchDB(t)
+	done := func(id string, lease int64, size int) {
+		if err := db.CreateBatchJob(BatchJob{ID: id, Caller: "a", CallerClass: ClassFleet, IDemKey: id, Status: "done", TargetsTotal: 1, CreatedAt: 1, Lease: lease}); err != nil {
+			t.Fatal(err)
+		}
+		if err := db.PutBatchTargets(id, []BatchTarget{{JobID: id, Idx: 0, URL: "https://x.example/", Status: "pending"}}); err != nil {
+			t.Fatal(err)
+		}
+		if err := db.UpdateBatchTarget(id, 0, lease, "done", strp(strings.Repeat("x", size)), nil, nil); err != nil {
+			t.Fatal(err)
+		}
+	}
+	done("old1", 100, 100)
+	done("old2", 200, 200)
+	done("new", 300, 300)
+
+	// A running job with one completed target must never be byte-evicted.
+	if err := db.CreateBatchJob(BatchJob{ID: "run", Caller: "a", CallerClass: ClassFleet, IDemKey: "run", Status: "running", TargetsTotal: 2, TargetsDone: 1, CreatedAt: 1, Lease: 400}); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.PutBatchTargets("run", []BatchTarget{
+		{JobID: "run", Idx: 0, URL: "https://x.example/", Status: "pending"},
+		{JobID: "run", Idx: 1, URL: "https://y.example/", Status: "pending"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.UpdateBatchTarget("run", 0, 400, "done", strp(strings.Repeat("x", 500)), nil, nil); err != nil {
+		t.Fatal(err)
+	}
+
+	// total nbytes = 100+200+300+500 = 1100. Evict oldest done until <= 250:
+	// old1(100), old2(200), new(300) all evicted (oldest first); run stays (live).
+	db.EvictBatchOldest(250)
+	for _, id := range []string{"old1", "old2", "new"} {
+		if _, ok := db.BatchJob(id); ok {
+			t.Fatalf("%s should be byte-evicted", id)
+		}
+	}
+	if _, ok := db.BatchJob("run"); !ok {
+		t.Fatal("running job must not be byte-evicted")
+	}
+	if n := db.BatchNbytes(); n != 500 {
+		t.Fatalf("BatchNbytes=%d want 500", n)
+	}
+}
+
+func TestMarkInFlightFailed(t *testing.T) {
+	db := newBatchDB(t)
+	mk := func(id, status string) {
+		if err := db.CreateBatchJob(BatchJob{ID: id, Caller: "a", CallerClass: ClassFleet, IDemKey: id, Status: status, TargetsTotal: 1, CreatedAt: 1, Lease: 1}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	mk("q", "queued")
+	mk("r", "running")
+	mk("d", "done")
+	if n := db.MarkInFlightFailed("restart", 999); n != 2 {
+		t.Fatalf("marked %d want 2", n)
+	}
+	if j, _ := db.BatchJob("q"); j.Status != "failed" || j.Error != "restart" || j.Lease != 999 {
+		t.Fatalf("q %+v", j)
+	}
+	if j, _ := db.BatchJob("r"); j.Status != "failed" || j.Error != "restart" {
+		t.Fatalf("r %+v", j)
+	}
+	if j, _ := db.BatchJob("d"); j.Status != "done" {
+		t.Fatalf("done job changed: %+v", j)
+	}
+}

docs/plans/p6/_files/metrics/batch_test.go

@@ -0,0 +1,61 @@
+package metrics
+
+import (
+	"io"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+type batchSrc struct{}
+
+func (batchSrc) Snapshot() Snapshot { return Snapshot{} }
+
+func TestBatchSeries(t *testing.T) {
+	s := New(batchSrc{})
+	s.ObserveBatchJob("created")
+	s.ObserveBatchJob("done")
+	s.ObserveBatchJob("done")
+	s.ObserveBatchJob("reused")
+	s.ObserveBatchJob("some raw string") // folded to "other", never a label
+	s.ObserveBatchTarget("ok")
+	s.ObserveBatchTarget("ok")
+	s.ObserveBatchTarget("blocked")
+	s.ObserveBatchTarget("upstream_5xx")
+	s.ObserveBatchTarget("leak me") // folded to "other"
+	s.SetBatchQueueDepth(3)
+	s.SetBatchTargetsInflight(1)
+	s.ObserveBatchJobSeconds(4 * time.Second)
+	s.ObserveBatchTargetSeconds(1500 * time.Millisecond)
+	s.ObserveBatchResultBytes(4096)
+
+	req := httptest.NewRequest("GET", "/metrics", nil)
+	req.RemoteAddr, req.Host = "127.0.0.1:9", "127.0.0.1:8890"
+	rec := httptest.NewRecorder()
+	s.Handler().ServeHTTP(rec, req)
+	body, _ := io.ReadAll(rec.Body)
+	out := string(body)
+	for _, want := range []string{
+		`sift_batch_jobs_total{outcome="created"} 1`,
+		`sift_batch_jobs_total{outcome="done"} 2`,
+		`sift_batch_jobs_total{outcome="reused"} 1`,
+		`sift_batch_jobs_total{outcome="other"} 1`,
+		`sift_batch_targets_total{outcome="ok"} 2`,
+		`sift_batch_targets_total{outcome="blocked"} 1`,
+		`sift_batch_targets_total{outcome="upstream_5xx"} 1`,
+		`sift_batch_targets_total{outcome="other"} 1`,
+		`sift_batch_queue_depth 3`,
+		`sift_batch_targets_inflight 1`,
+		`sift_batch_job_seconds_count 1`,
+		`sift_batch_target_seconds_count 1`,
+		`sift_batch_result_bytes_count 1`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("metrics lack %q", want)
+		}
+	}
+	if strings.Contains(out, "raw") || strings.Contains(out, "leak") {
+		t.Error("a raw outcome string leaked into a label")
+	}
+}