@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/commands/search/puremd.d.ts

@@ -0,0 +1,11 @@
+export type PuremdResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Fetch a single URL's content as markdown via pure.md, capped at maxChars.
+ *  Never throws — any transport or HTTP failure becomes { ok: false, reason }
+ *  so the caller can keep the URL in its failures list. */
+export declare function puremdFetch(url: string, maxChars: number): Promise<PuremdResult>;

package/dist/commands/search/puremd.js

@@ -0,0 +1,53 @@
+// Fallback content fetcher: when Exa cannot fetch a URL, we re-fetch it through
+// pure.md (https://pure.md), which renders any page to clean markdown. This is
+// the ONLY module that talks to pure.md. API-key resolution is optional — the
+// service works keyless (rate-limited); a key raises limits.
+import { join } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { userScopeRoot } from '../../core/scope.js';
+const PUREMD_BASE = 'https://pure.md';
+/** Resolve an optional pure.md API token: PUREMD_API_KEY env first, then
+ *  ~/.crouter/puremd.key. Returns undefined when neither is set — pure.md is
+ *  usable keyless, so a missing token is not an error. */
+function getApiKey() {
+    const env = process.env['PUREMD_API_KEY'];
+    if (env !== undefined && env.trim() !== '')
+        return env.trim();
+    const keyFile = join(userScopeRoot(), 'puremd.key');
+    if (existsSync(keyFile)) {
+        const fromFile = readFileSync(keyFile, 'utf8').trim();
+        if (fromFile !== '')
+            return fromFile;
+    }
+    return undefined;
+}
+/** Fetch a single URL's content as markdown via pure.md, capped at maxChars.
+ *  Never throws — any transport or HTTP failure becomes { ok: false, reason }
+ *  so the caller can keep the URL in its failures list. */
+export async function puremdFetch(url, maxChars) {
+    const headers = {};
+    const key = getApiKey();
+    if (key !== undefined)
+        headers['x-puremd-api-token'] = key;
+    let res;
+    try {
+        res = await fetch(`${PUREMD_BASE}/${url}`, { headers });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `pure.md request failed: ${msg}` };
+    }
+    if (!res.ok) {
+        return { ok: false, reason: `pure.md returned ${res.status} ${res.statusText}` };
+    }
+    let text;
+    try {
+        text = (await res.text()).trim();
+    }
+    catch {
+        return { ok: false, reason: 'pure.md response body unreadable' };
+    }
+    if (text === '')
+        return { ok: false, reason: 'pure.md returned empty content' };
+    return { ok: true, text: text.slice(0, maxChars) };
+}

package/dist/commands/search/web.d.ts

@@ -0,0 +1 @@
+export declare const webLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/search/web.js

