@crouton-kit/crouter 0.3.21 → 0.3.23

package/dist/builtin-skills/skills/development/SKILL.md

@@ -1,109 +0,0 @@
----
-name: development
-type: playbook
-description: Use when shaping or reshaping a build roadmap — choosing a development style, selecting a phase skeleton, or setting exit criteria for a software goal.
----
-
-# Development Playbook
-
-## Development Styles
-
-Pick one style as your primary frame before you write phases. Each fits a different risk/knowledge profile.
-
-**Vertical slice.** Start with the thinnest path end-to-end — one real request touching every layer — before thickening any of them. Use when the integration seams are the riskiest unknowns and a working skeleton keeps the team aligned on "done". Fits new features where you know what to build but not how the layers will talk.
-
-**Spike-then-harden.** Build a throwaway prototype of the one thing you don't understand, validate the approach, then discard it and build it properly. Use when there is a genuine technical unknown (unfamiliar API, unclear performance profile, novel algorithm) that blocks everything else. The spike is not the deliverable — the hardened version is.
-
-**Test-first.** Write the failing test before the implementation for every unit of logic. Use when the requirements are precise and stable (a parser, a data transform, a well-specified algorithm). Do not apply to exploratory or UI-heavy work where the spec is discovered by building.
-
-**Strangler-fig.** Introduce a new implementation path alongside the old one, route traffic to it incrementally, and delete the old path when migration is complete. Use for migrations and rewrites where you cannot replace atomically and must maintain a working system throughout.
-
-**Bottom-up.** Build foundational primitives first; compose them into higher-order behaviour last. Use when building a library or shared infrastructure where the interface must be right before consumers are written. Risky if the top-level requirements aren't settled — you may build the wrong primitives.
-
-**Decision rule:** if the riskiest unknown is technical feasibility, spike first. If it is integration correctness, vertical slice. If requirements are precise and logic-heavy, test-first. If it is a live-system migration, strangler-fig. If it is a foundational library with settled requirements, bottom-up. Default to vertical slice for ambiguous new feature work.
-
----
-
-## Roadmap Shapes by Scenario
-
-These are concrete phase skeletons. Adapt names and granularity; don't add phases that serve no exit criterion.
-
-### New feature
-1. **Explore** — map the affected subsystems, identify entry points and constraints, produce `context/explore.md`.
-2. **Spec** — define the interface, behaviour, and acceptance criteria; output `context/spec.md`.
-3. **Plan** — decompose spec into file-level tasks with dependency order; output `context/plan.md`.
-4. **Vertical slice** — implement the thinnest end-to-end path; validate it works before widening.
-5. **Harden** — fill out the remaining logic, edge cases, error paths.
-6. **Review** — non-implementer critique pass on the whole surface.
-7. **Fix** — action review findings.
-8. **Validate** — end-to-end confirmation against spec's acceptance criteria.
-
-### Refactor
-1. **Characterise** — write or identify tests that describe current behaviour; they must pass before and after.
-2. **Plan safe steps** — decompose into the smallest semantics-preserving transformations; each step independently reviewable.
-3. **Transform** — apply each step, running the characterisation suite after each one.
-4. **Verify equivalence** — confirm no observable behaviour changed; review for unintended scope drift.
-
-### Bug-fix campaign
-1. **Reproduce** — produce a reliable reproduction case for each bug; nothing proceeds without one.
-2. **Root cause** — trace the defect to its source; group bugs sharing a root cause.
-3. **Fix** — implement the minimal correct change; no opportunistic cleanups in the same commit.
-4. **Regression test** — add a test that would have caught this.
-5. **Validate** — confirm the reproduction case no longer triggers.
-
-### Greenfield
-1. **Explore/research** — understand the problem domain, constraints, and comparable systems.
-2. **Spec** — define the interface and top-level behaviour in enough detail to plan.
-3. **Architecture decision** — commit to the structural shape; record in `context/architecture.md`.
-4. **Spike** (if technical unknowns exist) — validate the risky piece before building around it.
-5. **Bottom-up build** — primitives first, then composition; validate each layer before building on it.
-6. **Integration** — assemble layers; validate end-to-end.
-7. **Review + fix** — critique full surface; action findings.
-
-### Migration / upgrade
-1. **Inventory** — enumerate every call site, every affected API, every integration point.
-2. **Compatibility plan** — decide the strangler-fig boundary; define the coexistence period.
-3. **New path** — implement the replacement without removing the old.
-4. **Route incrementally** — shift traffic or call sites in small batches; validate after each batch.
-5. **Delete old path** — only after full migration is confirmed.
-6. **Validate** — confirm nothing regressed; run the full integration surface.
-
-### Performance work
-1. **Baseline** — measure and record current performance numbers; define the target.
-2. **Profile** — identify the actual bottleneck; do not optimise before you know where the heat is.
-3. **Fix the bottleneck** — targeted change only; no speculative optimisation.
-4. **Measure again** — confirm the target is met against the same baseline method.
-5. **Review** — check that the fix doesn't introduce correctness or maintainability regressions.
-
----
-
-## Setting Exit Criteria per Phase
-
-Every phase needs a concrete, evaluable condition that tells you it is genuinely done — not "looks good" or "mostly working". Write exit criteria when you write the phase, not after.
-
-- **Explore:** a context doc exists that accurately describes the relevant subsystem; a reviewer or subsequent spec agent should not need to re-explore to write the spec.
-- **Spec:** acceptance criteria are concrete enough that an implementer can derive test cases from them without ambiguity.
-- **Plan:** every task maps to identified files; no task says "figure out how"; dependencies are explicit.
-- **Implementation:** the code compiles, all existing tests pass, and the acceptance criteria from the spec are provably met (by tests or by a validation agent's manual check).
-- **Review:** a non-implementer has read the diff and produced a report; all Major and Critical findings are addressed.
-- **Validation:** end-to-end confirmation against the spec's acceptance criteria passes in the real runtime, not just in isolation.
-
-If you cannot write a concrete exit criterion for a phase, the phase is underspecified — split it or spec it further before adding it to the roadmap.
-
----
-
-## The Build-Cycle Discipline
-
-This is the delegation pipeline from spec to shipped, with the coupling that makes it rigorous.
-
-**Spec → Plan.** The plan agent receives the spec as input; it does not re-derive requirements. If the spec is ambiguous, the plan agent reports the ambiguity — the orchestrator resolves it and re-delegates, not the plan agent by guessing.
-
-**Plan → Implement (parallel where safe).** Tasks with disjoint file sets run concurrently. Before spawning parallel implementers, verify file-level independence; if two tasks touch the same file, serialize them. Every implementation agent receives: the goal in one sentence, its specific task and done condition, the relevant context files by path, and the e2e validation recipe.
-
-**Implement → Review (non-implementer).** The reviewer receives the full diff and the relevant context docs. It produces a report sorted by severity — Critical, Major, Minor — and does not propose fixes inline. One review pass per implementation batch; do not re-review after fixes, validate instead.
-
-**Review → Fix.** The orchestrator triages the report, skips false positives, and delegates fix agents pointing at the report path. Fix agents read the findings, understand the code, and implement the correct fix — they are not given line-by-line instructions. Do not spawn a second reviewer after fixes land.
-
-**Fix → Validate.** Validation confirms the thing works end-to-end in the real runtime. It is distinct from tests passing — it exercises the integrated system. If validation fails, spawn fix agents against the failure, re-validate. Do not advance to the next phase until validation passes.
-
-**When review or validation exposes a phase gap** — a wrong assumption in the spec, a plan that missed a dependency, an implementation that reveals the design is wrong — re-delegate the affected phase rather than patching forward. A corrected spec or plan paid for in one extra wake costs less than an implementation built on a bad foundation.

package/dist/builtin-skills/skills/planning/SKILL.md

@@ -1,59 +0,0 @@
----
-name: planning
-type: playbook
-description: Use when shaping a planning roadmap, deciding plan structure, or fanning out plan-review specialists before declaring a plan ready.
----
-
-# Planning Playbook
-
-## Plan Shapes and the Decomposition Decision
-
-Every planning effort produces either a flat plan or a decomposed plan (index + part-plans). Choosing the wrong shape wastes a cycle — a flat plan that is too large forces an implementer to hold too much at once; a decomposed plan for something small adds overhead for no gain.
-
-**Use a flat plan** when the work is a single coherent domain, involves fewer than ~6 files, and can be written at consistent task granularity without exceeding roughly 150–200 lines. A flat plan has an overview, ordered phases, and a verification section. No sub-plans. One file.
-
-**Use a decomposed plan** when the change spans multiple domains (e.g., data layer, API surface, UI), involves 6+ files, or would require a master plan that cannot be written at consistent granularity without ballooning. In this case: produce an index plan (the navigable master) and delegate each domain slice to a `plan`-kind child node, giving each child its slice scope, the relevant portion of the spec, and its place in the dependency graph. A slice that itself decomposes further — multiple sub-domains, more than one window's worth of planning — goes to a `plan` sub-orchestrator created directly (`crtr node new --kind plan --mode orchestrator`), not a base child relied on to promote itself. The index plan is the synthesis artifact — it lists all sub-plans by path, defines phases and their dependencies, and contains a task table the implementation orchestrator can execute directly. Detail lives in sub-plans; the master is not allowed to carry it.
-
-**The decomposition trigger is domain boundary, not size alone.** Three backend files and three frontend files are two domains even if the total count is modest — plan them separately and synthesize, because the integration seam is where bugs live and one agent reading both halves won't catch them as cleanly as two agents each going deep.
-
-After collecting part-plans from children, synthesize before declaring done: resolve file ownership conflicts (two sub-plans naming the same file means you decide the sequence), align naming across all parts, fill integration gaps at domain boundaries, and ensure the task table in the index accurately reflects dependencies exposed only by reading all sub-plans together.
-
-## What a Good Task Looks Like
-
-A task is the atomic unit a single implementation node picks up and executes in one context window. Write tasks so that any implementation agent can pick one up cold and know exactly what to do.
-
-A good task has: a file path (or a small list of paths it exclusively owns), an explicit statement of what changes in that file, a list of its hard dependencies (which other tasks must land first), and a clear output — what type, what function signature, what export the next task can assume exists. If a task requires a type defined by a sibling task in the same phase, that dependency is explicit in the task row.
-
-A good task is **parallel-safe**: its files are not owned by another task in the same phase. If two tasks must touch the same file, serialize them across phases and say so. A task that shares files without serialization is a merge conflict waiting to happen.
-
-A good task is **bounded**: an implementation agent should be able to finish it in one context window without needing to re-read the entire plan. If a task description runs longer than a short paragraph, the task is too large — split it.
-
-## Plan-Review Specialist Roster
-
-Before declaring any plan ready for implementation, fan out the following reviewers as `review`-kind child nodes in parallel. Each reviewer checks one lens; running them together catches what no single pass can. Do not proceed to the implementation phase until all reviewer findings are folded back in — deferred findings become implementation bugs.
-
-### Requirements Coverage
-**What it checks:** Every requirement and design constraint maps to a concrete plan task; nothing is invented; nothing is missed. Specifically: API routes, data model fields, UI states (loading, empty, error), error handling, and edge cases called out in the spec all have explicit plan tasks.
-**Spawn task template:** "Review the plan at `<path>` against requirements `<req-path>` and design `<design-path>`. Check that every requirement and design constraint has a concrete, actionable plan section. Classify each as Covered / Partial / Missing. Flag blocking gaps only."
-
-### Pattern Consistency
-**What it checks:** The plan honours the codebase's established architecture, module structure, naming conventions, error-handling utilities, API response shapes, and frontend patterns. Deviations that would confuse an implementer or create inconsistency are flagged.
-**Spawn task template:** "Review the plan at `<path>` for pattern consistency against the codebase. Check architecture conventions, naming, error handling, API shapes, and frontend patterns. Read source files in the areas the plan touches; do not review in isolation. Flag deviations that contradict established patterns."
-
-### Code Smells / Design
-**What it checks:** Nullability mismatches between plan and data source, type conflicts across sub-plans, hidden N+1 queries, over-fetching, missing error boundaries in batch operations, leaky abstractions that couple unrelated concerns, file-ownership conflicts when multiple sub-plans name the same file.
-**Spawn task template:** "Review the plan at `<path>` for design problems: nullability mismatches, N+1 queries, type conflicts between parts, over-fetching, missing error boundaries, leaky abstractions. Read existing code in target areas. Report concrete issues only — no style or speculation."
-
-### Security
-**What it checks:** Input validation gaps (missing length limits, type constraints, enum checks), injection surfaces (raw SQL, shell, path traversal), missing auth/authz guards, data exposure in planned responses, and race conditions or TOCTOU bugs in planned state mutations. Only flags risks with a concrete exploit path in the plan.
-**Spawn task template:** "Review the plan at `<path>` for security risks. Check input validation, injection surfaces, auth/authz coverage, data exposure, and race conditions. Only flag risks with a concrete exploit path — no theoretical concerns."
-
-### Architecture Fit
-**What it checks:** The plan's proposed boundaries — new files, new modules, new abstractions — fit the system's existing decomposition. A new service that duplicates an existing one, a new abstraction layer that cuts across established boundaries, or a module proposed in the wrong layer are all findings.
-**Spawn task template:** "Review the plan at `<path>` for architecture fit against the existing system. Check whether proposed file locations, module boundaries, and abstractions align with how the codebase is currently decomposed. Flag new units that duplicate existing ones or violate established layer boundaries."
-
-## Folding Findings Back In
-
-After all reviewers report, collect their findings, triage by severity, and revise the plan before advancing. Critical and High findings must be resolved — either fix the plan or document in the task that the implementer must handle a specific constraint. Medium findings are addressed where straightforward; explicitly carried as a note in the relevant task when they are implementation-time concerns rather than plan-shape concerns. Do not dismiss findings without a reason.
-
-A plan that passes all five lenses with no unresolved Critical or High findings is ready to hand to an implementation orchestrator.

package/dist/builtin-skills/skills/spec/SKILL.md

@@ -1,83 +0,0 @@
----
-name: spec
-type: playbook
-description: Use when running a specification effort, shaping a spec roadmap, or deciding how to stage design and requirements work. Covers the three-stage shape→design→requirements methodology, when to delegate design to a child node, the isolation principle behind the design/requirements split, and what a finished spec contains.
----
-
-## The Three Stages
-
-A specification effort runs in exactly this order: **SHAPE** → **DESIGN** → **REQUIREMENTS**. Do not collapse them, skip ahead, or run them in parallel. Each stage has a gate; the next stage starts only when that gate is met.
-
-### Stage 1 — Shape
-
-Shape is the only stage that is genuinely interactive. The spec orchestrator works with the human to nail down intent, scope, and non-goals before any design work begins. The deliverable is not an artifact — it is a shared mental model sufficient to write a sharp design brief.
-
-Run an inquiry loop: name the most important ambiguity, form a provisional take, offer 2–4 concrete options, get a decision. Track these turns carefully. The shape stage is done when: (1) 3–7 named components or functional areas are identified, (2) the user's intent can be restated without correction, and (3) no unresolved contradictions remain between the user's goal and the existing codebase. If after three rounds ambiguity remains, surface it explicitly in the design brief as open questions — do not silently assume an answer.
-
-Gate: human confirms readiness to proceed to design.
-
-### Stage 2 — Design
-
-Design produces the blueprint: components and their topology, end-to-end flows, files and directories affected, locked decisions, and open questions resolved. The altitude is infra/services — no function signatures, no algorithm descriptions, no implementation ordering. Design answers "what shape does this take?" — planning answers "how is it built?"
-
-Small or simple design work (one surface, clear scope, few components) can be done by a single `design`-kind child node. Large or complex design work — multi-surface features, multiple interacting subsystems, significant architectural choices — must be delegated to a **design orchestrator** (a `design`-kind node created directly with `--mode orchestrator`), which decomposes the design internally and returns a finished artifact. The trigger for spawning a design orchestrator rather than a base design node: if the design effort has more than one distinct phase or more than ~5 interacting components, use an orchestrator.
-
-Gate: human approves the rendered design artifact.
-
-### Stage 3 — Requirements
-
-Requirements are derived from the finished, approved design. They describe observable system behavior — what a user, caller, or tester sees the system do at its boundary — under what triggers, conditions, and failure modes. Each requirement is written in EARS format (WHEN/WHILE/IF/WHERE + SHALL). Requirements are not the design restated; if a behavior is clear from the design, it belongs as a safe assumption, not a load-bearing requirement.
-
-Delegate requirements writing to a terminal `spec` agent (base lifecycle). Pass it the rendered design text only. Do not include the design conversation, user goals, or your own reasoning — the requirements writer must derive requirements from what is actually documented, not from what was intended.
-
-Gate: human reviews and approves all load-bearing requirements; no `rejected` or unresolved `draft` items remain.
-
----
-
-## The Design/Requirements Split — Why Isolation Matters
-
-Requirements written by the same context that argued out the design carry that context's blind spots. If the design left a behavior ambiguous and the design author filled it in mentally, requirements derived from that same mental state will encode the assumption without surfacing it for review. Written by a fresh context against the rendered design document alone, ambiguous points surface as gaps in `agentNotes` rather than silently-inherited assumptions.
-
-The isolation is structural, not stylistic. The requirements writer receives: the rendered design text and an output path. Nothing else. No user goal, no exploration findings, no conversation history. If something the user "intended" is not written in the design, it does not appear in the requirements — and that absence becomes visible, which is the desired outcome.
-
----
-
-## The Yield-Between-Runs Rule
-
-After the design is approved, the spec orchestrator runs `crtr node yield` before starting requirements work. This is mandatory, not optional.
-
-Why: the design conversation fills context with reasoning about tradeoffs, rejected alternatives, and design intent. That context biases delegation — it causes the orchestrator to frame the requirements task with assumptions from the design discussion. After yielding, the orchestrator revives fresh against `context/roadmap.md`, which records the finished design artifact path. It reads the design artifact cold and delegates the requirements work from that clean window, anchored on the rendered design rather than on the design conversation.
-
-The roadmap must record the design artifact path and the current stage before yielding. On revive, the first action is to read `context/roadmap.md`, confirm the design is landed, and delegate requirements work.
-
----
-
-## Roadmap Shape for a Spec Effort
-
-When shaping the roadmap at the start, structure it as follows. The goal section states what is being specified and for whom. Scope assumptions record what is in scope and what is not — a non-goal stated here propagates to every child without restating it. `## Strategy / phases` holds exactly three phases: Shape (gate: human sign-off), Design (gate: design artifact approved), Requirements (gate: all requirements approved). The current phase carries a one-line status of where it stands; completed phases are deleted, not summarized.
-
-After yield-and-revive, `## Strategy / phases` plus `## Active context` must let the fresh orchestrator orient in one pass without reading any child reports: the current phase's status line names what's in flight and which gate it's waiting on, and `## Active context` lists the design artifact and any other live context-file paths. Human-confirmed decisions and design detail fold into those context files, not the roadmap.
-
----
-
-## Delegating Design: Base Node vs. Orchestrator
-
-Spawn a base `design` node (terminal) when: the design surface is bounded, one component or subsystem, no multi-phase structure required. The node produces `context/design.md` and `context/design.json` and returns.
-
-Spawn a `design` orchestrator (resident) when: the feature spans multiple subsystems, has distinct implementation phases that need separate design treatment, or the design effort is itself likely to fill one context window before it's finished. Create it directly as an orchestrator — `crtr node new --kind design --mode orchestrator` — rather than spawning a base design node and counting on it to promote itself once it discovers the surface is too big; self-promotion is unreliable, and a node born an orchestrator is strictly more capable than one hoping to become one. Pass it the shape brief as its goal; it owns the decomposition and integration internally and reports a finished design artifact when done.
-
-In either case, the spec orchestrator waits for the design to land and the human to approve it before proceeding.
-
----
-
-## What a Finished Spec Contains
-
-A finished spec is precise enough that a planner can produce an implementation task breakdown without guessing intent. It contains:
-
-- **Behavior** — what the system does at its external boundary, organized by functional area, written in EARS format.
-- **Non-goals** — what is explicitly out of scope, so planners and implementers don't expand into it.
-- **Interfaces / inputs / outputs** — the data shapes and interaction contracts (at semantic-type level, not TypeScript declarations).
-- **Edge cases** — the failure modes, boundary conditions, and unusual states that must be handled, surfaced explicitly rather than left to the implementer to discover.
-- **Acceptance criteria** — per-requirement, testable conditions: "given input X, observe output Y" or "given state X, observe behavior Y."
-
-A spec that requires the reader to infer intent, assume behavior, or resolve design questions is not finished. If those gaps remain at the end of Stage 3, surface them explicitly as open questions before pushing final.

package/dist/commands/skill/state.d.ts

@@ -1,3 +0,0 @@
-export declare const stateEnable: import("../../core/command.js").LeafDef;
-export declare const stateDisable: import("../../core/command.js").LeafDef;
-export declare const stateBranch: import("../../core/command.js").BranchDef;

package/dist/commands/skill/state.js

@@ -1,71 +0,0 @@
-import { defineLeaf, defineBranch } from '../../core/command.js';
-import { skillConfigKey } from '../../types.js';
-import { resolveSkill } from '../../core/resolver.js';
-import { requireScopeRoot } from '../../core/scope.js';
-import { updateConfig, ensureScopeInitialized } from '../../core/config.js';
-import { resolveWriteScope } from './shared.js';
-async function toggleSkill(input, enabled) {
-    const nameRaw = input['name'];
-    const scopeStr = input['scope'];
-    const scope = resolveWriteScope(scopeStr);
-    const skillObj = resolveSkill(nameRaw);
-    const key = skillConfigKey(skillObj.plugin, skillObj.name);
-    const scopeRootPath = requireScopeRoot(scope);
-    ensureScopeInitialized(scope, scopeRootPath);
-    updateConfig(scope, (cfg) => {
-        cfg.skills[key] = { enabled };
-    });
-    return { name: skillObj.name, scope, enabled };
-}
-export const stateEnable = defineLeaf({
-    name: 'enable',
-    description: 'enable a skill',
-    whenToUse: 're-enable a skill that was previously disabled, making it visible to list and agent discovery again in the target scope.',
-    help: {
-        name: 'skill state enable',
-        summary: 'enable a skill in the given scope',
-        params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope where the enable was applied.' },
-            { name: 'enabled', type: 'boolean', required: true, constraint: 'Always true.' },
-        ],
-        outputKind: 'object',
-        effects: ['Writes the skill enable flag to config.json in the target scope.'],
-    },
-    run: async (input) => toggleSkill(input, true),
-});
-export const stateDisable = defineLeaf({
-    name: 'disable',
-    description: 'disable a skill',
-    whenToUse: 'hide a skill from list and agent discovery without deleting it — writes a disable flag to config.json in the target scope; reverse it later with `crtr skill state enable`.',
-    help: {
-        name: 'skill state disable',
-        summary: 'disable a skill in the given scope, hiding it from list and agent discovery',
-        params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope where the disable was applied.' },
-            { name: 'enabled', type: 'boolean', required: true, constraint: 'Always false.' },
-        ],
-        outputKind: 'object',
-        effects: ['Writes the skill disable flag to config.json in the target scope.'],
-    },
-    run: async (input) => toggleSkill(input, false),
-});
-export const stateBranch = defineBranch({
-    name: 'state',
-    description: 'enable or disable skills',
-    whenToUse: 'turn a skill on or off in a scope — disable to hide it from discovery without removing it, enable to bring it back.',
-    help: {
-        name: 'skill state',
-        summary: 'enable or disable skills',
-    },
-    children: [stateEnable, stateDisable],
-});

