fix(council): share review's engine config, and ship an entry point that runs

[eliahilse]

The council package was built next to kyora review and handed the same engine pool, but none of the discipline around it. This fixes what fell out of that.

I also convened the council on itself for this — claude, glm and qwen each read packages/council/mcp/src/ cold and led with the same two problems (misplaced/forged config, and the background-job layer). Their takes shaped what's here.

Entry points don't run

Two bins (kyora-council, kyora-stakes-hook) meant no runner could pick one:

$ npx @kyora-sh/council
npm error could not determine executable to run

and bunx resolves a multi-bin scoped package to the first bin — so the documented hook command

{ "type": "command", "command": "bunx @kyora-sh/council kyora-stakes-hook" }

started an MCP stdio server with kyora-stakes-hook as an argument. The server holds stdin open, so the hook hung on every matching Write/Edit/Bash until it timed out. (Both verified against a two-bin probe package.)

One bin now dispatches by subcommand — kyora-council hook, kyora-council [serve] — and the MCP server moves to server.ts behind startServer(), leaving index.ts as the entry point.

The council could never honor a config

council.ts forged a whole ReviewConfig — base, failOn, maxDiffBytes, maxFindingsPerEngine and five more fields meaningless to a council — purely to satisfy runEngineRaw's signature, and hardcoded overrides: {} while doing it. Every engineStatus(engine, undefined) call was the same thing again.

So this, from the README, was true for review and quietly false for the council:

a vendor CLI changing its flags is a config edit, not a code change

• runEngineRaw now takes a narrow RunConfig { timeoutMs, cooldownMinutes, overrides }, which ReviewConfig extends. Nothing to forge.
• The council reads the same kyora-review.config.json as review, resolved per checkout and cached. Config loading moved to a shared config.ts rather than being copied.
• argsFor fixes inverted precedence: a configured args override was silently discarded whenever the engine defined its own argsWrite/argsChat, so an override worked in review and was ignored in council. EngineOverride gains argsWrite/argsChat, making the council's own invocations overridable at all.

Background jobs could collide and strand

• Ids were Date.now() in base36 — two jobs starting in the same millisecond shared a filename, and the first result overwrote the second's record. Ids now carry a sequence.
• A job had no deadline. If the server was restarted mid-run, nothing ever moved the record off running and council_result reported "still running (48231s so far)" forever. A job past its deadline now reads back as failed, with a reason.

Two smaller correctness fixes

• council_convene_async seated the council twice over live quota — once to report engines, once to run them — so the engines it named were not guaranteed to be the ones that ran. Seating is now a separate step from asking.
• agent_fanout with write: true ran N write-capable CLIs against one working tree concurrently, with nothing enforcing the "disjoint files" its schema asked for. Write fanouts run in turn until each task can get its own checkout; read-only fanouts stay parallel.

Repo config

.mcp.json pointed at npx -y kyora-sh, which 404s on npm — the server never started for anyone who cloned this. It points at the published @kyora-sh/mcp now, and adds the council so the repo dogfoods it. The council package was also missing from the README's repo layout entirely.

Not in this PR

Two of the three council members argued the engine pool + usage/cooldown layer should be extracted into its own package, with review and council as peers on top of it, instead of council reaching into review's src/ through raw-TypeScript subpath exports. I think they're right, but it's a package move and a publish-surface change — worth doing deliberately rather than folded in here. The narrow RunConfig is the part that makes the current arrangement honest in the meantime.

Verification

bun run check-types, bun run test (57 pass, 0 fail), bun run build all green. New tests cover argsFor precedence, deadline reconciliation, id uniqueness, and the council picking up kyora-review.config.json overrides. The built binary was exercised on all three paths: tools/list over stdio, hook with a real payload, and an unknown subcommand exiting 2.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DtUdeCx22CrTpMMA698SFo