@@ -0,0 +1,65 @@
+import { defineLeaf } from '../../core/command.js';
+import { exaSearch, parseDomains, renderResult, TEXT_MAX_CHARACTERS, } from './exa.js';
+const SEARCH_TYPES = ['auto', 'fast', 'instant', 'deep-lite', 'deep', 'deep-reasoning'];
+export const webLeaf = defineLeaf({
+    name: 'web',
+    description: 'find web pages relevant to a query, with highlight excerpts',
+    whenToUse: 'you need to discover web pages relevant to a query and read query-matched excerpts from them — the default web search. Use this for open-ended research, finding sources, or gathering current information. Reach for `answer` instead when you want one synthesized, cited answer to a specific question rather than a ranked list of pages; reach for `contents` when you already hold the URLs and only need their content.',
+    help: {
+        name: 'search web',
+        summary: 'web search via Exa — ranked results with query-relevant highlight excerpts (or full text)',
+        params: [
+            { kind: 'positional', name: 'query', required: true, constraint: 'The search query. Natural language; be specific.' },
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...SEARCH_TYPES], required: false, default: 'auto', constraint: 'Search depth. auto balances relevance and speed; fast/instant trade depth for latency; deep-lite/deep/deep-reasoning run multi-query expansion and rank the combined set for harder synthesis.' },
+            { kind: 'flag', name: 'num', type: 'int', required: false, default: 10, constraint: 'Number of results to return.' },
+            { kind: 'flag', name: 'text', type: 'bool', required: false, constraint: `Return cleaned full page text (capped at ${TEXT_MAX_CHARACTERS} characters per result) instead of highlight excerpts. Off by default; highlights keep token usage predictable.` },
+            { kind: 'flag', name: 'include-domains', type: 'string', required: false, constraint: 'Comma-separated domain allowlist — restrict results to these domains.' },
+            { kind: 'flag', name: 'exclude-domains', type: 'string', required: false, constraint: 'Comma-separated domain blocklist — drop results from these domains.' },
+        ],
+        output: [
+            { name: 'query', type: 'string', required: true, constraint: 'Echo of the query searched.' },
+            { name: 'results', type: 'object[]', required: true, constraint: 'Ranked best-first, each: title, url, published date and author when present, and either highlight excerpts (default) or capped full text (--text).' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Decision road sign: either read selected result URLs through the contents leaf after checking its schema, or refine the query.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sends one search request to the Exa API (network). No local state changes.'],
+    },
+    run: async (input) => {
+        const query = input['query'];
+        const type = input['type'];
+        const num = input['num'];
+        const wantText = input['text'];
+        const contents = wantText
+            ? { text: { maxCharacters: TEXT_MAX_CHARACTERS } }
+            : { highlights: true };
+        const body = { query, type, numResults: num, contents };
+        const include = parseDomains(input['includeDomains']);
+        const exclude = parseDomains(input['excludeDomains']);
+        if (include !== undefined)
+            body['includeDomains'] = include;
+        if (exclude !== undefined)
+            body['excludeDomains'] = exclude;
+        const res = await exaSearch(body);
+        const results = res.results ?? [];
+        return {
+            query,
+            results,
+            follow_up: 'Fetch full content for selected result URLs with the contents leaf after checking its schema. No good hits? Broaden the query, drop domain filters, or try --type deep.',
+        };
+    },
+    render: (result) => {
+        const query = result['query'];
+        const results = result['results'];
+        const followUp = result['follow_up'];
+        if (results.length === 0) {
+            return `No results for "${query}".\n\n${followUp}`;
+        }
+        const lines = [`${results.length} results for "${query}":`, ''];
+        results.forEach((r, i) => {
+            lines.push(renderResult(r, i + 1));
+            lines.push('');
+        });
+        lines.push(followUp);
+        return lines.join('\n');
+    },
+});

package/dist/commands/search.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerSearch(): BranchDef;

package/dist/commands/search.js

@@ -0,0 +1,24 @@
+// `crtr search` subtree — web search for agents, backed by the Exa API. Three
+// leaves: web (find pages), answer (one grounded cited answer), contents
+// (extract from URLs you already have). API key resolves from EXA_API_KEY or
+// ~/.crouter/exa.key (see ./search/exa.ts).
+import { defineBranch } from '../core/command.js';
+import { webLeaf } from './search/web.js';
+import { answerLeaf } from './search/answer.js';
+import { contentsLeaf } from './search/contents.js';
+export function registerSearch() {
+    return defineBranch({
+        name: 'search',
+        rootEntry: {
+            concept: 'web search for agents — find pages, get grounded answers, extract page content (Exa)',
+            desc: 'search the web, answer a question with citations, or extract content from known URLs',
+            useWhen: 'you need information from the live web — current events, documentation, sources, facts beyond your training. Use web for relevant pages with excerpts, answer for one synthesized cited answer, and contents for clean text from URLs you already hold. Needs an Exa API key (EXA_API_KEY or ~/.crouter/exa.key).',
+        },
+        help: {
+            name: 'search',
+            summary: 'web search via the Exa API — find pages, answer questions with citations, extract page content',
+            model: 'Three leaves split by what you have and what you want. `web` is the default: a query in, ranked pages out with query-relevant highlight excerpts (or full text with --text) — use it for discovery and research. `answer` collapses a question into one synthesized, source-cited answer — use it when you want the conclusion, not a reading list. `contents` does no searching; it extracts cleaned content from URLs you already hold. Highlights are the default content mode everywhere (token-predictable); full text is opt-in and length-capped. Every leaf needs an Exa API key from EXA_API_KEY or ~/.crouter/exa.key.',
+        },
+        children: [webLeaf, answerLeaf, contentsLeaf],
+    });
+}

package/dist/commands/surface.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerSurface(): BranchDef;

package/dist/commands/surface.js