package/dist/core/__tests__/broker-crash-teardown.test.js

@@ -1,116 +0,0 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/broker-crash-teardown.test.ts
-//
-// Broker crash / teardown / boot-failure — acceptance items 4–6 of the headless-
-// broker migration plus the M-1/M-2 boot-failure regression. Split out of
-// broker-lifecycle.test.ts (see its header for the full file map); the tests are
-// the original acceptance gate, unchanged, on their own isolated harness:
-//   4 survive a broker crash via grace-revive RESUME on the saved .jsonl         → "CRASH"
-//   5 tear down cleanly — close → shutdown frame → exit, socket unlinked         → "clean teardown"
-//   6 ONE-WRITER (R2) — never two engine pids alive across crash→grace-revive    → "CRASH"
-//   M-1/M-2 a broker that dies before session_start is reaped, not stranded      → "boot failure"
-import { test, before, after } from 'node:test';
-import assert from 'node:assert/strict';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { createHarness, hasTmux } from './helpers/harness.js';
-import { isPidAlive } from '../canvas/pid.js';
-import { FAIL_BEFORE_SESSION_START } from './fixtures/fake-engine.js';
-// crtrd.ts module const (not exported). The fresh-pi-boot grace window the daemon
-// waits before grace-reviving a pi observed dead. Reference: crtrd.ts
-// `REVIVE_GRACE_MS = 20_000`.
-const REVIVE_GRACE_MS = 20_000;
-let h;
-let root;
-before(async () => {
-    if (!hasTmux())
-        return;
-    h = await createHarness({ sessionPrefix: 'crtr-brkcrash' });
-    root = h.spawnRoot('broker-crash suite root');
-});
-after(async () => {
-    if (h !== undefined)
-        await h.dispose();
-});
-// ===========================================================================
-// Item 4 + 6 — broker CRASH → grace-revive RESUME on the saved .jsonl; ONE-
-// WRITER: the crashed pid is dead BEFORE the revive launches and never
-// resurrects, and the revived pid is distinct (never two engine pids at once).
-// ===========================================================================
-test('CRASH → grace-revive RESUME; one-writer (old pid dead before new, never resurrects)', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — crash');
-    const oldPid = h.node(id).pi_pid;
-    assert.equal(isPidAlive(oldPid), true, 'broker alive before the crash');
-    assert.equal(h.node(id).intent ?? null, null, 'fresh broker has a null intent (not refresh/idle-release)');
-    const boots = h.bootCount(id);
-    // Kill the broker out from under the daemon (a crash). Use a fixed clock so the
-    // grace window is exercised deterministically.
-    process.kill(oldPid, 'SIGKILL');
-    await h.waitFor(() => !isPidAlive(oldPid), { label: 'crashed broker pid is dead' });
-    // ONE-WRITER: the old engine pid is dead BEFORE any revive can launch.
-    assert.equal(isPidAlive(oldPid), false, 'crashed pid dead before the daemon revives');
-    const NOW = 5_000_000;
-    await h.tick(NOW); // pid dead, intent null → handleBrokerLiveness → handleLiveWindow marks pending
-    assert.equal(h.bootCount(id), boots, 'inside the grace window → NOT yet revived');
-    await h.tick(NOW + REVIVE_GRACE_MS + 1); // grace elapsed → reviveNode(resume:true)
-    const boot2 = await h.awaitBoot(id, { minCount: boots + 1 });
-    assert.equal(boot2.resuming, true, 'grace-revive RESUMES the saved .jsonl');
-    const newPid = h.node(id).pi_pid;
-    assert.ok(newPid != null && isPidAlive(newPid), 'the revived broker pid is alive');
-    assert.notEqual(newPid, oldPid, 'the revived pid is distinct from the crashed one');
-    assert.equal(isPidAlive(oldPid), false, 'one-writer: the crashed pid never resurrected');
-});
-// ===========================================================================
-// Item 5 — clean teardown: close → hostFor(meta).teardown → `shutdown` frame →
-// broker disposes + exits, socket unlinked, status canceled, daemon leaves it.
-// ===========================================================================
-test('clean teardown — node close → broker shutdown frame → exit, socket unlinked, not revived', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — teardown');
-    const pid = h.node(id).pi_pid;
-    const sock = h.brokerSock(id);
-    await h.waitFor(() => existsSync(sock), { label: 'broker created its view.sock' });
-    // Close via the REAL CLI (resolves the node from --node; the subprocess carries
-    // no TMUX_PANE). closeNode marks canceled BEFORE teardown (crash-safe order),
-    // then hostFor(broker).teardown sends the `shutdown` frame.
-    const res = h.cli(root, ['node', 'close', '--node', id]);
-    assert.equal(res.code, 0, `node close should exit 0\n--stderr--\n${res.stderr}`);
-    await h.waitFor(() => !isPidAlive(pid), { label: 'broker process exited on shutdown frame' });
-    await h.waitFor(() => !existsSync(sock), { label: 'broker unlinked its socket on exit' });
-    assert.equal(h.status(id), 'canceled', 'the closed node is canceled');
-    // listNodes only surfaces active|idle, so a canceled broker is never supervised.
-    await h.tick();
-    assert.equal(h.status(id), 'canceled', 'still canceled after a daemon tick');
-    assert.equal(isPidAlive(pid), false, 'the broker stays dead — never revived');
-});
-// ===========================================================================
-// M-1 regression — a broker that DIES before session_start must surface a boot
-// failure, not strand the node forever. Before the fix handleBrokerLiveness read
-// pid==null UNCONDITIONALLY as "still booting", so a broker that threw before
-// recording a pid/session left the node 'active' with no engine FOREVER and the
-// parent waited on a dead child. The daemon must instead crash it past the boot
-// grace + push a boot-failure up the spine. (Also proves M-2: the broker's fatal
-// diagnostic reaches job/broker.log instead of /dev/null.)
-// ===========================================================================
-test('boot failure — a broker that dies before session_start is reaped, not stranded (review M-1/M-2)', { skip: !hasTmux() }, async () => {
-    // A headless child whose broker throws before session_start (no pid, no session
-    // EVER recorded). spawnHeadlessChildNoBoot does not awaitBoot (there is none).
-    const id = await h.spawnHeadlessChildNoBoot(root, `headless worker — boot fail ${FAIL_BEFORE_SESSION_START}`);
-    // M-2: the broker logs its fatal stack to job/broker.log and exits(1). Without
-    // the stdio redirect this diagnostic would be lost to /dev/null.
-    const brokerLog = join(h.home, 'nodes', id, 'job', 'broker.log');
-    await h.waitFor(() => existsSync(brokerLog) && /simulated pre-session_start boot failure/.test(readFileSync(brokerLog, 'utf8')), { label: 'broker logged its pre-session_start failure to job/broker.log' });
-    // The node is stuck 'active' with a null pid and a null session — the strand.
-    const n0 = h.node(id);
-    assert.equal(n0.pi_pid ?? null, null, 'no broker pid was ever recorded');
-    assert.equal(n0.pi_session_id ?? null, null, 'no session was ever recorded');
-    // Inside the boot grace the daemon LEAVES it (could be the sub-second boot gap).
-    const NOW = 9_000_000;
-    await h.tick(NOW);
-    assert.equal(h.status(id), 'active', 'inside the boot grace → daemon leaves it (boot gap)');
-    // Past the boot grace with STILL no pid and no session → crash + boot failure.
-    await h.tick(NOW + REVIVE_GRACE_MS + 1);
-    await h.waitForStatus(id, 'dead');
-    assert.equal(h.status(id), 'dead', 'a never-booted broker is reaped, not stranded active forever');
-    // …and the parent (an active subscriber of the child) was told up the spine.
-    const note = h.inbox(root).find((e) => /never started/.test(e.label ?? ''));
-    assert.ok(note !== undefined, 'the parent received a boot-failure notice up the spine');
-});

