@crouton-kit/crouter 0.3.11 → 0.3.12

package/dist/commands/debug.js

@@ -1,192 +0,0 @@
-// `crtr mode debug` leaf — reproduce-first root-cause workflow.
-//
-// Running it spawns a reproduction-only agent in a sibling tmux pane (the same
-// spawn + job-handle shape as `crtr agent new`) and returns a job handle
-// plus a follow_up. The orchestrator-side methodology lives in FLOW_DEBUG_GUIDE
-// (the leaf's help.guide), loaded via `crtr mode debug -h` after the repro
-// agent returns. Methodology stays in the CLI guide field, like PLAN_NEW_GUIDE;
-// no builtin skill.
-export const FLOW_DEBUG_GUIDE = `## Debug workflow — reproduce first
-
-Audience: the agent that ran \`crtr mode debug\`. A reproduction agent is
-already spawned in a sibling pane. It writes ONE failing integration test and
-never fixes anything. You do everything after: gate on the repro, root-cause,
-fix, verify against that same test.
-
-### Phase 0: Await the repro agent
-
-Run \`crtr job read result <job_id> --wait\` (10-min budget).
-On status:"timeout": re-issue the wait, or run \`crtr job read logs <job_id> --follow\`
-until the job is terminal.
-
-### Phase 1: Gate on reproduction
-
-\`reproduces:true\`: read \`test_path\`, run \`test_command\` YOURSELF, confirm
-it fails for the stated reason. Do not trust the agent's claim — if it passes
-or fails differently, treat repro as NOT achieved. This test is the regression
-gate; it stays in the suite after the fix.
-\`status:"failed"\` / \`reproduces:false\` / your run disproves it: no repro
-harness. Continue, but record "no reproduction — fix unverified; do not claim
-verified-fixed."
-
-### Phase 2: Reconnaissance
-
-Read the key files yourself — entry point, failure point, the data flow
-between. \`git log\` / \`git blame\` near the failure: recent changes are
-high-signal.
-
-### Phase 3: Assess difficulty, scale investigators
-
-Simple → solo (Explore subagents for tracing if the area is large).
-Medium → 2–3 parallel \`devcore:senior-advisor\`: data-flow tracer, assumption
-auditor, change investigator.
-Hard (intermittent, races, "been stuck", many modules) → 3–5 parallel:
-end-to-end tracer, assumption breaker, git archaeologist, boundary inspector.
-Give investigators file paths, observed behavior, and concrete tasks — never
-your hypotheses. Challenge theories against each other; the one that survives
-disconfirmation wins.
-
-### Phase 4: Fix
-
-Minimal root-cause fix. No scope expansion, no drive-by refactor.
-
-### Phase 5: Verify
-
-Re-run \`test_command\`: it MUST now pass. Run the broader suite for
-regressions. If there was no repro test, state the fix is unverified by
-reproduction and recommend explicit manual verification.
-
-### Phase 6: Report
-
-Root cause (exact line + why), evidence, the now-passing repro test path,
-confidence (High/Medium/Low; if not High, name what is uncertain).
-
-### Constraints
-
-The repro test is the regression guard — it stays; a fix-agent must never
-weaken it. Investigators run in forked contexts; they return summaries, not
-raw output. No code changes during Phases 2–3 except the repro test.`;
-import { defineLeaf } from '../core/command.js';
-import { InputError } from '../core/io.js';
-import { createJob, appendEvent } from '../core/jobs.js';
-import { spawnAgent, isInTmux } from '../core/spawn.js';
-import { readConfig } from '../core/config.js';
-import { reproHandoffPrompt } from '../prompts/debug.js';
-// Inlined from job.ts (module-private there; not exported, per the no-shim
-// convention). Same forms.
-function resolveMaxPanes() {
-    const cfg = readConfig('user');
-    return cfg.max_panes_per_window;
-}
-function assertTmux() {
-    if (!isInTmux()) {
-        throw new InputError({
-            error: 'not_in_tmux',
-            message: 'crtr mode debug requires tmux (TMUX env var not set).',
-            next: 'Run inside a tmux session.',
-        });
-    }
-}
-export function registerDebug() {
-    return defineLeaf({
-        name: 'debug',
-        help: {
-            name: 'mode debug',
-            summary: 'reproduce-first root-cause workflow: spawns a reproduction agent, then you root-cause and fix',
-            guide: FLOW_DEBUG_GUIDE,
-            params: [
-                {
-                    kind: 'stdin',
-                    name: 'steps_to_reproduce',
-                    required: true,
-                    constraint: 'Prose describing how to reproduce the failure. Pipe on stdin.',
-                },
-                {
-                    kind: 'flag',
-                    name: 'summary',
-                    type: 'string',
-                    required: true,
-                    constraint: 'One paragraph summary of the failure: symptom, where observed, expected vs actual.',
-                },
-                {
-                    kind: 'flag',
-                    name: 'cwd',
-                    type: 'path',
-                    required: false,
-                    constraint: 'Working directory for the spawned agent. Defaults to process.cwd().',
-                },
-            ],
-            output: [
-                {
-                    name: 'job_id',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Use with `job read status`, `job read logs`, `job read result`, `job cancel`.',
-                },
-                {
-                    name: 'follow_up',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Recommended next call.',
-                },
-            ],
-            outputKind: 'object',
-            effects: [
-                'Spawns a reproduction agent in a sibling tmux pane.',
-                'Creates a job entry at $XDG_STATE_HOME/crtr/jobs/<job_id>/.',
-                'On completion, result writes atomically to result.json.',
-            ],
-        },
-        slash: {
-            name: 'debug',
-            description: 'Debug mode — reproduce-first root-cause investigation.',
-            argumentHint: '<symptom or failing test>',
-            body: `You are entering **debug mode**: a reproduce-first, root-cause investigation.
-
-1. Run \`crtr mode debug -h\` to load the debugging workflow and output schema.
-2. Follow it — reproduce the failure first, then isolate the root cause before proposing a fix.
-
-The issue: $ARGUMENTS
-
-If no issue was given, ask the user for the symptom or failing test before starting.`,
-        },
-        run: async (input) => {
-            assertTmux();
-            const stepsToReproduce = input['steps_to_reproduce'];
-            const summary = input['summary'];
-            const cwd = input['cwd'] ?? process.cwd();
-            const issue = `${summary}\n\n${stepsToReproduce}`;
-            const { jobId } = createJob('debug-repro', { cwd });
-            const result = spawnAgent({
-                prompt: reproHandoffPrompt(issue, jobId),
-                cwd,
-                jobId,
-                maxPanesPerWindow: resolveMaxPanes(),
-            });
-            if (result.status === 'not-in-tmux') {
-                throw new InputError({
-                    error: 'not_in_tmux',
-                    message: result.message,
-                    next: 'Run inside a tmux session.',
-                });
-            }
-            if (result.status === 'spawn-failed') {
-                throw new InputError({
-                    error: 'spawn_failed',
-                    message: result.message,
-                    next: 'Check tmux is running and try again.',
-                });
-            }
-            const paneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
-            appendEvent(jobId, {
-                level: 'info',
-                event: 'worker_started',
-                message: `repro pane ${paneLabel} spawned`,
-            });
-            return {
-                job_id: jobId,
-                follow_up: `Await the reproduction agent: crtr job read result ${jobId} --wait. Then run \`crtr mode debug -h\` and follow the workflow from Phase 1.`,
-            };
-        },
-    });
-}

