Smithers Maintenance

---
name: smithers-maintenance
description: Work on Smithers workspace graph, generated documentation, benchmark or eval evidence, or durable flow authoring in this repository.
---

# Smithers maintenance

Use the owning source and current docs on the revision being changed. The source CLI (`makeCli()` in `packages/smithers/src/Cli.ts`) is the CLI syntax contract; the installed release can be stale. The 1.0 CLI separates target graph commands (`smthrs targets`, `show target`, `build|test|lint|docs|review|ci`) from durable flow commands (`smthrs flow list|plan|start`, `smthrs runs ...`). A flow start receipt does not prove completion; inspect its run and action receipts.

- **Graph or root files:** read [CONTRIBUTING.md](../../../CONTRIBUTING.md), especially root-file and target-index generation. `PACKAGE.ts` declares targets; generated companions and the whole declaration-set index have explicit checks. Use `pnpm run target-index` when that contract calls for regeneration.
- **Build/install/cache:** read [build](../../../packages/smithers/build/README.md), [workspace remote caching](../../../packages/smithers/build/docs/workspace/smithers-cloud-cache.md), and [cache trust](../../../packages/smithers/build/infra/CACHE-TRUST.md). The install flow currently supports pnpm only; Bun can still run target tools. Install actions use expected filesystem boundaries and do not enter the shared engine cache. The target `/ac` cache differs from engine step-cache/artifacts; hosted and self-hosted cache implementations need matching route, bound, and credential behavior.
- **Documentation:** Author library documentation in each package's `docs/` directory; it ships with the npm package. Run `pnpm docs:check` to verify tarball contents. Main-site projections use `pnpm --filter @smithers/site run sync:docs`.
- **Benchmarks or performance claims:** read [scripts/bench/README.md](../../../scripts/bench/README.md). Distinguish the deterministic PR gate from scheduled observed timings, review candidate baselines, and retain methods and limitations with any claim.
- **Evals:** read the owning suite's README, including [agent](../../../evals/agent/README.md) and [seeded review](../../../evals/review-seeded-bugs/README.md). Keep offline deterministic gates and deliberate baseline updates separate from live model measurements and spending.
- **Flows:** read [@smthrs/flow](../../../packages/smithers/flows/flow/README.md) and [CLI reference](../../../packages/smithers/docs/reference/cli/README.md). A file flow at `flows/<name>/flow.ts` default-exports a tagged `Flow.make` from `@smthrs/flow`. Export its action implementations as the optional named `layer` (`Declared.toLayer`, `AgentAction.layer`, or `Layer.mergeAll`); the registry composes it against the local host platform and agent services. Export implementations directly; the host owns `Action.Implementations`. Acquire extra dependencies during layer construction so missing services are refused at load. Use stable `Node.capture` callbacks for canonical persisted composition and matching `implementationVersion` declarations/registrations for sealed idempotent actions. New authoring uses Effect Schema, not retired JSX/Zod task examples. A decision inside a flow (classify, filter, rank, route, yes/no over items) asks Jev through `Classifier.make` and the host `Evaluator`, as one request with one question per item, never through an LLM seat; see [jev-check](../../../flows/coding/jev-check.ts).
- **Plans:** read [plan](../../../packages/smithers/flows/plan/README.md) and [plan-store](../../../packages/smithers/flows/plan-store/README.md). Node payloads are persisted as plaintext in `node_json` and approval cards without redaction; keep credentials out and resolve them at dispatch. Persisted plans are verified on write and read, and append uses an immutable-history compare-and-swap over the approved base and running prefix.
- **Generated or untrusted flow declarations:** read [core planning rules](../../../packages/smithers/flows/core/README.md). `Graph.build` executes bodies and planning callbacks with the caller's process authority; capability/effect metadata does not sandbox that code. Translate validated data into nodes with trusted code, or plan untrusted code in an externally isolated process.
- **Runtime or persistence:** read [flows runtime](../../../packages/smithers/flows/README.md), [engine](../../../packages/smithers/flows/engine/README.md), and [engine-store](../../../packages/smithers/flows/engine-store/README.md). `@smthrs/flow` declares behavior, the engine makes decisions, and the storage seam changes where state lives. Node and Bun use distinct native host/SQL adapters over the same SQLite migrations, journal, stores, cache, and recovery. Run migrations before SQL-backed services and use one writer for journal/state transitions; demonstrate cross-runtime recovery and cancellation. Browser bundling alone does not establish durable browser execution.
- **Journal and ownership fencing:** read [journal](../../../packages/smithers/flows/journal/README.md) and [run-store](../../../packages/smithers/flows/run-store/README.md). Ownership is arbitrated by the journal's injectable `Consensus` strategy (`SqlConsensus` over `flows_consensus_leases` by default, `Consensus.layerLocal` in-process); fenced durable emissions join its `guard`, so the run must be claimed and activated through it, and the journal and run store must share one strategy instance. `RunStore` mirrors the outcome on `flows_runs`, so a fixture that forges ownership in SQL writes both. `emitDurableUnfenced` is only for genuinely ownerless admission or repair, never a bypass for `fence_lost`. An expired lease alone does not authorize takeover; `LivenessEvidence` must be current, and an unknown probe counts as alive.
- **Step cache migrations:** read [step-cache](../../../packages/smithers/flows/step-cache/README.md). The earlier 1.0 RC migration 2002 identity is accepted explicitly; preserve its ledger and cached results during upgrade. An unknown migration identity remains a failure, not a reason to delete a runtime database.
- **Time travel:** read [time-travel](../../../packages/smithers/flows/time-travel/README.md) before changing fork, rewind, or their receipts. A durable fork reuses completed prefix attempts by their original action identities and gives new work child-scoped keys; rewind archives future waits and refuses crossed irreversible effects or live descendants. Test recovery after an interrupted mutation.
- **Sync:** read [sync](../../../packages/smithers/flows/sync/README.md) before changing cursors, subscriptions, or gateway mounts. Persist applied cursor progress with consumer state; change feeds are hints and a re-list is authoritative. Preserve rewind generation handling: `lineage_changed` requires rebuilding the projection. Branch RPC code is not currently mounted by the gateway.
- **Artifacts:** read [artifact storage](../../../packages/smithers/flows/artifacts/README.md). Its filesystem backend needs trusted host filesystem semantics; kernel-guarded filesystem access cannot substitute for them. Treat deletion as explicit and keep engine-store responsible for liveness/reachability.
- **Browser host:** read [platform-browser](../../../packages/smithers/flows/platform-browser/README.md). Its bash, filesystem, and jj views must share one volume; the tab uses the memory engine, and reload durability depends on the mount's `sync()`. Do not infer browser durability from a successful build or import.
- **Bun host:** read [platform-bun](../../../packages/smithers/flows/platform-bun/README.md) before changing its filesystem or process adapters. Its trusted filesystem boundary runs the native `smithers-jj-export` helper (build with `cargo build --locked --release -p smithers-ffi --bin smithers-jj-export` or set an absolute `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY`); `PATH` is never searched. Bun's host bundle is not the browser adapter.
- **Node host:** read [platform-node](../../../packages/smithers/flows/platform-node/README.md) before changing containment or process recovery. Confined operations require the `smithers-jj-export` helper built with the Rust toolchain `rust-toolchain.toml` pins; a missing helper refuses them. `ProcessLedger.layerMemory` cannot recover escaped children after a host crash, and permission checks belong around the host service bundle.

For TUI changes, read [apps/tui/AGENTS.md](../../../apps/tui/AGENTS.md) and its linked README. For app/server work, use their scoped `AGENTS.md` files. Treat issue state and wiki freshness as separate receipts from code status.

- **Bootstrap landing helper:** every authorized `pnpm commit --push` invocation must pass repeatable `--test "<command>"` flags. Commands run before VCS mutation with Bash pipefail. For an explicit exception, use `--no-test "<reason>"`; the helper records `Landing-Tests` in the commit. Require exit zero and `LANDED <sha>`, emitted only after fetching remote main and verifying ancestry. Push output alone is not a landing receipt.