smithers-orchestrator integration: 0.6.0 patch silently skipped on 0.9.1, supervisor never reports done, tracked runtime DBs, and doc drift

[roninjin10]

Hi cairo-coder team 👋 — smithers maintainer here. We read your takopi-smithers embedding closely (.smithers/workflow.tsx + TAKOPI_SMITHERS.md) — the plan → implement → review → fix Ralph loop over the schema registry is exactly how we hoped createSmithers would get used. A few things around it have gone stale; smallest-effort-first, and we're happy to send PRs for any of it.

1 · Delete after one bump — already fixed upstream

Your patch is keyed to smithers-orchestrator@0.6.0, but the dependency is ^0.9.0, which resolves to 0.9.1 — so the patch stopped applying at that bump. Both hunks have since landed upstream:

Patch hunk	Fixed upstream	Action
strip CLAUDE* env vars so child agents don't detect a nested session and exit code 0	ClaudeCodeAgent clears CLAUDE_CODE_ENTRYPOINT/CLAUDECODE since v0.16.0 → ClaudeCodeAgent.js@v0.16.0#L98	bump to 0.31.0; delete patches/ + patchedDependencies
zod-to-json-schema → Zod v4 native toJSONSchema()	upstream converts natively → zodToOpenAISchema.js@v0.31.0#L23	comes free with the same bump

⚠️ Until the bump, the nested-session protection the patch was written for is silently off — a run launched from inside a Claude Code session can have its planner/reviewer agents exit immediately with code 0, the exact failure your patch comment describes.

Also unlocked by the bump: the six explicit outputSchema props (workflow.tsx#L143-L227) become redundant — createSmithers's Task resolves the schema registry and injects the schema itself (create.js@v0.31.0#L264, taskCore.js#L263). Your comment at #L27-L28 already promises this — but 0.9.1 doesn't do it yet, so the props are load-bearing today and deletable after.

2 · Bugs in your integration

• supervisor.status can never reach "done" — the 30 s heartbeat interval (workflow.tsx#L62-L69) is never cleared or .unref()'d, so the event loop never drains and the beforeExit handler (#L71-L76) is unreachable (the process can't exit on its own either). Takopi sees a fresh heartbeat + "running" forever, even for finished runs. .unref() the timer and write the done-state from an explicit completion path.
• Runtime state is committed — .smithers/workflow.db, -shm, a ~400 KB -wal, and .takopi-smithers/supervisor.pid are all tracked. .gitignore#L56 only matches smithers.db*, but the workflow puts the store at .smithers/workflow.db (#L38). git rm --cached + widen the pattern.
• Docs steer agents into walls — and since this whole loop is agent-driven, these docs are load-bearing:
  • TAKOPI_SMITHERS.md#L20-L26 tells the supervisor to resume via db.execution.findIncomplete() — that API has never existed in smithers-orchestrator — and links smithers.sh/guides/mcp-integration, which 404s. Point agents at smithers.sh/llms-full.txt instead.
  • CLAUDE.md#L194-L195, AGENTS.md#L7-L8, and TAKOPI_SMITHERS.md#L14 all reference .takopi-smithers/config.toml, which isn't in the repo. Commit an example or drop the references.
• Dependency hygiene (hardening note) — the takopi-smithers pin (bun.lock#L323) declares smithers: ^0.5.4 — the unrelated legacy npm package of that name (#L309), which drags in EOL axios@0.21.4 — plus smithers-orchestrator: ^0.5.0, so the lockfile carries a second engine copy at 0.5.0 (#L357) beside your 0.9.1. We maintain takopi-smithers too; we'll drop the stray dep and lift the pin upstream — your side is then just bumping the github:evmts/takopi-smithers ref.

3 · Upstream fixes in flight on smithers

Upstream issue	What it unblocks here
smithersai/smithers#1417 — embeddable engine: drop the hard bun:sqlite requirement	a public surface for the supervisor state table (workflow.tsx#L44-L55) instead of (db as any).$client raw SQLite. That escape hatch is private API and bun:sqlite-only — createSmithers is the synchronous SQLite backend and fails loud under PGlite/Postgres, where there's no $client to .exec()

4 · Suggested fixes on your side (proposed sub-issues)

• bump smithers-orchestrator ^0.9.0 → 0.31.0, delete the dead patch — restores the nested-session fix you already wrote (§1)
• drop the six redundant outputSchema props after the bump (workflow.tsx#L143-L227)
• make supervisor.status = "done" reachable — .unref() the heartbeat + explicit completion write (§2)
• git rm --cached the runtime files and widen .gitignore#L56 to cover .smithers/workflow.db* + .takopi-smithers/supervisor.pid
• docs pass — real resume API, live links, config.toml committed or de-referenced (§2)
• portable supervisor state — replace the raw $client SQL once smithersai/smithers#1417 lands (we'll ping this issue when it does)
• bump the takopi-smithers ref once we land the pin fixes upstream (§2)

---

Compiled against cairo-coder@ff50521, with every claim verified against smithers v0.9.1, v0.16.0, and v0.31.0 source. If it's useful we'd start with the bump + patch deletion — that one is silently biting today.