@@ -0,0 +1,43 @@
+// `crtr surface` — the screen-facing entrypoints.
+//
+// Groups the four surface families under one canonical noun: standalone tmux
+// views, live broker attachment, the split editor workspace, and the browser
+// shell.
+import { defineBranch } from '../core/command.js';
+import { registerView } from './view.js';
+import { registerWorkspace } from './workspace.js';
+import { registerWeb } from '../clients/web/web-cmd.js';
+import { registerAttach } from '../clients/attach/attach-cmd.js';
+function namespaceForSurface(node) {
+    node.help.name = `surface ${node.help.name}`;
+    if (node.kind === 'branch') {
+        node.description = node.rootEntry?.concept ?? node.description ?? '';
+        node.whenToUse = node.rootEntry?.useWhen ?? node.whenToUse ?? '';
+        for (const child of node.children)
+            namespaceForSurface(child);
+    }
+}
+export function registerSurface() {
+    const view = registerView();
+    const attach = registerAttach();
+    const workspace = registerWorkspace();
+    const web = registerWeb();
+    for (const child of [view, attach, workspace, web]) {
+        child.tier = 'important';
+        namespaceForSurface(child);
+    }
+    return defineBranch({
+        name: 'surface',
+        rootEntry: {
+            concept: 'screen-facing surfaces — tmux views, live broker attachment, the editor workspace, and the browser shell',
+            desc: 'open and manage screen-facing surfaces',
+            useWhen: 'you need a UI or presentation surface rather than a node, document, or graph operation — standalone tmux views, live broker attachment, the split workspace layout, or the browser-hosted shell',
+        },
+        help: {
+            name: 'surface',
+            summary: 'open and manage screen-facing surfaces',
+            model: 'Four entrypoints share the screen-facing space. `view` hosts a standalone raw-ANSI surface in tmux; `attach` connects this pane to a node broker; `workspace` lays out the left rail plus chat pane in one tmux window; `web` serves the browser shell and broker relay. Pick the family by host and layout, then choose the leaf that matches the action.',
+        },
+        children: [view, attach, workspace, web],
+    });
+}

package/dist/commands/sys/__tests__/sync-import.test.js

@@ -0,0 +1,72 @@
+// Regression: `crtr sys sync` is the one-shot migration path from legacy
+// Agent Skill bundles into crouter memory docs. The hard cut removes SKILL.md as
+// an active guidance surface, but must keep the converter.
+//
+// Run: node --import tsx/esm --test src/commands/sys/__tests__/sync-import.test.ts
+import { afterEach, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sysSyncLeaf } from '../sync.js';
+import { parseFrontmatterGeneric } from '../../../core/frontmatter.js';
+let home;
+let prevHome;
+beforeEach(() => {
+    prevHome = process.env.HOME;
+    home = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-'));
+    process.env.HOME = home;
+});
+afterEach(() => {
+    if (prevHome === undefined)
+        delete process.env.HOME;
+    else
+        process.env.HOME = prevHome;
+    rmSync(home, { recursive: true, force: true });
+});
+test('imports a SKILL.md bundle as a plain crouter memory doc', async () => {
+    const sourceRoot = join(home, '.claude', 'skills');
+    const bundle = join(sourceRoot, 'demo-skill');
+    mkdirSync(bundle, { recursive: true });
+    writeFileSync(join(bundle, 'SKILL.md'), '---\nname: Demo Skill\ndescription: Handles demos. Use when demo work appears.\n---\n\n# Demo\n\nDo the demo.\n', 'utf8');
+    const result = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user' });
+    assert.equal(result?.imported, 1);
+    const target = join(home, '.crouter', 'memory', 'demo-skill.md');
+    assert.equal(existsSync(target), true);
+    const parsed = parseFrontmatterGeneric(readFileSync(target, 'utf8'));
+    assert.equal(parsed.data?.kind, 'knowledge');
+    assert.equal(parsed.data?.['system-prompt-visibility'], 'preview');
+    assert.equal(parsed.data?.['file-read-visibility'], 'none');
+    assert.equal(parsed.data?.['when-and-why-to-read'], 'When demo work appears, this knowledge should be read because handles demos.');
+    assert.match(parsed.body, /Do the demo\./);
+});
+test('skips generated crtr boot skills instead of importing them', async () => {
+    const bundle = join(home, '.pi', 'agent', 'skills', 'crtr-skills');
+    mkdirSync(bundle, { recursive: true });
+    writeFileSync(join(bundle, 'SKILL.md'), '---\nname: crtr-skills\n---\n\n<!-- crtr-boot-skill v2 -->\n', 'utf8');
+    const result = await sysSyncLeaf.run({ source: bundle, scope: 'user' });
+    assert.equal(result?.imported, 0);
+    assert.equal(result?.skipped, 1);
+    assert.equal(existsSync(join(home, '.crouter', 'memory', 'crtr-skills.md')), false);
+});
+test('permanently ignores selected SKILL.md bundles', async () => {
+    const sourceRoot = join(home, '.claude', 'skills');
+    const bundle = join(sourceRoot, 'ignored-skill');
+    mkdirSync(bundle, { recursive: true });
+    writeFileSync(join(bundle, 'SKILL.md'), '---\nname: Ignored Skill\ndescription: Ignore me. Use when testing ignores.\n---\n\n# Ignore\n', 'utf8');
+    const ignored = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user', ignore: true });
+    assert.equal(ignored?.ignored, 1);
+    assert.equal(existsSync(join(home, '.crouter', 'skill-import-ignore.json')), true);
+    const dry = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user', dryRun: true });
+    assert.equal(dry?.wouldImport, 0);
+    assert.equal((dry?.results).length, 0);
+    const shown = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user', dryRun: true, includeIgnored: true });
+    assert.equal(shown?.ignored, 1);
+    assert.equal((shown?.results)[0].status, 'ignored');
+    const wouldIgnore = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user', dryRun: true, ignore: true });
+    assert.equal(wouldIgnore?.wouldIgnore, 1);
+    assert.equal((wouldIgnore?.results)[0].status, 'would-ignore');
+    const rendered = sysSyncLeaf.render?.(wouldIgnore);
+    assert.notEqual(rendered, undefined);
+    assert.match(rendered, /would ignore/);
+});