package/dist/commands/job.d.ts

@@ -1,11 +0,0 @@
-import type { BranchDef } from '../core/command.js';
-/** Count of jobs currently in the live state, or null when listing fails.
- *  Backs the always-on "Workers running" signal on root -h so an agent never
- *  forgets it has in-flight workers to collect. */
-export declare function liveJobCount(): number | null;
-/** The job subtree's root-level dynamic block. A bounded aggregate (running
- *  count + how to collect), never an enumeration: live jobs are volatile and
- *  unbounded, so listing them in root -h would balloon (cli-design rule 15).
- *  Omitted when nothing is running. */
-export declare function buildJobRootBlock(): string | null;
-export declare function registerJob(): BranchDef;

package/dist/commands/job.js

@@ -1,384 +0,0 @@
-// `crtr job` subtree — universal monitoring registry for any ongoing task.
-//
-// Producers (agent spawns, future task systems) register jobs and write
-// results; this subtree is the read/cancel/submit surface shared across all
-// producers. Sub-branches: read {list, status, logs, result}, submit, _fail,
-// cancel.
-//
-// Terminal-write contract:
-//   Worker MAY call `crtr job submit` → writes result.md (done|failed).
-//   If claude exits without submitting, the wrapper shell's `crtr job _fail`
-//   marks it failed IF no result file exists yet.
-//   If the worker's tmux pane is closed, SIGHUP skips `_fail`; the jobs layer
-//   then reaps the job by detecting that its recorded pane has vanished.
-//   `job read result` watches result file appearance and polls for pane death.
-//
-// `job read logs` is the only JSONL leaf.
-import { defineBranch, defineLeaf } from '../core/command.js';
-import { emitLine } from '../core/io.js';
-import { InputError } from '../core/io.js';
-import { writeMarkdownResult, readResult as jobsReadResult, jobStatus, listJobs, readLog, cancelJob, appendEvent, } from '../core/jobs.js';
-import { scheduleKillCurrentPane } from '../core/spawn.js';
-import { paginate } from '../core/pagination.js';
-import { stateBlock } from '../core/help.js';
-const WAIT_BUDGET_MS = 10 * 60 * 1000;
-const FOLLOW_POLL_MS = 1000;
-/** Count of jobs currently in the live state, or null when listing fails.
- *  Backs the always-on "Workers running" signal on root -h so an agent never
- *  forgets it has in-flight workers to collect. */
-export function liveJobCount() {
-    try {
-        return listJobs().filter((j) => j.state === 'live').length;
-    }
-    catch {
-        return null;
-    }
-}
-/** The job subtree's root-level dynamic block. A bounded aggregate (running
- *  count + how to collect), never an enumeration: live jobs are volatile and
- *  unbounded, so listing them in root -h would balloon (cli-design rule 15).
- *  Omitted when nothing is running. */
-export function buildJobRootBlock() {
-    const n = liveJobCount();
-    if (n === null || n === 0)
-        return null;
-    return stateBlock('workers', { count: n }, '`crtr job read list` to see them; `crtr job read result ID` to collect');
-}
-const DEFAULT_KILL_SECS = 2;
-// ---------------------------------------------------------------------------
-// read sub-branch
-// ---------------------------------------------------------------------------
-const readList = defineLeaf({
-    name: 'list',
-    help: {
-        name: 'job read list',
-        summary: 'paginated list of jobs, sorted by created_at ascending',
-        params: [
-            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 20, constraint: 'Default 20, max 100.' },
-            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
-        ],
-        output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {job_id, kind, state, created_at}. Sorted by created_at ascending.' },
-            { name: 'next_cursor', type: 'string | null', required: true, constraint: 'null means no more items.' },
-            { name: 'total', type: 'integer | null', required: true, constraint: 'Total count of all jobs.' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only.'],
-    },
-    run: async (input) => {
-        const limit = typeof input['limit'] === 'number' ? input['limit'] : 20;
-        const cursor = typeof input['cursor'] === 'string' ? input['cursor'] : undefined;
-        const all = listJobs();
-        const page = paginate(all, { limit, cursor }, {
-            defaultLimit: 20,
-            maxLimit: 100,
-            keyOf: (item) => item.created_at,
-            total: 'count',
-        });
-        return {
-            items: page.items,
-            next_cursor: page.next_cursor,
-            total: page.total,
-        };
-    },
-});
-const readStatus = defineLeaf({
-    name: 'status',
-    help: {
-        name: 'job read status',
-        summary: 'read the current status of a job',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
-        ],
-        output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Echo of input.' },
-            { name: 'state', type: 'string', required: true, constraint: 'One of: live, done, failed, canceled, closed (worker pane closed with no submitted result).' },
-            { name: 'age_s', type: 'number', required: true, constraint: 'Seconds since job creation.' },
-            { name: 'last_event', type: 'object | null', required: true, constraint: 'Most recent log event {event, ts}, or null if no events yet.' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only.'],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const status = jobStatus(jobId);
-        return {
-            job_id: jobId,
-            state: status.state,
-            age_s: status.age_s,
-            last_event: status.last_event,
-        };
-    },
-});
-const readLogs = defineLeaf({
-    name: 'logs',
-    help: {
-        name: 'job read logs',
-        summary: 'read log events from a job; emits JSONL — one event object per line',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
-            { kind: 'flag', name: 'since', type: 'string', required: false, constraint: 'ISO 8601 timestamp. Only emit events at or after this time.' },
-            { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'ISO 8601 timestamp. Only emit events before this time.' },
-            { kind: 'flag', name: 'level', type: 'enum', choices: ['debug', 'info', 'warn', 'error'], required: false, default: 'info', constraint: 'Minimum severity. Default: info.' },
-            { kind: 'flag', name: 'follow', type: 'bool', required: false, constraint: 'When present, stream new events until the job reaches a terminal state, then stop.' },
-        ],
-        output: [
-            {
-                name: '<event line>',
-                type: 'object',
-                required: true,
-                constraint: 'Each JSONL line is: {ts:string, level:"debug"|"info"|"warn"|"error", event:string, message:string, data?:object}. Emitted one per line.',
-            },
-        ],
-        outputKind: 'jsonl',
-        effects: ['None. Read-only.'],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const since = typeof input['since'] === 'string' ? input['since'] : undefined;
-        const until = typeof input['until'] === 'string' ? input['until'] : undefined;
-        const level = (typeof input['level'] === 'string' ? input['level'] : 'info');
-        const follow = input['follow'] === true;
-        const minLevel = level;
-        // Emit all existing events.
-        const events = readLog(jobId, { sinceTs: since, untilTs: until, minLevel });
-        for (const ev of events) {
-            emitLine(ev);
-        }
-        if (!follow)
-            return;
-        // Follow: poll for new events until the job reaches a terminal state.
-        // Track the latest emitted timestamp to avoid re-emitting.
-        let lastTs = until !== undefined ? until : new Date(0).toISOString();
-        // Update lastTs from emitted events.
-        for (const ev of events) {
-            const e = ev;
-            if (typeof e['ts'] === 'string' && e['ts'] > lastTs) {
-                lastTs = e['ts'];
-            }
-        }
-        const terminalStates = new Set(['done', 'failed', 'canceled', 'closed']);
-        await new Promise((resolve) => {
-            const poll = () => {
-                const status = jobStatus(jobId);
-                const newEvents = readLog(jobId, { sinceTs: lastTs !== new Date(0).toISOString() ? lastTs : undefined, minLevel });
-                for (const ev of newEvents) {
-                    const e = ev;
-                    if (typeof e['ts'] === 'string' && e['ts'] > lastTs) {
-                        emitLine(e);
-                        lastTs = e['ts'];
-                    }
-                }
-                if (terminalStates.has(status.state)) {
-                    resolve();
-                    return;
-                }
-                setTimeout(poll, FOLLOW_POLL_MS);
-            };
-            setTimeout(poll, FOLLOW_POLL_MS);
-        });
-    },
-});
-const readResult = defineLeaf({
-    name: 'result',
-    help: {
-        name: 'job read result',
-        summary: 'read the final result of a completed job',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
-            { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'When present, blocks until a result file appears (up to 10 min).' },
-        ],
-        output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Echo of input.' },
-            { name: 'status', type: 'string', required: true, constraint: 'One of: done, failed, canceled, closed, timeout. closed = the worker pane went away before submitting a result.' },
-            { name: 'result_md', type: 'string', required: false, constraint: 'Markdown body submitted by an agent via `crtr job submit`. Present when the job used the agent submit path.' },
-            { name: 'result', type: 'object', required: false, constraint: 'Structured object submitted by a programmatic caller (human/sys). Present when the job used the programmatic submit path.' },
-            { name: 'reason', type: 'string', required: false, constraint: 'Short explanation from frontmatter. Present when status is failed (agent-reported error) or closed (worker pane closed before submitting).' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only.'],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const wait = input['wait'] === true;
-        const r = await jobsReadResult(jobId, { waitMs: wait ? WAIT_BUDGET_MS : 0 });
-        const out = { job_id: jobId, status: r.status };
-        if (r.result !== undefined) {
-            out['result'] = r.result;
-        }
-        if (r.result_md !== undefined) {
-            out['result_md'] = r.result_md;
-        }
-        if (r.reason !== undefined) {
-            out['reason'] = r.reason;
-        }
-        return out;
-    },
-});
-const readBranch = defineBranch({
-    name: 'read',
-    help: {
-        name: 'job read',
-        summary: 'read job status, logs, or results',
-        children: [
-            { name: 'list', desc: 'paginated job list', useWhen: 'enumerating jobs' },
-            { name: 'status', desc: 'current state and age', useWhen: 'checking if a job is still live' },
-            { name: 'logs', desc: 'stream JSONL log events', useWhen: 'monitoring progress or debugging a job' },
-            { name: 'result', desc: 'read final result', useWhen: 'collecting the output of a completed job' },
-        ],
-    },
-    children: [readList, readStatus, readLogs, readResult],
-});
-// ---------------------------------------------------------------------------
-// submit — called by the worker inside its pane (or by any producer that
-// writes a result programmatically)
-// ---------------------------------------------------------------------------
-const jobSubmit = defineLeaf({
-    name: 'submit',
-    help: {
-        name: 'job submit',
-        summary: 'deliver a markdown result back to a job record (called by workers, or any producer writing the terminal value)',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id injected as $CRTR_JOB_ID in the spawned pane.' },
-            { kind: 'stdin', name: 'body', required: false, constraint: 'Markdown body of the result, piped on stdin. Required when --status is done (the default). When --status failed, stdin is optional; --reason carries the explanation.' },
-            { kind: 'flag', name: 'status', type: 'enum', choices: ['done', 'failed'], required: false, default: 'done', constraint: 'Terminal status to record. Default: done.' },
-            { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Short failure reason. Required when --status failed; ignored otherwise.' },
-            { kind: 'flag', name: 'kill-pane', type: 'bool', required: false, constraint: `When present, schedule the current tmux pane to close ${DEFAULT_KILL_SECS}s after submission so the spawned worker does not linger. Reviewer agents should pass this; planner/implementer handoffs already self-kill on spawn.` },
-        ],
-        output: [
-            { name: 'submitted', type: 'boolean', required: true, constraint: 'Always true on success.' },
-            { name: 'pane_kill_scheduled', type: 'boolean', required: true, constraint: 'True when --kill-pane is set and a tmux pane kill was scheduled. False otherwise (--kill-pane not set, not in tmux, or TMUX_PANE unset).' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Writes <jobdir>/result.md atomically (YAML frontmatter + body), marking the job done or failed.',
-            'Updates meta.json status to match.',
-            `When --kill-pane is set, schedules \`tmux kill-pane\` on $TMUX_PANE after ${DEFAULT_KILL_SECS}s (detached; submit still returns cleanly).`,
-        ],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const status = (typeof input['status'] === 'string' ? input['status'] : 'done');
-        const body = typeof input['body'] === 'string' ? input['body'] : '';
-        const reason = typeof input['reason'] === 'string' ? input['reason'] : '';
-        const killPane = input['killPane'] === true;
-        if (status === 'done' && body.trim() === '') {
-            throw new InputError({
-                error: 'invalid_field',
-                message: '--status done requires a markdown body on stdin.',
-                field: 'body',
-                next: `Pipe the markdown result on stdin, e.g. \`crtr job submit ${jobId} <<'MD' ... MD\`. For failures, use \`--status failed --reason "<why>"\`.`,
-            });
-        }
-        if (status === 'failed' && reason.trim() === '') {
-            throw new InputError({
-                error: 'invalid_field',
-                message: '--status failed requires --reason "<text>".',
-                field: 'reason',
-                next: 'Pass --reason explaining why the task could not complete.',
-            });
-        }
-        writeMarkdownResult(jobId, body, status, status === 'failed' ? reason : undefined);
-        appendEvent(jobId, {
-            level: status === 'failed' ? 'error' : 'info',
-            event: 'worker_finished',
-            message: status === 'failed' ? `worker failed: ${reason}` : 'worker submitted result',
-        });
-        const paneKillScheduled = killPane ? scheduleKillCurrentPane(DEFAULT_KILL_SECS) : false;
-        return { submitted: true, pane_kill_scheduled: paneKillScheduled };
-    },
-});
-// ---------------------------------------------------------------------------
-// _fail — called by the wrapper shell if claude exits without submitting
-// ---------------------------------------------------------------------------
-const jobFail = defineLeaf({
-    name: '_fail',
-    help: {
-        name: 'job _fail',
-        summary: 'internal: mark a job failed if it has not already been submitted (called by wrapper shell)',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id. If a result file already exists, this is a no-op.' },
-        ],
-        output: [
-            { name: 'recorded', type: 'boolean', required: true, constraint: 'True if failure was recorded; false if a result file already existed (no-op).' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Writes result.md with status "failed" and a reason if no result file is present.',
-            'Updates meta.json status to failed.',
-        ],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        try {
-            const existing = await jobsReadResult(jobId, { waitMs: 0 });
-            if (existing.status !== 'timeout') {
-                return { recorded: false };
-            }
-        }
-        catch {
-            // job dir not found — still try to write to surface the failure
-        }
-        try {
-            writeMarkdownResult(jobId, '', 'failed', 'worker exited without submitting');
-            appendEvent(jobId, {
-                level: 'error',
-                event: 'worker_finished',
-                message: 'worker exited without submitting',
-            });
-            return { recorded: true };
-        }
-        catch {
-            return { recorded: false };
-        }
-    },
-});
-// ---------------------------------------------------------------------------
-// cancel
-// ---------------------------------------------------------------------------
-const jobCancel = defineLeaf({
-    name: 'cancel',
-    help: {
-        name: 'job cancel',
-        summary: 'send a best-effort cancellation signal to a running job',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
-        ],
-        output: [
-            { name: 'canceled', type: 'boolean', required: true, constraint: 'True if a signal was delivered or the job was already terminal; false if the job was not live.' },
-        ],
-        outputKind: 'object',
-        effects: ['Best-effort: delivers SIGTERM to the worker process and marks meta.json canceled.'],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const result = cancelJob(jobId);
-        return { canceled: result.canceled };
-    },
-});
-// ---------------------------------------------------------------------------
-// root branch
-// ---------------------------------------------------------------------------
-export function registerJob() {
-    return defineBranch({
-        name: 'job',
-        rootEntry: {
-            concept: 'producer-agnostic record of any ongoing task — its logs and result',
-            desc: 'monitor and collect from any ongoing task',
-            useWhen: 'reading status, logs, or result of a job started by any producer',
-            dynamicState: buildJobRootBlock,
-        },
-        help: {
-            name: 'job',
-            summary: 'monitor and collect results from any ongoing task',
-            model: 'A job is a producer-agnostic record of an ongoing task: state, logs, terminal result. Producers (`crtr agent new *`, future task systems) create jobs; this subtree is the shared read/cancel/submit surface. States: live | done | failed | canceled | closed (worker pane closed before submitting a result).',
-            children: [
-                { name: 'read', desc: 'read status, logs, or results', useWhen: 'monitoring or collecting from a running or completed job' },
-                { name: 'submit', desc: 'deliver result from inside a worker pane or any producer', useWhen: 'a worker is ready to return its output' },
-                { name: '_fail', desc: 'internal: mark job failed on unsubmitted exit', useWhen: 'called by the wrapper shell, not manually' },
-                { name: 'cancel', desc: 'best-effort cancel a live job', useWhen: 'stopping a job that is no longer needed' },
-            ],
-        },
-        children: [readBranch, jobSubmit, jobFail, jobCancel],
-    });
-}