slash-do 2.11.0 → 2.13.0

package/lib/review-cross-file-contract.md

@@ -0,0 +1,186 @@
+# Cross-File Contract Review Agent
+
+## Mandate
+You review code by tracing CONTRACTS across files: schema/shape agreements, validation parity, error classification, field-set enumerations, intent-vs-implementation claims that span multiple files, and architectural-pattern adherence. You catch issues invisible at single-file review where producer and consumer hold incompatible expectations — schema fields the implementation drops, validation gaps between sibling endpoints, response shapes that diverge between primary and fallback paths, audit logic that diverges from authoritative production logic. You do NOT trace runtime state/lifecycle propagation across files (the cross-file tracing agent handles state, async coordination, resource cleanup, and concurrency).
+
+## Approach
+
+Apply the checklist as a prompt for attention, not an exhaustive specification. Reason about contracts as agreements between TWO sides: a producer and a consumer (writer/reader, validator/persister, schema/handler, route/service, client/server). When the two disagree on shape, type, value-set, semantics, or completeness, flag it — even if no checklist item names the exact pattern.
+
+## Reading Strategy
+1. Read ALL changed files to understand each module's responsibility
+2. For each new/modified data shape (request, response, event, persisted record), identify the producer AND every consumer; verify field-by-field agreement on names, types, optionality, value sets
+3. For each new/modified validation rule, verify it applies on EVERY write path (create, update, sync, bulk, internal)
+4. For each new error classification, verify wrappers preserve the fields downstream classifiers depend on
+5. For each documented or commented behavior, verify the implementation actually delivers it
+
+## Principles to Evaluate
+
+**DRY** — Logic duplicated across files (similar validators, response builders, error wrappers, schema definitions) drifts. Two near-identical implementations are a refactor opportunity AND a contract risk.
+
+**SOLID — Interface Segregation, Liskov substitution** — Consumers should depend only on the contract they actually use; substitutable producers must honor the same contract.
+
+## Checklist
+
+### Error Handling
+
+- Service functions throwing generic Error for client conditions — 500 instead of 400/404. Consistent access-control responses across endpoints. Concurrency failures → 409 not 500
+- Swallowed errors; generic messages replacing detail — including cross-layer error propagation: if the server returns structured error details (field-level validation messages, `details[]` arrays, error codes), the client layer should surface actionable detail rather than discarding structure for a generic string. External service wrappers returning null for all failures (collapsing config errors, auth, rate limits, 5xx into "not found")
+- Caller/callee disagreement: `{ success: false }` vs `.catch()`; gate returning `{ shouldRun: false }` on error vs fail-open runtime; argument shape mismatches (wrapped object vs bare array, wrong positional order); async EventEmitter handlers creating unhandled rejections
+- Destructive ops in retry/cleanup paths without own error handling
+- External service calls without configurable timeouts
+- Missing fallback for unavailable downstream services
+- SSE or streaming handlers that call `end()`/`close()` on mid-stream errors without emitting an error event — the client observes a clean stream termination and treats partial content as complete. Emit a structured `event: error` block before closing so clients can detect and surface the failure. Conversely, named lifecycle events (`error`, `done`, `complete`) must be MUTUALLY EXCLUSIVE — after emitting `error`, do NOT also emit `done`, or include explicit success/error info in the terminal frame. Trace every exit path of the stream generator and the route's loop body to verify only one terminal event fires
+- Streaming server handlers whose abort signal is wired into ONLY the final consumer (e.g., the LLM provider fetch) but not into upstream retrieval / embedding / subprocess work — disconnects don't actually stop the expensive earlier work. Trace the AbortSignal from `req.on('close')` through every async leg of the pipeline and verify each takes a `signal` parameter and propagates it
+- Raw `fetch()` failures (TypeError "Failed to fetch", DNS errors, ECONNREFUSED) at API client boundaries must be translated to a consistent message matching the project's established transport-error utility. Trace each new API client function against existing siblings (`apiCore.request`, `apiOpenClaw.streamMessage`) and verify the same wrapper is used; preserve `AbortError` so callers distinguish cancellation from failure
+- SSE or event dispatchers that handle named event types but ignore the protocol's default/unnamed event — SSE streams that emit `data:` without `event:` produce type `'message'` (the SSE default), which a handler processing only named types will silently discard. Verify the default event type is either handled or explicitly excluded
+- Route handlers that call a status/health probe before delegating to the main service when the service already handles the "not configured"/"unreachable" case — the pre-probe adds an extra upstream round-trip on every request and can fail even when the intended operation would succeed. Let the service be the authoritative source of truth and map its structured errors to the appropriate HTTP status at the route boundary
+- Sync-shaped route handler (`POST /generate`, `POST /txt2img`) wrapping a service that is async-by-design (returns a job handle, writes the artifact later) — the handler must subscribe to the completion event BEFORE calling the service (so a fast/cached job can't fire `complete` before the listener attaches) AND wait for the matching job id with a timeout. Common bug: the handler reads `result.filename` from disk immediately after the service returns, gets nothing, and replies with an empty success payload. Trace from route → service → completion-event/file-watcher → response builder; verify the route awaits a real readiness signal, not just the service's job-handle return. If the service is callable both async (jobId-only) and sync (await artifact), expose the sync variant explicitly (`generateAndWait` / `generateSync`) rather than mixing modes
+- Cross-module feature-flag detection drift — when multiple modules independently determine "is feature X active?" (HTTPS enabled, OAuth scopes, dark mode, a tier-gated capability) using divergent checks, behavior diverges and the user-visible UX contradicts itself. Examples: client UI checks one cert file while the server requires both; client hardcodes an `https://` scheme while the server is running plain HTTP; one helper checks `cert.pem` exists, another checks `cert.pem && key.pem`. Centralize the predicate in a single exported helper (`hasTailscaleCert()`, `isHttpsEnabled()`, `userHasScope(scope)`) and have every caller import it. Flag any module that re-derives the same boolean inline
+- Cross-module error classification — a low-level wrapper rethrows errors with a different `name`/`code`/`message` shape than the original (e.g., a custom fetch wrapper aborts with `new Error('Request aborted')` while the classifier downstream checks `err.name === 'AbortError'`). The classifier matches nothing and the timeout/cancel branch never fires. Either preserve `name`/`code`/`cause` through the wrapper, OR have the classifier accept the union of shapes the wrapper can emit. Trace each error-classifying call site back to the wrapper(s) that produce its inputs and verify the contract holds
+- Compatibility-shim end-to-end plumbing — when a route bridges to an external API standard (A1111 SD-API, OpenAI, S3-compatible, etc.) every documented response field must be backed by a real value chain through the provider, intermediate service, and response builder. Common bug: the response shape is correct but a field like `seed`, `progress`, `eta`, `model`, or `usage.tokens` is hardcoded to a default (`0`, `null`, the request input) because nothing in the chain actually returns it. Trace each declared response field from where it's set in the route → the service's return shape → the underlying provider/process output, and confirm the value flows end-to-end; placeholder fields ("we'll plumb it later") break clients that depend on the standard. Same trace applies to "always returns 0 / always undefined / always empty array" patterns in the response — they signal incomplete plumbing
+- Catch-all fallback that synthesizes a SUCCESS-shaped payload indistinguishable from a legitimate quiet state — e.g., catching any IPC/RPC failure and returning `{ success: true, status: { isRunning: false } }` so the dashboard renders "engine cleanly stopped" whether the engine is actually stopped, timing out, or crashed. Operators can't distinguish "expected idle" from "outage". Either preserve a distinct health/mode value the UI recognizes as "outage" AND ensure every consumer maps it, OR translate the underlying error to a specific HTTP status. Don't gate the fallback on broad rejection types — distinguish timeout, connection-refused, and method-not-found
+
+### Validation & Consistency
+
+- Breaking changes to public API without version bump or deprecation path
+- Backward-incompatible changes (renamed config keys, file formats, schemas, event payloads, routes, persisted data) without migration or fallback. Route renames need redirects
+- Data migrations silently changing runtime behavior — preserve execution semantics. Unsupported source values must be flagged, not defaulted
+- Update endpoints with field allowlists not covering new model fields
+- New endpoints not matching validation patterns of existing similar ones. The same field (id, name) accepted by multiple endpoints must be validated identically everywhere — path params, query, body, on sibling endpoints (create/update/delete/activate). Skipping param validation on one sibling turns violations into 404/500 instead of 400. `z.string().min(1)` without `.trim()` accepts whitespace-only names. API doc schemas must be structurally complete
+- Client-side input validation limits (max count, file size, string length, combined totals) must be consistent with — and ideally tighter than — server-side enforcement. When the client allows combinations the server rejects (e.g., 8 × 10MB files vs a 50MB JSON body limit), users hit confusing 400/413 errors. Trace all enforcement boundaries (UI, API schema, body parser, downstream service) and verify they form a coherent envelope
+- Sample config files, README examples, and documentation that reference config keys or structure must match what the implementation actually reads. Trace example keys against the config loader — stale examples teach operators to configure values the system ignores (or vice versa)
+- Subprocess invocations must inherit the same configuration source as the parent — if the parent reads from `.env`/config files but the child only sees `process.env`, exporting those values explicitly via the `env` option is required. Trace from config loader → invocation site → subprocess script. Otherwise a probe uses customized credentials/ports while the underlying setup runs with defaults, creating an "inconsistency loop" where the probe always fails and provisioning re-applies defaults that overwrite user customization
+- Config values whose format can be validated at initialization time (URLs, port numbers, auth schemes) but are only validated at first use — misconfiguration surfaces as a cryptic runtime error deep in the call stack. Validate format and range of security-relevant config values during initialization and surface a specific diagnostic identifying the bad field
+- URL joining utilities that force paths absolute-from-origin (stripping the base URL's pathname) — `baseUrl=http://host/proxy` + `/v1/api` silently produces `http://host/v1/api` instead of `http://host/proxy/v1/api`. Verify URL construction utilities preserve pathname segments from the base URL, or document and enforce that base URLs must be origin-only
+- Summary/aggregation endpoints using different filters/sources than detail views they link to
+- Discovery endpoints must validate against consumer's actual supported set. Identifier transformations between producer and consumer must preserve expected format
+- Validation functions introduced for a field: trace ALL write paths. New branches must apply same validation as siblings
+- Foreign-key existence-check parity across write paths — when a create endpoint validates that a referenced ID exists (`createWork` checks `folderId` resolves to a folder; `createComment` checks `postId` exists) before persisting, every other write path that accepts the same field (update/PATCH, bulk import, sync, admin override, internal callers) MUST apply the same existence check. Partial coverage allows orphaned references through the unguarded path: `updateWork({ folderId: 'nonexistent' })` succeeds, the work appears in no folder's listing, and cascade/group operations break. Trace every endpoint that writes the foreign-key field and verify the existence check; same applies to nullable references — null is fine, but a non-null value must resolve. Also covers cross-entity invariants (parent must be of correct type, owner must be active, target must not be self)
+- Stored config merged with shallow spread — nested objects lose new default keys on upgrade. Use deep merge
+- Schema fields accepting values downstream can't handle. Validated params never consumed (dead API surface). `.partial()` on nested schemas: verify nested objects also partial. `.partial()` with `.default()` silently overwrites persisted values on update
+- Generator/validator structural invariant — when a generator produces values with structural guarantees (sortability via fixed-width prefix, embedded checksum, encoded version), the validator regex (and any client-side mirror) must enforce the SAME shape. Broader regexes accept inputs the generator never emits, breaking invariants the rest of the system relies on (e.g., lexical sort == chronological sort breaks once a base36 timestamp grows by a digit). Trace generator → server validator → client mirror as a closed loop. Test fixtures should use IDs/payloads that match generator output, not contrived literals
+- Schemas accepting paired range fields (`startDate`/`endDate`, `min`/`max`, `from`/`to`) without a cross-field refinement (`zod .refine()`) — accepts inconsistent ranges (start > end). Trace the schema definition, route validation, and downstream consumer to confirm the range relationship is enforced somewhere (preferably at the schema)
+- Required-at-use-time config values (model name, API key, endpoint URL, default selection) that may be null/undefined in the source data must be validated at the boundary before invoking the downstream API. Trace from config source → loading layer → use site, and verify nullable fields are guarded with a clear, actionable error before the downstream call. Otherwise the downstream API responds with an opaque error far from the user's intent
+- Multi-part UI gated on different prop subsets — derive single enablement boolean
+- Entity creation without case-insensitive uniqueness
+- Arrays of IDs (widget ids, tag ids, member ids) persisted, returned by API, or rendered with `key={x}` without container-level dedup — element-level validation (type, length) isn't enough. Enforce uniqueness via schema refinement (`zod.refine(arr => new Set(arr).size === arr.length)`), dedupe on ingest, AND dedupe during read-path sanitization so hand-edited / legacy data can't reintroduce collisions. Apply the same first-wins dedup to arrays of records keyed by id at the container level
+- Data loaded from files or persistent stores sanitized less strictly than the API accepts on write — hand-edited, migrated, or corrupted persisted state can introduce values (oversized names, non-kebab ids, duplicate entries) the API rejects on mutate, producing oversized responses, unreachable records, or invariant violations. Apply the same length caps, regex, uniqueness, and type guards in read-path sanitization as in request validation
+- Code reading response properties that don't exist — verify field names, nesting, actual response shape. Wrappers that don't request/forward needed fields. Call sites using wrong function variant for input format or wrong positional argument order
+- Data model fields with different names per write path. Entity identity keys inconsistent across lookup paths
+- Entity type changes without revalidating type-specific invariants and clearing old-type fields
+- Config flag invariants (A implies B) not enforced across all layers: UI toggles, API validation, server defaults, persistence
+- Operations scoped to entity subtype without verifying discriminator — wrong type corrupts state
+- Inconsistent "missing value" semantics (null vs empty string vs whitespace) across layers. Validation returning null when null means "clear" downstream. Normalization applied inconsistently between write and comparison paths
+- Validation delegating to runtime computation — conflating "no result in window" with "invalid input"
+- Numeric strings without NaN/type guards. Hand-rolled regex for well-known formats — use platform parsers. For URLs of structured services (GitHub/GitLab PR URLs, OAuth callback URLs, custom protocols), use `new URL()` and validate: protocol allowlist (reject non-http(s) like `file:`, custom schemes), `parsed.hostname` not `parsed.host` (host includes port), exact path-segment shape (e.g., `/<owner>/<repo>/pull/<n>` is exactly two segments before `pull`), and a numeric/format check on terminal segments. Allow trailing path suffixes (`/pull/123/files`) without mis-parsing earlier segments as the project. Empty hostname or set port should reject by default unless explicitly supported
+- Identifier fields used as delimiter-separated keys (`<kind>:<ref>`, `owner/repo`, `tag,name`, `bucket#object`) must reject the delimiter character at validation time — otherwise persisted entries become unaddressable through the API (DELETE/GET/PATCH that splits on the delimiter gets the wrong segments) and cross-component matching (cover keys, cache keys) breaks. Trace from the field's validator (regex, schema) through every consumer that splits on the delimiter, and verify the delimiter is in the rejected character set
+- Persisted JSON loaders (`loadProjects()`, `loadHistory()`, `loadCollections()`) called at runtime must normalize the parsed root shape — hand-edited or corrupted persistence (`{}` instead of `[]`, `null` instead of `{}`) crashes downstream `.find` / `.unshift` / `.map` callers and breaks all reads after the first bad write. Apply `Array.isArray(parsed) ? parsed : []` (or `isPlainObject` for object roots) in EVERY loader, not just the import-time bootstrap, and trace each loader's consumers to verify they don't assume shape that the loader doesn't enforce
+- Forge/host detection from data source vs reference source — when a function operates on data from one source (PR URL) but determines runtime behavior from a different source (the local repo's `origin` remote, the cwd's git config), the two can disagree, leading to `gh api` calls against GitLab MRs or vice versa. Carry the forge/host discriminator with the data: parse it out of the URL itself and use that to choose the CLI/API path, OR explicitly require both inputs to come from the same source and validate their agreement before proceeding
+- Last-precedence wins for layered config blocks — when parsing config files (PM2 ecosystem, docker-compose, env-file layers) that allow multiple scope blocks for the same key (`env`, `env_development`, `env_production`), key extraction must respect explicit precedence (later/more-specific blocks override earlier/general) — not first-wins-then-skip. Otherwise a `PORT` defined in both `env` and `env_production` reserves whichever appears first in the file, which is rarely the runtime value
+- UI hidden from nav but accessible via direct URL
+- Summary counters missing edge cases; counters incremented before confirming state change; batch ops reporting success while logging per-item failures
+
+### Cross-File Consistency
+
+- New functions following existing patterns must match ALL aspects (validation, error codes, response shape, cleanup). Partial copying is #1 review feedback source
+- Multiple code paths emitting what should be the SAME response/event/snapshot (e.g., a status payload constructed by a primary engine, a stopped-engine IPC handler, a route fallback, AND a websocket emitter) drift over time as fields are added. Extract the shape into a single shared builder that every emission point imports, AND lock the contract with a snapshot/contract test. When a fix targets shape drift, audit whether the fix REMOVES it (consolidates emitters) or PERPETUATES it (adds a 4th hand-built copy inline). Trace every emission site, count distinct construction sites, recommend consolidation when N > 2
+- Fallback or degraded-mode response shape must be a SUPERSET of fields the consumer reads — when consumers treat the response as a full replacement (`setStatus(res.status)` rather than merging), missing fields cause UI sections to disappear or default to wrong values (`apy`, `lifecycle`, `health.mode`, `market.lastPrice`). Don't rely on "the consumer will preserve the last good value via socket merging" without verifying the actual reload code path — a hard refresh during fallback may have no prior state to merge with. Inventory every field the consumer reads on the happy path, and verify the fallback emits a meaningful value (or explicit "stale/unknown" marker the consumer recognizes) for each
+- Schema migrations that COPY a value from an old field to a new field WITHOUT clearing the old field can leave both populated. Code reading BOTH fields and emitting one record per non-null instance produces duplicate output keyed by the same underlying identifier (the same orderId rendered twice with different categorizing types). Either clear the old field after migration, dedupe by stable id when emitting, or read only the migration-target field once a completion guard confirms migration ran. Trace from the migration step through every read path that enumerates the affected fields
+- Audit, lint, anomaly, and analytics tools that re-derive a domain concept (current cycle, active session, completed period) using a SIMPLIFIED heuristic must match the authoritative production logic — or they produce false positives/negatives. When production keeps a cycle active until `sellRatio < 1.0`, the audit can't use a 50% threshold. When production tracks a persisted `currentCycleId`, the audit can't fall back to "newest activity wins". Either invoke the authoritative function/predicate, OR snapshot-test the audit against production-state fixtures. Same applies to suppression rules — gating "ignore this anomaly" on a stale signal hides real issues
+- New API client functions must use same encoding/escaping as existing ones
+- New endpoints must be wired in all runtime adapters (serverless, framework routes, gateway)
+- New external service calls must use established mock/test infrastructure
+- New UI consumers against existing APIs: verify every field name, nesting, identifier, response envelope matches actual producer response
+- Discovery/catalog endpoints: trace enumerated set against consumer's supported inputs
+- Cross-platform script-flag parity — when a JS service spawns platform-specific scripts (`generate.py` on macOS/Linux, `generate_win.py` on Windows; `setup.sh` vs `setup.ps1`; per-OS helpers), every flag/argument the dispatching service emits must be implemented in EVERY platform script. Partial coverage causes "unrecognized arguments" / silent ignores on the other OS the moment that path runs. Trace from `buildArgs()` through the spawn call to each platform script's argparse/parameter definitions and verify coverage. If support is intentionally asymmetric, gate the flag emission by platform (`if (!IS_WIN) args.push('--image-strength', ...)`) and update inline comments to match the real behavior — don't ship STATUS lines or comments claiming a feature works when the underlying script ignores it
+- When a codebase already has an established helper for a common operation (`atomicWrite()` for safe file replacement, `request({ silent })` for non-toasting fetch, `withTimeout()` polyfilling `AbortSignal.any`, `safeUnder()` for path containment), every new caller for the same operation must use the helper — bare `writeFileSync`/`fetch`/`AbortSignal.any` reintroduces the bug the helper was created to fix. Search for the existing wrapper before adding a new direct call, and flag drift between the safe path and the new direct call
+- Architectural pattern divergence — every new module/file/feature addresses a class of concern, and the project usually has an ESTABLISHED pattern for that class. New code MUST adopt the established pattern rather than introduce a parallel implementation. Classes to consider (non-exhaustive): **data storage & persistence** (repository modules, ORM models, file-backed registries, migration conventions, key/index naming), **content/template management** (prompt registries, template directories, locales/translations, theme tokens, schema definitions, presets, recipes), **API endpoints** (route mounting, middleware chain, validation library, request/response shape, pagination/error envelope), **authentication & authorization** (auth helpers, scope/role gates, session lookup, principal extraction), **error handling** (typed error classes, status-code mapping, error-response builder, structured `details[]`), **logging & observability** (structured logger, correlation-ID propagation, log-level conventions, metric/trace emitters), **configuration loading** (env-var schema, settings file, deep-merge defaults, validation at boundary), **HTTP/transport clients** (fetch wrapper, retry helper, abort/timeout utility, base URL/auth header injection), **caching** (cache helper, key conventions, invalidation hooks, TTL policy), **background work** (queue/worker convention, job lifecycle events, retry/backoff policy), **state management** (store/context/hook patterns, action shape, selector conventions), **testing infrastructure** (fixture builders, mock harness, snapshot conventions, e2e scaffolding), **inter-service communication** (RPC clients, event/pub-sub conventions, message-envelope shape), **file/path & naming conventions** (directory layout, casing, suffixes, sibling-file pairing). Common offenders: a new `*Prompts.js`/`*Templates.js`/`*Copy.js`/`*Defaults.js` hardcoding content the project manages via a registry directory + loader; a new endpoint hand-rolling validation/error responses while siblings use a shared validator + error class; a new feature reading from disk directly when peer features go through a repository module; a new auth check inline when peers route through a centralized scope/role helper; a new `console.log` statement when the rest of the codebase uses a structured logger with correlation IDs; a new `fetch()` call without the project's transport-error wrapper / retry / abort utility; a new background task spawned inline when peers use a queue/worker pattern; a new state slice using `useState` when peers use the project's store; a new test that hand-rolls fixtures the rest of the suite gets from a shared builder. Detection methodology: (a) classify the concern(s) the new code addresses; (b) inventory how peer features in the same service handle that same class — search for sibling directories (`data/`, `templates/`, `locales/`, `schemas/`, `presets/`, `recipes/`, `migrations/`, `repositories/`, `services/`, `middleware/`, `clients/`, `queues/`, `stores/`), helper modules (`load*`, `get*`, `resolve*`, `*Registry`, `*Repository`, `*Service`, `*Client`, `*Worker`), shared types (error classes, schema definitions, response builders, action types), and centralized utilities (auth gates, logger, transport wrapper, retry helper, cache wrapper, config loader); (c) compare the new code's pattern to the dominant peer pattern; (d) flag every divergence — even if the new code "works" in isolation. Recommend either (i) refactor the new code onto the established pattern, OR (ii) extend the established pattern to cover a structural gap (a missing variable type, scope, error category, response field, retry policy, log dimension, queue type) — the established artifact, not the bypass, should be the durable surface. Hardcoded parallel implementations create maintenance drift, break invariants the dominant pattern enforces (variable substitution, error classification, auth-scope coverage, log correlation, retry/backoff, transactional boundaries), fragment the audit/diff surface for changes in that class, prevent the established edit/operate workflow, and force future readers to learn N implementations of the same concept
+- Compound visual state propagation through child components — when a parent component supports a visual state (`dimmed`, `disabled`, `loading`, `selected`, `muted`) that should affect its entire visual presence, every visual sub-component (text labels, halos, edge strips, ground glow, accents, neon lines, hologram overlays, ring/border meshes) must inherit and apply the state. Threading the prop only into the primary mesh/material/text leaves surrounding decorations at full opacity, so non-matching items still read as "lit" and the visual filter fails. Centralize via a single shared multiplier prop passed to every child, OR enumerate all opacity/emissive/color sites and verify each consumes the state
+- Cross-module constants kept in sync by comment ("must stay in sync with X", duplicated regex, duplicated event name, duplicated size limit) — the comment is not enforcement and drift is a silent failure. Event names, regex patterns, numeric limits, path segments, and feature-flag keys shared across modules (client↔server, route↔service, component↔component, producer↔consumer) must be a single exported constant imported by both. Flag any instance where a comment notes "keep in sync" without the actual shared module
+- New global APIs (`AbortSignal.any`, `Promise.withResolvers`, `structuredClone`) used directly when the codebase already has a fallback utility for the same API — search for an existing wrapper (`fetchWithTimeout`, `withSignal`, polyfill helpers) before adding a new direct call. Drift between the safe path and a new direct call reintroduces the runtime error the fallback was created to avoid
+- Pure persistence/utility modules importing from orchestration/service modules just to access a constant pulls the entire downstream import graph as a transitive dependency. Trace each `import` in storage / utility files; if the imported symbol is a constant (enum, regex, size cap, valid-mode set), suggest moving it to a small dedicated shared module
+- Modules that own a persistence schema (write to disk/DB with a known shape) should validate at the persistence boundary, not assume the API/route layer will catch everything. Trace from route validator → service call → persistence write — verify enum/range/required checks exist at the storage layer for fields the schema cares about. Direct callers (internal scripts, tests, programmatic batch jobs) bypass route validation otherwise
+
+### Specification Conformance
+- Parsers for well-known formats (cron, dates, URLs, semver): verify boundary handling matches spec — field ranges, normalization, step/range semantics
+
+### Boolean/type Fidelity Through Serialization
+- Boolean flags persisted to text (markdown metadata, query strings, flat files): trace write → storage → read → consumption. `"false"` is truthy — verify strict equality at all consumption sites
+
+### Cross-layer Invariant Enforcement
+- Config flag invariants (A implies B): trace through UI toggles, form submission, route validation, server defaults, persistence round-trip
+
+### Error Path Completeness
+- Each error reaches user with helpful message and correct HTTP status. Multi-step operations track per-item failures separately from overall success
+
+### Entity Identity Key Consistency
+- Computed lookup keys (e.g., `e.id || e.externalId`): trace all paths using same computation — inconsistent keys cause mismatches
+
+### Intent vs Implementation (cross-file)
+- Cross-references between files (identifiers, param names, format conventions, versions, thresholds) that disagree — trace all references when one changes. Internal identifiers renamed when concept renamed
+- Modified values referenced in other files: trace all cross-references
+- Responsibility relocated from one module to another: trace all dependents at old location (guards, return values, state updates). Remove dead code at old location
+
+### Batch/Paginated Consumption
+- Batch API callers handle partial results, continuation tokens, rate limits with backoff. Resource names account for environment prefixes
+- Periodic maintenance (cleanup, expiry, dedup) bolted onto a paginated read path runs only for items returned in that page — entries beyond the boundary are never processed. Trace from list endpoint → maintenance/sweep code → the iteration that bounds it. Move maintenance to a background sweep, run a separate unbounded pass, OR use cheap metadata (mtime, size) for the maintenance pass while only doing expensive reads for the page actually returned. Maintenance gates that depend on parsed metadata fields will skip records where parsing returns a sentinel (0, null, "") — those records become permanent
+
+### Deep-link URL Contract (sender ↔ receiver)
+- A URL with query parameters (`?id=...`, `?date=...`) or path segments is a contract: the receiving page/route MUST consume those parameters and use them to scroll/select/filter. Trace each new deep-link href to the destination route handler / page component and verify it reads and acts on every parameter the sender includes. If the receiver doesn't yet support the parameter, either drop it (and adjust docs/changelog claims) or wire it through end-to-end
+
+### Data Model vs Access Pattern
+- Claims of ordering ("recent", "top") verified against key/index design — random UUIDs require full scans
+
+### Update Schema Depth
+- Update schemas from create (`.partial()`): nested objects must also be partial
+
+### Multi-source Data Aggregation
+- Items from multiple sources: retain source identifier through aggregation for downstream routing
+
+### Field-set Enumeration Consistency
+- Operations targeting field sets: trace every other enumeration (UI predicates, filters, docs, tests) — prefer single source of truth
+
+### Abstraction Layer Fidelity
+- Wrappers requesting all fields handlers depend on — third-party APIs often require opt-in. Mutually exclusive params: strip conflicts. Framework function variants match input format. Positional args match called function's parameter order
+
+### Parameter Consumption Tracing
+- Validated params: trace to actual consumption. Unread params create dead API surface — wire through or remove
+
+### Summary/Aggregation Consistency
+- Dashboard counts vs detail views: same filters, ordering. Navigation links propagate aggregated context
+
+### Data Model / Status Lifecycle
+- Changed statuses/enums: sweep API docs, UI filters, conditional rendering, routes, tests. Renamed concepts: trace all manifestations (routes, components, variables, CSS, tests)
+
+### Type-discriminated Entities
+- Discriminator changes: trace all code paths (migration, bulk, UI type-switchers) — verify downstream branching handles all transitions
+
+### Data Migration Semantics
+- Migrated fields preserve behavioral meaning. Concurrency protection for read-triggered migrations. Unsupported source values flagged not defaulted
+
+### Bulk vs Single-item Parity
+- Single-item CRUD changes: trace corresponding bulk operation — verify same fields, validation, secondary data
+
+### Config Auto-upgrade Provenance
+- Auto-upgrade logic: distinguish user customization from previous default — without provenance, overwrites intentional customizations
+
+### Query Key / Stored Key Alignment
+- Lookup key precision/encoding/format matching write path — mismatches return zero matches
+
+### Subprocess Condition Detection
+- Subprocess output parsed to detect conditions: check both stdout and stderr plus exit code — location varies by tool version
+
+### Formatting Consistency
+- New content matches file's existing indentation, bullets, headings, structure
+
+## Output Format
+
+For each finding:
+```
+file:line — [CRITICAL|IMPROVEMENT|UNCERTAIN] description
+Cross-file trace: file_a:line → file_b:line (what flows between them)
+Evidence: `quoted code from each file`
+```
+
+Only report verified findings with cross-file evidence. If the trace is uncertain, mark [UNCERTAIN].

package/lib/review-cross-file-tracing.md

@@ -1,7 +1,7 @@
 # Cross-File Tracing Review Agent
 
 ## Mandate
-You review code by tracing data and control flow ACROSS files. You catch issues invisible in single-file review: mismatched contracts, broken call chains, stale state propagation, lifecycle gaps, and architectural violations.
+You review code by tracing STATE, LIFECYCLE, AND CONCURRENCY across files. You catch issues invisible at single-file review: stale state propagation, lifecycle gaps (mount/unmount, init/cleanup, started/completed), resource leaks, lock/flag exit paths, and concurrent-mutation races. You do NOT audit data shape contracts, validation parity, error classification, or architectural-pattern adherence (the cross-file contract agent handles that).
 
 ## Approach
 
@@ -45,68 +45,24 @@ Apply the checklist as a prompt for attention, not an exhaustive specification.
 - Optimistic UI messages that substitute placeholder text when the actual payload sent to the server differs — the conversation history and server-side record will show different content than what the user saw. Use the same fallback text in both the optimistic render and the outgoing payload, or surface the actual payload text
 - Optimistic placeholder IDs ('pending', 'temp_*', client-generated UUIDs) echoed back to the server in subsequent requests — server validates against its real ID format and rejects them as 400s. Trace from optimistic insertion → controls bound to the optimistic record (pin, promote, delete, follow-up) → outgoing request payloads. Disable controls until the server returns a real ID, OR omit the field from outgoing payloads when the local value still matches the optimistic shape
 - Client-side AbortController for an in-flight streaming/long-lived operation must abort when the owning UI context tears down OR navigates AWAY from THAT operation. When cleanup is keyed to a route param, navigation events emitted BY the in-flight stream itself (e.g., redirecting to a permalink after the server returns an id) trigger the cleanup and abort the very operation that caused the navigation. Track the streaming operation's identity in a ref and abort only when navigating away from THAT identity, not on every param change. Mirror by cancelling the stream reader (`reader.cancel()`) in `finally` and ignoring late events whose ID doesn't match the now-current operation
+- Cancellation completeness — a cancel UI must short-circuit ALL continuation paths, not just close the visible stream. Trace from the cancel handler through: (a) the `runOperation()` Promise — store the `reject` ref or use AbortController so the original Promise actually settles; (b) any `.then(...)` chained from a non-cancelable upstream POST — check a per-run token before opening downstream resources (EventSource, WebSocket, secondary fetch) so a late HTTP response can't spawn a new SSE connection after cancellation; (c) every UI flag set during start (`extracting`, `running`, spinner) — must reset regardless of which step cancellation interrupted. Otherwise late SSE/state updates fire for cancelled work, queues advance prematurely, and spinners get stuck on
+- User-initiated cancel signals propagating through subprocess close handlers must NOT surface as generic "error" — when a `/cancel` route sends SIGTERM and the child's `'close'` handler reports `Killed by signal SIGTERM` to clients via SSE/WebSocket as `{type: 'error'}`, the UI shows a confusing failure for a normal cancel. Trace from cancel route → `proc.kill()` → close handler → broadcast event: distinguish SIGTERM (deliberate cancel) from SIGKILL/non-zero exit (real failure) and emit a separate `cancelled` event type or status. Same applies to AbortController-driven server-side cancels
+- Client-side EventSource / WebSocket `onerror` handlers that only call `close()` without resetting render-state flags (`renderJobId`, `progress`, `isLoading`) leave the UI stuck in "in-progress" forever after a connection drop. Trace every long-lived stream attach → onerror handler → state reset; verify the handler clears every flag set when the stream opened and surfaces a user-visible toast/banner so the user knows to retry
+- Cancel + queue worker race: queue workers that mark the running item errored and immediately advance to the next pending job race the server's cancellation cleanup — a cancelled child takes SIGTERM→SIGKILL escalation seconds to actually exit, and the next job hits `409 BUSY` from the server's still-active singleton. Either (a) make the cancel call return only after the child's `'close'` event, OR (b) have the worker treat 409 BUSY as retry/backoff rather than a terminal error. Trace from cancel UI → cancel route → server-side child lifecycle → worker's "next item" trigger
 - Settings whose persistence model is per-record (per-conversation, per-document, per-project) held only in local component state — refresh resets to the persisted value while the server-side history shows different content. Trace: UI mode/setting state → outgoing payload → persistence schema → reload path. Persist on every mutation OR derive UI from the last-persisted record
 
-### Error Handling
-
-- Service functions throwing generic Error for client conditions — 500 instead of 400/404. Consistent access-control responses across endpoints. Concurrency failures → 409 not 500
-- Swallowed errors; generic messages replacing detail — including cross-layer error propagation: if the server returns structured error details (field-level validation messages, `details[]` arrays, error codes), the client layer should surface actionable detail rather than discarding structure for a generic string. External service wrappers returning null for all failures (collapsing config errors, auth, rate limits, 5xx into "not found")
-- Caller/callee disagreement: `{ success: false }` vs `.catch()`; gate returning `{ shouldRun: false }` on error vs fail-open runtime; argument shape mismatches (wrapped object vs bare array, wrong positional order); async EventEmitter handlers creating unhandled rejections
-- Destructive ops in retry/cleanup paths without own error handling
-- External service calls without configurable timeouts
-- Missing fallback for unavailable downstream services
-- SSE or streaming handlers that call `end()`/`close()` on mid-stream errors without emitting an error event — the client observes a clean stream termination and treats partial content as complete. Emit a structured `event: error` block before closing so clients can detect and surface the failure. Conversely, named lifecycle events (`error`, `done`, `complete`) must be MUTUALLY EXCLUSIVE — after emitting `error`, do NOT also emit `done`, or include explicit success/error info in the terminal frame. Trace every exit path of the stream generator and the route's loop body to verify only one terminal event fires
-- Streaming server handlers whose abort signal is wired into ONLY the final consumer (e.g., the LLM provider fetch) but not into upstream retrieval / embedding / subprocess work — disconnects don't actually stop the expensive earlier work. Trace the AbortSignal from `req.on('close')` through every async leg of the pipeline and verify each takes a `signal` parameter and propagates it
-- Raw `fetch()` failures (TypeError "Failed to fetch", DNS errors, ECONNREFUSED) at API client boundaries must be translated to a consistent message matching the project's established transport-error utility. Trace each new API client function against existing siblings (`apiCore.request`, `apiOpenClaw.streamMessage`) and verify the same wrapper is used; preserve `AbortError` so callers distinguish cancellation from failure
-- SSE or event dispatchers that handle named event types but ignore the protocol's default/unnamed event — SSE streams that emit `data:` without `event:` produce type `'message'` (the SSE default), which a handler processing only named types will silently discard. Verify the default event type is either handled or explicitly excluded
-- Route handlers that call a status/health probe before delegating to the main service when the service already handles the "not configured"/"unreachable" case — the pre-probe adds an extra upstream round-trip on every request and can fail even when the intended operation would succeed. Let the service be the authoritative source of truth and map its structured errors to the appropriate HTTP status at the route boundary
-
 ### Resource Management
 
 - Event listeners, sockets, subscriptions, timers, useEffect cleaned up on teardown
 - Delete/destroy leaving orphaned secondary resources (data dirs, branches, child records, temp files). Over-broad preservation guards preventing cleanup when nothing worth preserving (branch preserved with 0 commits ahead). Cleanup with implicit mutations (auto-merge, auto-commit) — abort on prerequisite failure
+- Delete/destroy/cleanup handlers that gate on a getter as an existence check (`getWork(id)` → `unlink(...)`, `loadConfig(id)` → `rm -rf`, `parseManifest()` → archive) propagate the getter's failure modes to the cleanup path — if the entity is in a corrupted/invalid state (parse error, schema mismatch, missing required field, transient FS read error), the getter throws and the entity becomes UNDELETABLE through the API/UI, leaving users with no recovery path. Trace from cleanup handler → existence check → underlying read/parse and verify: either catch known corruption error classes (`err.code === 'CORRUPTED_MANIFEST'`, `SyntaxError`, `SchemaValidationError`) and proceed with cleanup, OR use a lower-level existence check that doesn't require parsing (`fs.existsSync` for the directory, lock-file presence, rowid lookup without joins). Corrupted entities are exactly when users need to delete them most
 - Initialization functions without guard against multiple calls — creates duplicates
 - Self-rescheduling callbacks where error before re-registration permanently stops schedule — use try/finally
 - `requestAnimationFrame` handles not cancelled on component unmount — pending frames invoke DOM operations or state updates on unmounted nodes. Store the handle and cancel it in the `useEffect` cleanup
 - Large payloads (base64, binary buffers) stored in multiple state fields simultaneously (e.g., as both a `data` field and a `previewUrl` data URL) — each copy multiplies memory. Derive one representation from the other on demand (use `URL.createObjectURL()` for display, revoke on removal and unmount) rather than storing both
 - Blob/object URLs created via `URL.createObjectURL()` not revoked on both item removal AND component unmount — unmounting with pending items leaks all their URLs. Add a cleanup effect that revokes any remaining URLs on unmount
 - ReadableStream / fetch readers consumed in a loop without `try/finally` — an exception thrown inside the loop leaves the reader and underlying stream open. Wrap the read loop in `try/finally { reader.cancel() }`. The `finally` block should catch its own errors so it doesn't mask the original exception
-
-### Validation & Consistency
-
-- Breaking changes to public API without version bump or deprecation path
-- Backward-incompatible changes (renamed config keys, file formats, schemas, event payloads, routes, persisted data) without migration or fallback. Route renames need redirects
-- One-time migrations without completion guard — re-execute every startup
-- Data migrations silently changing runtime behavior — preserve execution semantics. Unsupported source values must be flagged, not defaulted
-- Update endpoints with field allowlists not covering new model fields
-- New endpoints not matching validation patterns of existing similar ones. The same field (id, name) accepted by multiple endpoints must be validated identically everywhere — path params, query, body, on sibling endpoints (create/update/delete/activate). Skipping param validation on one sibling turns violations into 404/500 instead of 400. `z.string().min(1)` without `.trim()` accepts whitespace-only names. API doc schemas must be structurally complete
-- Client-side input validation limits (max count, file size, string length, combined totals) must be consistent with — and ideally tighter than — server-side enforcement. When the client allows combinations the server rejects (e.g., 8 × 10MB files vs a 50MB JSON body limit), users hit confusing 400/413 errors. Trace all enforcement boundaries (UI, API schema, body parser, downstream service) and verify they form a coherent envelope
-- Sample config files, README examples, and documentation that reference config keys or structure must match what the implementation actually reads. Trace example keys against the config loader — stale examples teach operators to configure values the system ignores (or vice versa)
-- Subprocess invocations must inherit the same configuration source as the parent — if the parent reads from `.env`/config files but the child only sees `process.env`, exporting those values explicitly via the `env` option is required. Trace from config loader → invocation site → subprocess script. Otherwise a probe uses customized credentials/ports while the underlying setup runs with defaults, creating an "inconsistency loop" where the probe always fails and provisioning re-applies defaults that overwrite user customization
-- Config values whose format can be validated at initialization time (URLs, port numbers, auth schemes) but are only validated at first use — misconfiguration surfaces as a cryptic runtime error deep in the call stack. Validate format and range of security-relevant config values during initialization and surface a specific diagnostic identifying the bad field
-- URL joining utilities that force paths absolute-from-origin (stripping the base URL's pathname) — `baseUrl=http://host/proxy` + `/v1/api` silently produces `http://host/v1/api` instead of `http://host/proxy/v1/api`. Verify URL construction utilities preserve pathname segments from the base URL, or document and enforce that base URLs must be origin-only
-- Summary/aggregation endpoints using different filters/sources than detail views they link to
-- Discovery endpoints must validate against consumer's actual supported set. Identifier transformations between producer and consumer must preserve expected format
-- Validation functions introduced for a field: trace ALL write paths. New branches must apply same validation as siblings
-- Stored config merged with shallow spread — nested objects lose new default keys on upgrade. Use deep merge
-- Schema fields accepting values downstream can't handle. Validated params never consumed (dead API surface). `.partial()` on nested schemas: verify nested objects also partial. `.partial()` with `.default()` silently overwrites persisted values on update
-- Generator/validator structural invariant — when a generator produces values with structural guarantees (sortability via fixed-width prefix, embedded checksum, encoded version), the validator regex (and any client-side mirror) must enforce the SAME shape. Broader regexes accept inputs the generator never emits, breaking invariants the rest of the system relies on (e.g., lexical sort == chronological sort breaks once a base36 timestamp grows by a digit). Trace generator → server validator → client mirror as a closed loop. Test fixtures should use IDs/payloads that match generator output, not contrived literals
-- Schemas accepting paired range fields (`startDate`/`endDate`, `min`/`max`, `from`/`to`) without a cross-field refinement (`zod .refine()`) — accepts inconsistent ranges (start > end). Trace the schema definition, route validation, and downstream consumer to confirm the range relationship is enforced somewhere (preferably at the schema)
-- Required-at-use-time config values (model name, API key, endpoint URL, default selection) that may be null/undefined in the source data must be validated at the boundary before invoking the downstream API. Trace from config source → loading layer → use site, and verify nullable fields are guarded with a clear, actionable error before the downstream call. Otherwise the downstream API responds with an opaque error far from the user's intent
-- Multi-part UI gated on different prop subsets — derive single enablement boolean
-- Entity creation without case-insensitive uniqueness
-- Arrays of IDs (widget ids, tag ids, member ids) persisted, returned by API, or rendered with `key={x}` without container-level dedup — element-level validation (type, length) isn't enough. Enforce uniqueness via schema refinement (`zod.refine(arr => new Set(arr).size === arr.length)`), dedupe on ingest, AND dedupe during read-path sanitization so hand-edited / legacy data can't reintroduce collisions. Apply the same first-wins dedup to arrays of records keyed by id at the container level
-- Data loaded from files or persistent stores sanitized less strictly than the API accepts on write — hand-edited, migrated, or corrupted persisted state can introduce values (oversized names, non-kebab ids, duplicate entries) the API rejects on mutate, producing oversized responses, unreachable records, or invariant violations. Apply the same length caps, regex, uniqueness, and type guards in read-path sanitization as in request validation
-- Code reading response properties that don't exist — verify field names, nesting, actual response shape. Wrappers that don't request/forward needed fields. Call sites using wrong function variant for input format or wrong positional argument order
-- Data model fields with different names per write path. Entity identity keys inconsistent across lookup paths
-- Entity type changes without revalidating type-specific invariants and clearing old-type fields
-- Config flag invariants (A implies B) not enforced across all layers: UI toggles, API validation, server defaults, persistence
-- Operations scoped to entity subtype without verifying discriminator — wrong type corrupts state
-- Inconsistent "missing value" semantics (null vs empty string vs whitespace) across layers. Validation returning null when null means "clear" downstream. Normalization applied inconsistently between write and comparison paths
-- Validation delegating to runtime computation — conflating "no result in window" with "invalid input"
-- Numeric strings without NaN/type guards. Hand-rolled regex for well-known formats — use platform parsers
-- UI hidden from nav but accessible via direct URL
-- Summary counters missing edge cases; counters incremented before confirming state change; batch ops reporting success while logging per-item failures
+- Page/component-level unsubscribe from shared event streams — when a page hook (or per-route component) emits `unsubscribe` on a Socket.IO namespace / pub-sub channel / shared bus on cleanup, and the server's subscription model is per-socket (single Set, no ref-count), unmounting that page DROPS subscriptions other always-mounted consumers (Layout-level notifications, header counts, global toasts) still depend on. Trace every `subscribe` / `unsubscribe` emit and every `socket.off(event)` (without a handler) site to identify which channels are shared. Either avoid unsubscribing from shared namespaces in page-level hooks, OR introduce a ref-counted subscription manager so multiple components can attach/detach without stepping on each other
 
 ### Concurrency & Data Integrity
 
@@ -117,39 +73,14 @@ Apply the checklist as a prompt for attention, not an exhaustive specification.
 - Early returns for "no primary fields" skipping secondary operations
 - Shared flags/locks with exit paths that skip cleanup — permanent lock
 
-### Cross-File Deep Checks
-
-**Cross-file consistency**
-- New functions following existing patterns must match ALL aspects (validation, error codes, response shape, cleanup). Partial copying is #1 review feedback source
-- New API client functions must use same encoding/escaping as existing ones
-- New endpoints must be wired in all runtime adapters (serverless, framework routes, gateway)
-- New external service calls must use established mock/test infrastructure
-- New UI consumers against existing APIs: verify every field name, nesting, identifier, response envelope matches actual producer response
-- Discovery/catalog endpoints: trace enumerated set against consumer's supported inputs
-- Cross-module constants kept in sync by comment ("must stay in sync with X", duplicated regex, duplicated event name, duplicated size limit) — the comment is not enforcement and drift is a silent failure. Event names, regex patterns, numeric limits, path segments, and feature-flag keys shared across modules (client↔server, route↔service, component↔component, producer↔consumer) must be a single exported constant imported by both. Flag any instance where a comment notes "keep in sync" without the actual shared module
-- New global APIs (`AbortSignal.any`, `Promise.withResolvers`, `structuredClone`) used directly when the codebase already has a fallback utility for the same API — search for an existing wrapper (`fetchWithTimeout`, `withSignal`, polyfill helpers) before adding a new direct call. Drift between the safe path and a new direct call reintroduces the runtime error the fallback was created to avoid
-- Pure persistence/utility modules importing from orchestration/service modules just to access a constant pulls the entire downstream import graph as a transitive dependency. Trace each `import` in storage / utility files; if the imported symbol is a constant (enum, regex, size cap, valid-mode set), suggest moving it to a small dedicated shared module
-- Actions triggered from one surface (command palette, global menu, external event) that mutate data another already-mounted page/component fetched on mount — re-navigating to the same route doesn't remount (routers no-op it), so the visible state stays stale while the server updates. Propagate change via shared store, a pub/sub event whose name is a shared constant, focus/visibility refetch, or key-based remount — and verify the mounted page actually subscribes on its side
-- Modules that own a persistence schema (write to disk/DB with a known shape) should validate at the persistence boundary, not assume the API/route layer will catch everything. Trace from route validator → service call → persistence write — verify enum/range/required checks exist at the storage layer for fields the schema cares about. Direct callers (internal scripts, tests, programmatic batch jobs) bypass route validation otherwise
+### State/Lifecycle Deep Checks
 
 **Cleanup/teardown side effects**
 - Cleanup functions with implicit mutations (auto-merge, auto-commit, cascade writes) — verify abort on prerequisite failure
 
-**Specification conformance**
-- Parsers for well-known formats (cron, dates, URLs, semver): verify boundary handling matches spec — field ranges, normalization, step/range semantics
-
 **Temporal context**
 - Timezone-aware logic alongside non-timezone-aware in same flow — mixed contexts trigger on wrong day/hour
 
-**Boolean/type fidelity through serialization**
-- Boolean flags persisted to text (markdown metadata, query strings, flat files): trace write → storage → read → consumption. `"false"` is truthy — verify strict equality at all consumption sites
-
-**Cross-layer invariant enforcement**
-- Config flag invariants (A implies B): trace through UI toggles, form submission, route validation, server defaults, persistence round-trip
-
-**Error path completeness**
-- Each error reaches user with helpful message and correct HTTP status. Multi-step operations track per-item failures separately from overall success
-
 **Concurrency under user interaction**
 - Optimistic updates with async: second action while first in-flight — rollback/success handlers can clobber concurrent state or close over stale snapshots
 
@@ -171,86 +102,38 @@ Apply the checklist as a prompt for attention, not an exhaustive specification.
 **Paired lifecycle event completeness**
 - "Started" event → every exit path (success, error, early return, no-op branches for specific entity types) emits "completed"/"failed"
 
-**Entity identity key consistency**
-- Computed lookup keys (e.g., `e.id || e.externalId`): trace all paths using same computation — inconsistent keys cause mismatches
-
-**Intent vs implementation (cross-file)**
-- Cross-references between files (identifiers, param names, format conventions, versions, thresholds) that disagree — trace all references when one changes. Internal identifiers renamed when concept renamed
-- Modified values referenced in other files: trace all cross-references
-- Responsibility relocated from one module to another: trace all dependents at old location (guards, return values, state updates). Remove dead code at old location
-
 **Transactional write integrity**
 - Multi-item writes: condition expressions preventing stale-read races (TOCTOU). Update ops that silently create records for invalid IDs (DynamoDB UpdateItem, MongoDB upsert) — add existence conditions. Caught conditional failures → 409 not 500
 
-**Batch/paginated consumption**
-- Batch API callers handle partial results, continuation tokens, rate limits with backoff. Resource names account for environment prefixes
-- Periodic maintenance (cleanup, expiry, dedup) bolted onto a paginated read path runs only for items returned in that page — entries beyond the boundary are never processed. Trace from list endpoint → maintenance/sweep code → the iteration that bounds it. Move maintenance to a background sweep, run a separate unbounded pass, OR use cheap metadata (mtime, size) for the maintenance pass while only doing expensive reads for the page actually returned. Maintenance gates that depend on parsed metadata fields will skip records where parsing returns a sentinel (0, null, "") — those records become permanent
-
-**Deep-link URL contract (sender ↔ receiver)**
-- A URL with query parameters (`?id=...`, `?date=...`) or path segments is a contract: the receiving page/route MUST consume those parameters and use them to scroll/select/filter. Trace each new deep-link href to the destination route handler / page component and verify it reads and acts on every parameter the sender includes. If the receiver doesn't yet support the parameter, either drop it (and adjust docs/changelog claims) or wire it through end-to-end
-
-**Data model vs access pattern**
-- Claims of ordering ("recent", "top") verified against key/index design — random UUIDs require full scans
-
 **Deletion/lifecycle cleanup**
 - Delete functions: trace all lifecycle resources. State resets: clear individual contributing records — stale records block re-entry
 
-**Update schema depth**
-- Update schemas from create (`.partial()`): nested objects must also be partial
-
 **Mutation return value freshness**
 - Returned entity reflects post-mutation state. Force/trigger operations reset dependent scheduling state
 
 **Read-after-write consistency**
 - Writes then immediate scans/aggregations: check store's consistency model. Compute from in-memory state or use consistent-read options
 
-**Multi-source data aggregation**
-- Items from multiple sources: retain source identifier through aggregation for downstream routing
-
-**Field-set enumeration consistency**
-- Operations targeting field sets: trace every other enumeration (UI predicates, filters, docs, tests) — prefer single source of truth
-
-**Abstraction layer fidelity**
-- Wrappers requesting all fields handlers depend on — third-party APIs often require opt-in. Mutually exclusive params: strip conflicts. Framework function variants match input format. Positional args match called function's parameter order
-
-**Parameter consumption tracing**
-- Validated params: trace to actual consumption. Unread params create dead API surface — wire through or remove
-
-**Summary/aggregation consistency**
-- Dashboard counts vs detail views: same filters, ordering. Navigation links propagate aggregated context
-
-**Data model / status lifecycle**
-- Changed statuses/enums: sweep API docs, UI filters, conditional rendering, routes, tests. Renamed concepts: trace all manifestations (routes, components, variables, CSS, tests)
-
-**Type-discriminated entities**
-- Discriminator changes: trace all code paths (migration, bulk, UI type-switchers) — verify downstream branching handles all transitions
-
 **Migration idempotency**
-- Startup migrations: verify second run is no-op. Condition excludes already-migrated records
-
-**Data migration semantics**
-- Migrated fields preserve behavioral meaning. Concurrency protection for read-triggered migrations. Unsupported source values flagged not defaulted
+- Startup migrations: verify second run is no-op. Condition excludes already-migrated records. One-time migrations triggered on load/startup without a completion guard re-execute every startup
 
 **Dependent operation ordering**
 - Side effects only after primary operation confirms success. `Promise.all` grouping sequential deps. Resource allocation before gate operations (locks, validation)
 
-**Bulk vs single-item parity**
-- Single-item CRUD changes: trace corresponding bulk operation — verify same fields, validation, secondary data
-
 **Bulk selection lifecycle**
 - Selection cleared on data refresh/deletion. Not cleared but should be on filter/sort/page change. Re-validate at execution time after confirmation dialog
 
-**Config auto-upgrade provenance**
-- Auto-upgrade logic: distinguish user customization from previous default — without provenance, overwrites intentional customizations
+**Streaming abort signal threading**
+- Streaming server handlers whose abort signal is wired into ONLY the final consumer (e.g., the LLM provider fetch) but not into upstream retrieval / embedding / subprocess work — disconnects don't actually stop the expensive earlier work. Trace the AbortSignal from `req.on('close')` through every async leg of the pipeline and verify each takes a `signal` parameter and propagates it
 
-**Query key / stored key alignment**
-- Lookup key precision/encoding/format matching write path — mismatches return zero matches
+**Multi-provider operation enumeration**
+- When a system supports multiple providers/backends/sources for the same capability (image-gen local + codex, search backends, storage tiers), every dispatcher operation that fans out (cancel, list active, attach SSE, status probe, "current job") must enumerate ALL providers — not short-circuit on the first match. Trace from the dispatcher entry point through every provider import and verify each provider's variant of the operation is invoked. Common bug: `cancel()` calls `local.cancel()` and returns; codex jobs survive
 
-**Subprocess condition detection**
-- Subprocess output parsed to detect conditions: check both stdout and stderr plus exit code — location varies by tool version
+**Job ownership before clearing shared singleton state**
+- Finalize / cleanup handlers in single-active-job providers (`activeJob`, `activeProcess`, `currentSession`) must check the cleared reference still belongs to the job that owns the handler — otherwise a stale finalize from an older run wipes state belonging to a newer in-flight job. Pattern: `const isOwner = activeJob === job; if (isOwner) activeJob = null;`. The error path (spawn `'error'` before `'close'`) is the most common entry that bypasses the close handler's ownership check, so `finalizeError` is the most common offender
 
-**Formatting consistency**
-- New content matches file's existing indentation, bullets, headings, structure
+**Actions across mounted surfaces**
+- Actions triggered from one surface (command palette, global menu, external event) that mutate data another already-mounted page/component fetched on mount — re-navigating to the same route doesn't remount (routers no-op it), so the visible state stays stale while the server updates. Propagate change via shared store, a pub/sub event whose name is a shared constant, focus/visibility refetch, or key-based remount — and verify the mounted page actually subscribes on its side
 
 ## Output Format
 

package/lib/review-security-audit.md

@@ -24,9 +24,10 @@ For each changed file:
 
 ### Trust Boundaries & Data Exposure
 
-- API responses returning full objects with sensitive fields — destructure and omit across ALL paths (GET, PUT, POST, error, socket). Comments claiming data isn't exposed while the code does expose it
+- API responses returning full objects with sensitive fields — destructure and omit across ALL paths (GET, PUT, POST, error, socket). Comments claiming data isn't exposed while the code does expose it. This includes server-internal absolute filesystem paths (`/Users/.../data/loras/foo.safetensors`, `C:\app\data\models\bar`) returned in catalog/list endpoints — they leak server layout, OS, and install locations to any UI user and couple the client to filesystem structure. Return basenames or relative identifiers (`/data/loras/<filename>`) and resolve/validate server-side at consumption time. The same scrubbing applies to server-emitted log/status/progress lines forwarded to clients via SSE, WebSocket, or any push channel (`STATUS:Saved to /Users/me/data/...`, error tails, ffmpeg progress lines): trace each `log()`/`emit('status', ...)`/`stderr.write` whose output crosses the trust boundary and reduce paths to basenames (`os.path.basename`, `path.basename`) so server filesystem layout never leaks through the live channel. **Error messages** are a frequent leak source: `ServerError`, custom error classes, and thrown messages that interpolate filesystem paths (`new ServerError(\`Corrupted manifest at ${path}\`)`), connection strings, internal hostnames, environment variable values, or stack frames are surfaced verbatim by default error handlers — the path/detail belongs in the server log `context` field while the user-facing `message` should be path-free (`Corrupted manifest`, optionally with the entity ID). Audit every `throw new Error(\`... ${path/secret/host} ...\`)` and every error-response builder for infrastructure detail crossing the boundary
 - Server trusting client-provided computed/derived values (scores, totals, correctness flags, file metadata like MIME type and size) — strip and recompute server-side. Validate uploads via magic bytes and buffer length, not headers
 - Server trusting persisted-state flags (builtIn, protected, role, owner, immutable) read from flat-file/JSON/DB records to make authorization or deletion decisions — hand-editing the file or tampered sync can flip the flag and bypass protection. Derive authority on every read from a trusted source: a code-level constant set of built-in ids, session identity, or a server-side role lookup. The persisted representation can cache the flag for display, but must not be the source of truth for security decisions
+- Persisted-state filename/path fields (history JSON entries, settings.json paths, manifest entries) used as filesystem operands (`path.join(BASE, item.filename)` for `unlink`, `readFile`, `spawn` arg lists, ffmpeg/imagemagick concat manifests) without basename + path-resolve-prefix-check validation — corrupted, hand-edited, or tampered persisted state can include `../` segments that escape the intended directory and read/write/delete arbitrary files. Use a `safeUnder(base, candidate)` helper at every consumption site (delete, stitch, last-frame extract, batch ops, thumbnail). For paths that further pass into exec arg strings or manifest files (e.g., ffmpeg concat-demuxer `file '...'` lines), basename validation is necessary but not sufficient — the consumer's parser has its own escaping rules: single quotes / newlines break ffmpeg manifests, backslashes on Windows are interpreted as escape characters in quoted strings, shell metacharacters break shell-quoted args. Either reject filenames containing parser-special characters at validation time, or apply consumer-specific escaping (forward-slash normalization, quote escape, etc.) before writing the manifest/argv
 - New endpoints under restricted paths (admin, internal) missing authorization — compare with sibling endpoints for same access gate (role check, scope validation). New OAuth scopes must be checked comprehensively — a check testing only one scope misses newly added scopes
 - User-controlled objects merged via `Object.assign`/spread without sanitizing keys — `__proto__`, `constructor`, `prototype` enable prototype pollution. Use `Object.create(null)`, whitelist keys, use `hasOwnProperty` not `in`
 - Push events (WebSocket, SSE, pub/sub) emitted without scoping to originating user/session — sensitive payloads leak to all connected clients. Scope via room/channel isolation or server-side correlation ID
@@ -36,6 +37,7 @@ For each changed file:
 - Trimming values where whitespace is significant (API keys, tokens, passwords, base64) — only trim identifiers/names
 - Endpoints accepting unbounded arrays without upper limits — enforce max size. Validate element types/format, deduplicate to prevent inflated counts/repeated side effects. Internal operations fanning out unbounded parallel I/O risk EMFILE — use concurrency limiters
 - Security/sanitization functions handling only one input format when data arrives in multiple formats (JSON, shell env, URL-encoded, headers) — sensitive data leaks through unhandled format
+- Allowlists gating user-provided identifiers must use the consumer's identifier namespace, not a sibling namespace. Common bug: an allowlist of import-module names (`cv2`, `PIL`) used to gate `pip install <name>` — pip's identifier space is package specs (`opencv-python`, `pillow`), so the allowlist permits installs of typosquatted/unintended packages. Same risk for: command names vs aliases, OAuth scope strings vs role names, file extensions vs MIME types, language identifiers vs runtime identifiers. Build the allowlist from the consumer's actual valid-input set (`REQUIRED_PACKAGES.map(pipNameFor)`), NOT from a related-but-different list, and include a unit test that asserts every allowlist entry is a valid input to the consumer
 
 ### Hand-rolled Validators