package/dist/commands/sys/config.js

@@ -12,7 +12,17 @@ const TOP_LEVEL_KEYS = new Set([
     'plugins',
     'max_panes_per_window',
     'canvasNav',
+    'modelLadders',
+    'personaStrengths',
 ]);
+const MODEL_PROVIDERS = new Set(['anthropic', 'openai']);
+const MODEL_STRENGTHS = new Set(['ultra', 'strong', 'medium', 'light']);
+function isModelProvider(value) {
+    return MODEL_PROVIDERS.has(value);
+}
+function isModelStrength(value) {
+    return MODEL_STRENGTHS.has(value);
+}
 function getNestedValue(obj, key) {
     const parts = key.split('.');
     let current = obj;
@@ -32,7 +42,7 @@ function parseConfigValue(raw) {
         return parseInt(raw, 10);
     return raw;
 }
-function setNestedValue(cfg, key, value) {
+function setNestedValue(cfg, key, rawValue, value) {
     const parts = key.split('.');
     const topKey = parts[0];
     if (!TOP_LEVEL_KEYS.has(topKey)) {
@@ -65,11 +75,50 @@ function setNestedValue(cfg, key, value) {
         // record tables are edited directly in config.json (run `crtr sys config
         // path` to locate it).
         if (key === 'canvasNav.prefixKey') {
-            cfg.canvasNav.prefixKey = String(value);
+            cfg.canvasNav.prefixKey = rawValue;
             return;
         }
         throw usage(`canvasNav.${parts.slice(1).join('.') || '*'} is a record table — edit config.json directly (run \`crtr sys config path\`). Only canvasNav.prefixKey is settable via this command.`);
     }
+    if (topKey === 'modelLadders') {
+        if (parts.length === 2 && parts[1] === 'defaultProvider') {
+            if (!isModelProvider(rawValue)) {
+                throw usage(`modelLadders.defaultProvider must be anthropic or openai`);
+            }
+            cfg.modelLadders.defaultProvider = rawValue;
+            return;
+        }
+        if (parts.length === 3) {
+            const provider = parts[1];
+            const strength = parts[2];
+            if (!isModelProvider(provider)) {
+                throw usage(`modelLadders provider must be anthropic or openai`);
+            }
+            if (!isModelStrength(strength)) {
+                throw usage(`modelLadders strength must be ultra, strong, medium, or light`);
+            }
+            if (rawValue.trim() === '') {
+                throw usage(`modelLadders.${provider}.${strength} cannot be empty`);
+            }
+            cfg.modelLadders[provider][strength] = rawValue;
+            return;
+        }
+        throw usage(`unsupported key path for set: ${key}`);
+    }
+    if (topKey === 'personaStrengths') {
+        if (parts.length !== 2) {
+            throw usage(`unsupported key path for set: ${key}`);
+        }
+        const persona = parts[1];
+        if (persona.trim() === '' || persona !== persona.trim()) {
+            throw usage(`personaStrengths.<persona-kind> must be a non-empty persona kind without leading or trailing whitespace`);
+        }
+        if (!isModelStrength(rawValue)) {
+            throw usage(`personaStrengths.<persona-kind> must be ultra, strong, medium, or light`);
+        }
+        cfg.personaStrengths[persona] = rawValue;
+        return;
+    }
     if (parts.length === 1) {
         cfg[topKey] = value;
         return;
@@ -87,13 +136,13 @@ function setNestedValue(cfg, key, value) {
 const configGet = defineLeaf({
     name: 'get',
     description: 'read a config value by key',
-    whenToUse: 'you want to read a single config value by its dotted key — the current auto_update policy, max_panes_per_window, the canvasNav prefix key — optionally from a specific scope. Use sys config set instead to change a value, sys config path to locate the file for hand-editing.',
+    whenToUse: 'you want to read a single config value by its dotted key — the current auto_update policy, max_panes_per_window, the canvasNav prefix key, model ladders, or persona strengths — optionally from a specific scope. Use sys config set instead to change a value, sys config path to locate the file for hand-editing.',
     help: {
         name: 'sys config get',
         summary: 'read a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window, canvasNav (read whole; edit canvasNav.prefixBinds/graphBinds in config.json directly).' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Scope to read from. Default: user.' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window, canvasNav, modelLadders, personaStrengths (read whole; edit canvasNav.prefixBinds/graphBinds in config.json directly).' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to read from. Default: user.' },
         ],
         output: [
             { name: 'key', type: 'string', required: true, constraint: 'Echo of input key.' },
@@ -117,12 +166,12 @@ const configGet = defineLeaf({
 const configSet = defineLeaf({
     name: 'set',
     description: 'write a config value by key',
-    whenToUse: 'you want to change a crtr setting — flip auto_update.crtr or auto_update.content to notify, apply, or off, raise max_panes_per_window, rebind canvasNav.prefixKey — written to the user or project scope. Use sys config get instead to read a value; the canvasNav record tables are not settable here, so edit config.json directly (sys config path) for those.',
+    whenToUse: 'you want to change a crtr setting — flip auto_update.crtr or auto_update.content to notify, apply, or off, raise max_panes_per_window, rebind canvasNav.prefixKey, set model ladders, or map persona strengths — written to the user or project scope. Use sys config get instead to read a value; the canvasNav record tables are not settable here, so edit config.json directly (sys config path) for those.',
     help: {
         name: 'sys config set',
         summary: 'write a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window, canvasNav.prefixKey. The canvasNav.prefixBinds/graphBinds record tables are not settable here — edit config.json directly (`crtr sys config path`).' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window, canvasNav.prefixKey, modelLadders.defaultProvider, modelLadders.<anthropic|openai>.<ultra|strong|medium|light>, personaStrengths.<persona-kind>. The canvasNav.prefixBinds/graphBinds record tables are not settable here — edit config.json directly (`crtr sys config path`).' },
             { kind: 'flag', name: 'value', type: 'string', required: true, constraint: 'value VALUE — string, required. Stored as-is if quoted; coerced to number or boolean when unambiguous.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user.' },
         ],
@@ -141,7 +190,7 @@ const configSet = defineLeaf({
         // Flags are stringly-typed; coerce to number or boolean when unambiguous
         const parsed = parseConfigValue(rawValue);
         const cfg = readConfig(scope);
-        setNestedValue(cfg, key, parsed);
+        setNestedValue(cfg, key, rawValue, parsed);
         writeConfig(scope, cfg);
         // Read back the written value for echo
         const written = getNestedValue(cfg, key);
@@ -191,10 +240,10 @@ const configPath = defineLeaf({
 export const configBranch = defineBranch({
     name: 'config',
     description: 'read and write configuration',
-    whenToUse: 'inspecting or changing crtr settings — read a value with sys config get, change one with sys config set (auto_update policy, max_panes_per_window, canvasNav.prefixKey), or locate config.json with sys config path to hand-edit the record tables set cannot reach.',
+    whenToUse: 'inspecting or changing crtr settings — read a value with sys config get, change one with sys config set (auto_update policy, max_panes_per_window, canvasNav.prefixKey, model ladders, persona strengths), or locate config.json with sys config path to hand-edit the record tables set cannot reach.',
     help: {
         name: 'sys config',
-        summary: 'read and write crtr configuration',
+        summary: 'read and write crtr configuration, including model ladders and persona strengths',
     },
     children: [configGet, configSet, configPath],
 });

package/dist/commands/sys/doctor.js

@@ -5,6 +5,9 @@ import { scopeRoot, listScopes, marketplacesDir, pluginsDir } from '../../core/s
 import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
 import { pathExists, listDirs, removePath } from '../../core/fs-utils.js';
 import { lsRemote } from '../../core/git.js';
+import { listNodes } from '../../core/canvas/index.js';
+import { activeFaultForDisplay } from '../../core/canvas/render.js';
+import { readFault } from '../../core/runtime/fault.js';
 function pass(scope, name, message) {
     return { scope, name, status: 'pass', message };
 }
@@ -41,6 +44,8 @@ function applyRemediation(rem) {
                 removePath(rem.path);
                 return true;
             }
+            case 'human_action':
+                return false;
             default:
                 return false;
         }
@@ -49,6 +54,51 @@ function applyRemediation(rem) {
         return false;
     }
 }
+function faultMessage(fault) {
+    const parts = [
+        `${fault.link} ${fault.kind}`,
+        `disposition=${fault.retry.disposition}`,
+        typeof fault.retry.attempt === 'number' && typeof fault.retry.max === 'number' ? `attempt=${fault.retry.attempt}/${fault.retry.max}` : undefined,
+        typeof fault.retry.nextAt === 'string' ? `nextAt=${fault.retry.nextAt}` : undefined,
+    ].filter((part) => part !== undefined);
+    return parts.join(' · ');
+}
+function faultRemediation(fault) {
+    const actionByKind = {
+        connection: 'restore connectivity',
+        'rate-limit': 'wait for the rate limit to clear',
+        overloaded: 'wait for load to drop',
+        auth: 're-authenticate',
+        protocol: 'fix the protocol mismatch',
+        other: 'fix the underlying issue',
+    };
+    const progress = fault.retry.disposition === 'auto'
+        ? fault.retry.by === 'client'
+            ? 'client redialing'
+            : typeof fault.retry.attempt === 'number' && typeof fault.retry.max === 'number'
+                ? `auto-retrying, attempt ${fault.retry.attempt}/${fault.retry.max}`
+                : 'auto-retrying'
+        : fault.retry.disposition === 'fatal'
+            ? 'parked fatal'
+            : 'manual';
+    return {
+        kind: 'human_action',
+        description: `${actionByKind[fault.kind]}; ${progress}; inspect ${fault.logPath}`,
+        logPath: fault.logPath,
+    };
+}
+function runFaultChecks() {
+    const results = [];
+    for (const node of listNodes()) {
+        const fault = activeFaultForDisplay(node, readFault(node.node_id));
+        if (fault === null)
+            continue;
+        const name = `fault:${node.node_id}:${fault.link}`;
+        const remediation = faultRemediation(fault);
+        results.push(failCheck('canvas', name, faultMessage(fault), remediation));
+    }
+    return results;
+}
 function runChecksForScope(scope, opts) {
     const results = [];
     const root = scopeRoot(scope);
@@ -198,14 +248,14 @@ export const sysDoctorLeaf = defineLeaf({
             { kind: 'flag', name: 'remote', type: 'bool', required: false, constraint: 'Check git remotes with ls-remote (slow — makes network calls).' },
         ],
         output: [
-            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path. Sorted by scope then name.' },
+            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action. Sorted by scope then name.' },
             { name: 'ok', type: 'boolean', required: true, constraint: 'True when no unresolved fail checks remain.' },
         ],
         outputKind: 'object',
         effects: [
             'Read-only unless --fix is passed.',
-            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories.',
-            'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys) so callers can apply it directly without --fix.',
+            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings stay read-only.',
+            'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys, or a human_action with logPath) so callers can apply it directly without --fix.',
         ],
     },
     run: async (input) => {
@@ -218,10 +268,12 @@ export const sysDoctorLeaf = defineLeaf({
             const results = runChecksForScope(scope, { fix, remote });
             allResults.push(...results);
         }
+        allResults.push(...runFaultChecks());
         // Sort by scope then name (mirrors old printResults grouping)
+        const scopeOrder = { user: 0, project: 1, builtin: 2, canvas: 3 };
         allResults.sort((a, b) => {
             if (a.scope !== b.scope)
-                return a.scope.localeCompare(b.scope);
+                return scopeOrder[a.scope] - scopeOrder[b.scope];
             return a.name.localeCompare(b.name);
         });
         const ok = !allResults.some((r) => r.status === 'fail' && r.fixed !== true);

package/dist/commands/sys/prompt-review.d.ts

@@ -0,0 +1 @@
+export declare const promptReviewLeaf: import("../../core/command.js").LeafDef;