package/dist/core/__tests__/broker-dialogs.test.js

@@ -1,126 +0,0 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/broker-dialogs.test.ts
-//
-// Broker dialog handling — the §5.4 C2 forward-progress proof plus the T8 attach
-// gates G5/G5b/G6. Split out of broker-lifecycle.test.ts (see its header for the
-// full file map); the tests are the original acceptance gate, unchanged, on their
-// own isolated harness. The attach-client helpers live in
-// helpers/broker-clients.ts (the PRODUCTION ViewSocketClient, §0 one-writer: a
-// viewer holds ONLY a socket).
-import { test, before, after, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { createHarness, hasTmux } from './helpers/harness.js';
-import { isPidAlive } from '../canvas/pid.js';
-import { createAttachKit } from './helpers/broker-clients.js';
-let h;
-let root;
-const kit = createAttachKit(() => h);
-const { attach, attachUntil } = kit;
-before(async () => {
-    if (!hasTmux())
-        return;
-    h = await createHarness({ sessionPrefix: 'crtr-brkdlg' });
-    root = h.spawnRoot('broker-dialogs suite root');
-});
-after(async () => {
-    if (h !== undefined)
-        await h.dispose();
-});
-afterEach(() => {
-    kit.closeAll();
-});
-const brokerPid = (id) => h.node(id).pi_pid;
-// ===========================================================================
-// C2 forward-progress (zero-viewer path) — an unattended blocking dialog
-// resolves to its default (false) IMMEDIATELY: with no controller connected the
-// broker's REAL makeBrokerUiContext falls back to noOp resolution, so the engine
-// never deadlocks AND never waits on a per-dialog timeout (the design §5.4
-// timeout premise is false). Red/green: the OLD broker armed a setTimeout and
-// resolved only after `timeout` ms; the fixed broker resolves in ~0ms. (Supports
-// acceptance item 7: the existing suite stays green; this only ADDS coverage.)
-// ===========================================================================
-test('C2 — unattended dialog resolves to its default IMMEDIATELY (noOp), never waits on a timeout', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — dialog');
-    const pid = h.node(id).pi_pid;
-    // Drive the fake engine to call uiContext.confirm(..., { timeout: 5000 }) with
-    // NO controller. C2 fix: makeBrokerUiContext resolves the default (false) AT
-    // ONCE — it does NOT arm/await the timeout. A generous < 2000ms bound is still a
-    // hard fail against the old ~5000ms timeout-wait while staying robust on slow CI.
-    h.fakeCmd(id, { cmd: 'dialog', timeout: 5000 });
-    const results = await h.waitFor(() => {
-        const r = h.dialogResults(id);
-        return r.length > 0 ? r : null;
-    }, { timeoutMs: 15_000, label: 'unattended dialog resolved' });
-    assert.equal(results[0].resolved, false, 'unattended confirm resolves to its default (false / deny)');
-    assert.ok(results[0].ms < 2000, `C2: resolved IMMEDIATELY (noOp), not after the 5000ms timeout — got ${results[0].ms}ms`);
-    assert.equal(isPidAlive(pid), true, 'the broker made forward progress (still alive, did not hang or exit)');
-});
-// ---------------------------------------------------------------------------
-// G5 — dialog forward + answer. Guards: a blocking dialog reaches the controller
-// as extension_ui_request and the controller's extension_ui_response unblocks the
-// engine with ITS answer (not the default). Failure mode: a dialog the controller
-// can't see/answer (silent deadlock).
-// ---------------------------------------------------------------------------
-test('G5 — controller receives an extension_ui_request, answers it, and the engine proceeds with that answer', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G5a');
-    const c = await attach(id, 'controller', 'g5-ctrl');
-    h.fakeCmd(id, { cmd: 'dialog', timeout: 20_000 }); // generous: the controller answers first
-    const req = await c.waitFrame((f) => f.type === 'extension_ui_request', 'G5 dialog forwarded to controller');
-    assert.equal(req.method, 'confirm', 'G5: the forwarded dialog is the confirm() the engine raised');
-    const reqId = req.id;
-    c.send({ type: 'extension_ui_response', id: reqId, confirmed: true });
-    const results = await h.waitFor(() => {
-        const r = h.dialogResults(id);
-        return r.length > 0 ? r : null;
-    }, { label: 'G5 dialog resolved by the controller', timeoutMs: 15_000 });
-    assert.equal(results[0].resolved, true, 'G5: the engine proceeded with the controller answer (true), not the default (false)');
-});
-// ---------------------------------------------------------------------------
-// G5 (mid-dialog attach) — Guards: a dialog raised under a prior controller stays
-// pending across that controller's detach (M2) and is delivered to whoever takes
-// control next via welcome.pending_dialog. Failure mode: a pending dialog lost on
-// controller handoff.
-// ---------------------------------------------------------------------------
-test('G5 — a controller attaching MID-dialog receives the pending dialog via welcome.pending_dialog', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G5b');
-    const a = await attach(id, 'controller', 'g5b-A');
-    h.fakeCmd(id, { cmd: 'dialog', timeout: 30_000 }); // stays pending long enough for the handoff
-    const reqA = await a.waitFrame((f) => f.type === 'extension_ui_request', 'G5b dialog forwarded to controller A');
-    const reqId = reqA.id;
-    a.send({ type: 'bye' });
-    a.close(); // M2: detach frees control but does NOT cancel the pending dialog
-    // Controller B takes control (retry covers the close→controllerId=null beat) and
-    // its welcome carries the still-pending dialog.
-    const b = await attachUntil(id, 'controller', 'g5b-B', (x) => x.welcome.role === 'controller' && x.welcome.pending_dialog != null, 'G5b controller B takes control with the pending dialog');
-    assert.equal(b.welcome.pending_dialog.id, reqId, 'G5b: welcome.pending_dialog is the same dialog raised under A');
-    assert.equal(b.welcome.pending_dialog.method, 'confirm', 'G5b: the pending dialog is the confirm()');
-    b.send({ type: 'extension_ui_response', id: reqId, confirmed: true });
-    const results = await h.waitFor(() => {
-        const r = h.dialogResults(id);
-        return r.length > 0 ? r : null;
-    }, { label: 'G5b dialog resolved by controller B', timeoutMs: 15_000 });
-    assert.equal(results[0].resolved, true, 'G5b: controller B answered the handed-off dialog and the engine proceeded');
-});
-// ---------------------------------------------------------------------------
-// G6 — anti-deadlock. (a) a zero-viewer dialog resolves to its default AT ONCE
-// (noOp). (b) an ATTENDED dialog the controller never answers resolves on a SHORT
-// per-dialog broker timeout. Guards: the engine never hangs on a dialog with no
-// answerer. Failure mode: a forever-blocked turn.
-// ---------------------------------------------------------------------------
-test('G6 — zero-viewer dialog resolves immediately; an unanswered attended dialog resolves on the broker timeout', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G6');
-    const pid = brokerPid(id);
-    // (a) zero viewers → immediate noOp default (NOT the 5000ms timeout).
-    h.fakeCmd(id, { cmd: 'dialog', timeout: 5000 });
-    const r1 = await h.waitFor(() => (h.dialogResults(id).length >= 1 ? h.dialogResults(id) : null), { label: 'G6a zero-viewer dialog resolved', timeoutMs: 15_000 });
-    assert.equal(r1[0].resolved, false, 'G6a: zero-viewer dialog resolves to the default (deny)');
-    assert.ok(r1[0].ms < 2000, `G6a: resolved immediately (noOp), not after the 5000ms timeout — got ${r1[0].ms}ms`);
-    // (b) controller attached but silent → the broker resolves on the SHORT explicit
-    // per-dialog timeout (800ms), never the 120s default.
-    const c = await attach(id, 'controller', 'g6-ctrl');
-    h.fakeCmd(id, { cmd: 'dialog', timeout: 800 });
-    await c.waitFrame((f) => f.type === 'extension_ui_request', 'G6b dialog forwarded to controller'); // received, deliberately NOT answered
-    const r2 = await h.waitFor(() => (h.dialogResults(id).length >= 2 ? h.dialogResults(id) : null), { label: 'G6b attended dialog resolved on timeout', timeoutMs: 15_000 });
-    assert.equal(r2[1].resolved, false, 'G6b: an unanswered attended dialog resolves to the default (deny)');
-    assert.ok(r2[1].ms >= 600 && r2[1].ms < 5000, `G6b: resolved on the ~800ms per-dialog timeout, not instantly and not the 120s default — got ${r2[1].ms}ms`);
-    assert.equal(isPidAlive(pid), true, 'G6: the engine made forward progress on both dialogs (still alive)');
-});