@crouton-kit/crouter 0.3.26 → 0.3.28

package/dist/commands/human/prompts.js

@@ -2,7 +2,7 @@ import { defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { spawnNode } from '../../core/runtime/nodes.js';
 import { interactionDir } from '../../core/artifact.js';
-import { isInTmux } from '../../core/spawn.js';
+import { tmuxServerReachable } from '../../core/spawn.js';
 import { mkdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
@@ -211,7 +211,7 @@ export const humanNotify = defineLeaf({
         const rc = { mode: 'notify' };
         atomicWriteJson(join(idir, 'run.json'), rc);
         let shown = false;
-        if (isInTmux()) {
+        if (tmuxServerReachable()) {
             shown = detachHumanTui(idir, cwd).status === 'spawned';
         }
         return { shown, dir: idir };
@@ -256,7 +256,7 @@ export const humanShow = defineLeaf({
         if (paneId !== undefined) {
             return { pane_id: paneId, reason: null };
         }
-        const reason = isInTmux()
+        const reason = tmuxServerReachable()
             ? 'renderer unavailable (termrender/uv missing)'
             : 'not in tmux';
         return { pane_id: null, reason };

package/dist/commands/human/queue.d.ts

@@ -1,3 +1,20 @@
+/** Deliver-back + reap an interaction whose answer is on disk but was never
+ *  delivered. The detached `_run` worker's `pushFinal` is normally the SOLE
+ *  deliver-back + reap step; when it never ran (e.g. a broker asker pre-fix, or
+ *  a human draining via `crtr human inbox`, which writes response.json directly
+ *  and never calls pushFinal), the answer strands and the bridge node leaks.
+ *
+ *  Idempotent and self-gating: a no-op unless the bridge node is still LIVE
+ *  (active|idle) AND its interaction is resolved on disk — so it never
+ *  double-delivers an interaction the `_run` worker already finalized (pushFinal
+ *  flips status=done). Reconstructs the same pushFinal body `_run` would have
+ *  emitted, per mode; a canceled-on-disk response reaps the node without
+ *  delivering a result (mirrors `human cancel`). Returns true iff it acted. */
+export declare function finalizeResolvedInteraction(jobId: string): Promise<boolean>;
+/** Sweep every interaction under the cwd's interactions root and deliver-back +
+ *  reap any that are answered-but-undelivered (see finalizeResolvedInteraction).
+ *  Interaction dir names ARE the bridge node ids. Returns how many it healed. */
+export declare function healStrandedInteractions(cwd: string): Promise<number>;
 export declare const humanInbox: import("../../core/command.js").LeafDef;
 export declare const humanList: import("../../core/command.js").LeafDef;
 export declare const humanCancel: import("../../core/command.js").LeafDef;

package/dist/commands/human/queue.js

@@ -6,12 +6,109 @@ import { paginate } from '../../core/pagination.js';
 import { getNode, subscribersOf } from '../../core/canvas/index.js';
 import { transition } from '../../core/runtime/lifecycle.js';
 import { appendInbox } from '../../core/feed/inbox.js';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { inbox, scanInbox, parseDeck, deckPath, responsePath, isResolved, atomicWriteJson, ask, launchReview, readJson, display, } from '@crouton-kit/humanloop';
 import { killPane } from './shared.js';
 // ---------------------------------------------------------------------------
+// stranded-answer healing
+// ---------------------------------------------------------------------------
+/** A deterministic one-line-per-interaction summary, mirroring humanloop's
+ *  `<id>: <option>[ — <freetext>]` shape. Used when reconstructing a
+ *  ResolutionEnvelope from a bare on-disk response.json (which stores only
+ *  `{responses, completedAt}`), so a healed deliver-back reads like the live one. */
+function summarizeResponses(responses) {
+    return responses
+        .map((r) => {
+        const opt = r.selectedOptionId ?? '';
+        const ft = typeof r.freetext === 'string' && r.freetext.trim() !== '' ? ` — ${r.freetext.trim()}` : '';
+        return `${r.id}: ${opt}${ft}`;
+    })
+        .join('\n');
+}
+/** Deliver-back + reap an interaction whose answer is on disk but was never
+ *  delivered. The detached `_run` worker's `pushFinal` is normally the SOLE
+ *  deliver-back + reap step; when it never ran (e.g. a broker asker pre-fix, or
+ *  a human draining via `crtr human inbox`, which writes response.json directly
+ *  and never calls pushFinal), the answer strands and the bridge node leaks.
+ *
+ *  Idempotent and self-gating: a no-op unless the bridge node is still LIVE
+ *  (active|idle) AND its interaction is resolved on disk — so it never
+ *  double-delivers an interaction the `_run` worker already finalized (pushFinal
+ *  flips status=done). Reconstructs the same pushFinal body `_run` would have
+ *  emitted, per mode; a canceled-on-disk response reaps the node without
+ *  delivering a result (mirrors `human cancel`). Returns true iff it acted. */
+export async function finalizeResolvedInteraction(jobId) {
+    const node = getNode(jobId);
+    if (node === null)
+        return false;
+    if (node.status !== 'active' && node.status !== 'idle')
+        return false;
+    const idir = interactionDir(jobId, node.cwd);
+    if (!isResolved(idir))
+        return false;
+    const rc = readJson(join(idir, 'run.json'));
+    if (rc === null)
+        return false;
+    const resp = readJson(responsePath(idir));
+    if (resp === null)
+        return false;
+    // Canceled out-of-band (a raw canceled response.json, not via `human cancel`):
+    // there is no answer to deliver — just reap the node and tell waiting
+    // subscribers no answer is coming, the same quiet deferred note `human cancel`
+    // emits. (`finalize` is legal from active|idle; the status guard above holds.)
+    if (resp['canceled'] === true) {
+        transition(jobId, 'finalize');
+        const note = typeof resp['reason'] === 'string' && resp['reason'] !== '' ? ` — ${resp['reason']}` : '';
+        for (const sub of subscribersOf(jobId)) {
+            appendInbox(sub.node_id, {
+                from: jobId,
+                tier: 'deferred',
+                kind: 'message',
+                label: `human interaction ${jobId} canceled — no answer is coming${note}`,
+                data: { body: `The human interaction ${jobId} was canceled${note}. No response will arrive.` },
+            });
+        }
+        return true;
+    }
+    const responses = resp['responses'] ?? [];
+    const completedAt = resp['completedAt'] ?? new Date().toISOString();
+    const summary = summarizeResponses(responses);
+    if (rc.mode === 'approve') {
+        const sel = responses.find((r) => r.id === rc.approve_iid)?.selectedOptionId;
+        await pushFinal(jobId, JSON.stringify({ approved: sel === 'yes', summary, responses, responsePath: responsePath(idir), completedAt }));
+    }
+    else {
+        // ask (and any other answered deck): the full ResolutionEnvelope shape.
+        const env = {
+            summary,
+            responsePath: responsePath(idir),
+            schema: 'humanloop.response/v2',
+            responses,
+            completedAt,
+        };
+        await pushFinal(jobId, JSON.stringify(env));
+    }
+    return true;
+}
+/** Sweep every interaction under the cwd's interactions root and deliver-back +
+ *  reap any that are answered-but-undelivered (see finalizeResolvedInteraction).
+ *  Interaction dir names ARE the bridge node ids. Returns how many it healed. */
+export async function healStrandedInteractions(cwd) {
+    const root = interactionsRoot(cwd);
+    if (!existsSync(root))
+        return 0;
+    let healed = 0;
+    for (const ent of readdirSync(root, { withFileTypes: true })) {
+        if (!ent.isDirectory())
+            continue;
+        if (await finalizeResolvedInteraction(ent.name))
+            healed++;
+    }
+    return healed;
+}
+// ---------------------------------------------------------------------------
 // inbox (human-invoked, blocking)
 // ---------------------------------------------------------------------------
 export const humanInbox = defineLeaf({
@@ -23,13 +120,23 @@ export const humanInbox = defineLeaf({
         summary: 'interactively drain pending interactions at your own terminal',
         params: [],
         inputNote: 'No input. Run this at a human terminal — it blocks until the backlog is drained or you quit.',
-        output: [{ name: 'drained', type: 'boolean', required: true, constraint: 'True once the loop returns.' }],
+        output: [
+            { name: 'drained', type: 'boolean', required: true, constraint: 'True once the loop returns.' },
+            { name: 'delivered', type: 'integer', required: true, constraint: 'How many answered-but-undelivered interactions were delivered back to their askers and reaped.' },
+        ],
         outputKind: 'object',
-        effects: ['Resolves pending interactions in the per-project interactions root via the TUI.'],
+        effects: [
+            'Resolves pending interactions in the per-project interactions root via the TUI.',
+            'Delivers any answered-but-undelivered interaction back to its asking node and reaps the bridge node (the deliver-back the detached _run worker would have done).',
+        ],
     },
     run: async () => {
         await inbox([interactionsRoot(process.cwd())]);
-        return { drained: true };
+        // humanloop's inbox() writes response.json but never calls pushFinal — so a
+        // deck drained here would strand (no answer-back, leaked bridge node). Heal
+        // every resolved-but-live interaction: deliver its answer to the asker + reap.
+        const delivered = await healStrandedInteractions(process.cwd());
+        return { drained: true, delivered };
     },
 });
 // ---------------------------------------------------------------------------

package/dist/commands/memory/__tests__/lint-schema.test.js

@@ -9,6 +9,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { lintSubstrateSchema } from '../lint.js';
 const ROUTING = 'When you are X, this reference should be read because Y';
+const RUNGS = { 'system-prompt-visibility': 'name', 'file-read-visibility': 'none' };
 test('lint rejects a doc still carrying the retired `when` key', () => {
     const err = lintSubstrateSchema({ kind: 'reference', when: 'when X' });
     assert.ok(err !== null, 'old-shape `when` must produce a finding');
@@ -25,5 +26,27 @@ test('lint rejects a substrate doc missing the merged routing field', () => {
     assert.match(err, /when-and-why-to-read/);
 });
 test('lint accepts the merged new-shape frontmatter', () => {
-    assert.equal(lintSubstrateSchema({ kind: 'reference', 'when-and-why-to-read': ROUTING }), null);
+    assert.equal(lintSubstrateSchema({ kind: 'reference', 'when-and-why-to-read': ROUTING, ...RUNGS }), null);
+});
+// Visibility is a required, case-by-case authoring call — there is no kind
+// default. lint must reject a doc that omits either rung (the runtime parser
+// silently floors a missing rung to `none`, which is exactly the tolerance this
+// gate exists to catch at authoring time).
+test('lint rejects a substrate doc missing system-prompt-visibility', () => {
+    const err = lintSubstrateSchema({
+        kind: 'reference',
+        'when-and-why-to-read': ROUTING,
+        'file-read-visibility': 'none',
+    });
+    assert.ok(err !== null, 'a missing rung must produce a finding');
+    assert.match(err, /missing system-prompt-visibility/);
+});
+test('lint rejects a substrate doc missing file-read-visibility', () => {
+    const err = lintSubstrateSchema({
+        kind: 'reference',
+        'when-and-why-to-read': ROUTING,
+        'system-prompt-visibility': 'name',
+    });
+    assert.ok(err !== null, 'a missing rung must produce a finding');
+    assert.match(err, /missing file-read-visibility/);
 });

package/dist/commands/memory/lint.d.ts

@@ -1,8 +1,9 @@
 /** Schema checks for a doc living in a substrate memory dir: a memory store
  *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
- *  error here (elsewhere it just means "not a substrate doc"). Rung and gate
- *  values are checked RAW — the runtime parser silently falls back to kind
- *  defaults / inert gates, which is exactly the silent tolerance this lint
- *  exists to catch at authoring time. */
+ *  error here (elsewhere it just means "not a substrate doc"). Both rungs are
+ *  REQUIRED — there is no kind default to lean on, so a missing rung is an
+ *  authoring error. Rung and gate values are checked RAW — the runtime parser
+ *  silently falls back to the neutral floor / inert gates, which is exactly the
+ *  silent tolerance this lint exists to catch at authoring time. */
 export declare function lintSubstrateSchema(fm: Record<string, unknown> | null): string | null;
 export declare const lintLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/lint.js

@@ -17,10 +17,11 @@ const VALID_RUNGS = [...RUNGS, 'always'];
 const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
 /** Schema checks for a doc living in a substrate memory dir: a memory store
  *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
- *  error here (elsewhere it just means "not a substrate doc"). Rung and gate
- *  values are checked RAW — the runtime parser silently falls back to kind
- *  defaults / inert gates, which is exactly the silent tolerance this lint
- *  exists to catch at authoring time. */
+ *  error here (elsewhere it just means "not a substrate doc"). Both rungs are
+ *  REQUIRED — there is no kind default to lean on, so a missing rung is an
+ *  authoring error. Rung and gate values are checked RAW — the runtime parser
+ *  silently falls back to the neutral floor / inert gates, which is exactly the
+ *  silent tolerance this lint exists to catch at authoring time. */
 export function lintSubstrateSchema(fm) {
     if (fm === null)
         return 'missing frontmatter: a memory store doc requires `kind: skill|reference|preference`';
@@ -38,7 +39,10 @@ export function lintSubstrateSchema(fm) {
     }
     for (const field of RUNG_FIELDS) {
         const v = fm[field];
-        if (v !== undefined && (typeof v !== 'string' || !VALID_RUNGS.includes(v))) {
+        if (v === undefined) {
+            return `missing ${field}: choose a rung explicitly (${RUNGS.join('|')}) — there is no kind default`;
+        }
+        if (typeof v !== 'string' || !VALID_RUNGS.includes(v)) {
             return `invalid ${field}: ${JSON.stringify(v)} (expected ${RUNGS.join('|')})`;
         }
     }

package/dist/commands/memory/write.js

@@ -10,13 +10,21 @@ export const writeLeaf = defineLeaf({
     help: {
         name: 'memory write',
         summary: 'create or update memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
+        guide: 'The body is the easy part; the craft is ROUTING — every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, forever, so default each rung DOWN.\n\n' +
+            'Pick the kind. skill = how to DO something (a repeatable procedure/playbook); reference = what is TRUE or how something WORKS (a fact about the user, a system\u2019s behavior, code docs); preference = how to BEHAVE (a directive, a standing correction). The test that splits the close pair: does it DIRECT behavior ("always lint after authoring" \u2192 preference) or INFORM the world-model ("Silas likes chicken", "the daemon never reloads dist/" \u2192 reference)? A correction yields a preference, a learned fact a reference, a repeatable procedure a skill.\n\n' +
+            'Set the rungs \u2014 BOTH --system-prompt-visibility (boot) and --file-read-visibility (on-read) are REQUIRED on create. There is no default: the right rung is a case-by-case call, never a function of kind. The ladder, lowest to highest: `none` for niche docs almost nothing should pull into context; `name` for the common case \u2014 references and skills that are relatively uncommon but an agent (or the user, by name) may reach for; `preview` for docs important enough that their routing line is worth its token cost every session (preferences usually land here); `content` (full body injected) for a doc that would be `preview` except its body is already so short you may as well inline it whole. `content` is rare \u2014 when a `content` doc grows past a bullet or two, downgrade it to `preview`. Each axis is independent: usually one carries a real rung and the other is `none` (see the hook paragraph next).\n\n' +
+            'Choose the hook \u2014 boot vs file-read. There are exactly two moments a doc can surface. Behavior and procedure (preferences, skills) are relevant whatever file is open \u2192 surface at boot. Knowledge about code (references) belongs NEXT TO the code: put the file in that directory\u2019s .crouter/memory/ and it fires positionally when files there are read, costing nothing at boot. The exception that matters: a reference about a PERSON or PROCESS has no code directory to anchor to, so on-read triggering is meaningless \u2014 set --system-prompt-visibility preview so its routing line surfaces at boot instead.\n\n' +
+            'Write the routing line (--when-and-why-to-read) FIRST, before storing anything: "When <circumstance the agent is in>, this <kind> should be read because <what the read buys>." The test: can a stranger mid-task decide from that one line alone whether to spend the read? If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user ONE sharp question instead of improvising. ("Remember I like chicken" routes cleanly \u2192 food/meal decisions; "be careful with the API" does not \u2192 which API, careful how, against what failure?) And NEVER paraphrase the advice in the routing line \u2014 a preview that gives away the gist makes every future agent skip the real read. BAD: "\u2026because it carries the placement policy \u2014 -h first, memory only for dev-mode material." GOOD: "\u2026because it carries the standing placement policy."\n\n' +
+            'Find before write. `crtr memory find <topic>` first; grow ONE doc per recurring circumstance rather than minting near-duplicates \u2014 extend `food-preferences`, do not create `likes-chicken`. Group related docs with path names (area/topic). Do not store what is already recorded (code structure, git history, CLAUDE.md) or what only matters to this conversation.\n\n' +
+            'Body: write for a STRANGER \u2014 a future session that shares none of this conversation. State current truth, not the history of getting there (no "as discussed"). Keep the reasoning behind a rule and cut everything else; dense beats complete, since every line costs a mid-task reader.\n\n' +
+            'Gate (--gate, optional): a predicate making the doc eligible only for nodes whose own config matches (e.g. `{ mode: orchestrator }` or `{ orchestration.depth: { gte: 2 } }`); a failing gate hides it from both hooks but it stays findable by search. Default is no gate \u2014 most docs want exactly that. After authoring, validate with `crtr memory lint`.',
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity (e.g. `topic` or `area/topic`) → memory/<name>.md at the resolved scope. Updated in place if it already exists, otherwise created.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },
             { kind: 'flag', name: 'when-and-why-to-read', type: 'string', required: false, constraint: 'The read-routing line, authored as ONE sentence: "When <circumstance>, this <kind> should be read <because <payoff>>." It states WHEN to read this doc and WHY the read is worth it — read-routing, NEVER a justification of why the content should be obeyed. Rendered verbatim as the preview. Required when creating.' },
             { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form — a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
-            { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help.' },
-            { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document surfaces when it is read off disk.' },
+            { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help. Required when creating — there is no kind default; pick a rung explicitly.' },
+            { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document surfaces when it is read off disk. Required when creating — there is no kind default; pick a rung explicitly.' },
             { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — expression/condition that determines when this document applies.' },
             { kind: 'flag', name: 'applies-to', type: 'string', required: false, constraint: 'Frontmatter applies-to — glob/path scope the document applies to.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user.' },
@@ -48,6 +56,15 @@ export const writeLeaf = defineLeaf({
         if (created && input['whenAndWhyToRead'] === undefined) {
             throw usage(`creating ${name} requires --when-and-why-to-read: one read-routing sentence "When <circumstance>, this ${kind} should be read <because <payoff>>." (rendered verbatim as the preview).`);
         }
+        // CREATE requires BOTH visibility rungs as an explicit, case-by-case call —
+        // there is no kind default to lean on. UPDATE inherits whatever the existing
+        // doc already carries.
+        if (created && input['systemPromptVisibility'] === undefined) {
+            throw usage(`creating ${name} requires --system-prompt-visibility: pick a rung explicitly (none|name|preview|content) — there is no kind default. See \`crtr memory write -h\` for what each rung means.`);
+        }
+        if (created && input['fileReadVisibility'] === undefined) {
+            throw usage(`creating ${name} requires --file-read-visibility: pick a rung explicitly (none|name|preview|content) — there is no kind default. See \`crtr memory write -h\` for what each rung means.`);
+        }
         // In-place update: start from the existing frontmatter (preserving fields
         // not passed this time), then overlay the provided ones. Create: start clean.
         const frontmatter = created

package/dist/commands/memory.js

@@ -20,7 +20,7 @@ export function registerMemory() {
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — skills, references, preferences',
-            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. Append `-h` at any leaf for its full schema.',
+            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc; the dir then renders as one entry at the INDEX\'s rung, and that rung is a ceiling for its whole subtree (`none` hides the dir) — when a doc mysteriously is not surfacing, check its ancestors\' INDEX rungs and its gate. Append `-h` at any leaf for its full schema, and `crtr memory write -h` for the authoring guide.',
         },
         children: [listLeaf, readLeaf, findLeaf, writeLeaf, lintLeaf],
     });

package/dist/commands/sys/feedback.d.ts

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

package/dist/commands/sys/feedback.js

@@ -0,0 +1,163 @@
+// `crtr sys feedback` — file a GitHub issue against the crtr repo when the
+// harness itself misbehaves (a command errors unexpectedly, hangs, churns, or
+// acts contrary to its documented contract). The agent supplies one prose
+// description; everything else (version, node identity, recent activity) is
+// auto-collected and templated into the issue body. gh-less / unauthed hosts
+// fall back to a durable local file so the report is never lost.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { userScopeRoot } from '../../core/scope.js';
+import { getNode, jobDir, readTelemetry } from '../../core/canvas/index.js';
+import { readPackageVersion } from './shared.js';
+/** Canonical repo for crtr harness feedback — feedback is always about the
+ *  tool, regardless of which project the reporting agent is working in. */
+const FEEDBACK_REPO = 'crouton-labs/crouter';
+function collectContext() {
+    const env = process.env;
+    const nodeId = env['CRTR_NODE_ID'] ?? null;
+    let cycle = null;
+    let logTail = [];
+    if (nodeId !== null) {
+        const meta = getNode(nodeId);
+        if (meta !== null && typeof meta.cycles === 'number')
+            cycle = meta.cycles;
+        logTail = readLogTail(nodeId);
+    }
+    const contextTokens = nodeId !== null ? readTelemetry(nodeId).context_tokens ?? null : null;
+    return {
+        version: readPackageVersion(),
+        platform: `${os.platform()} ${os.release()} (${os.arch()})`,
+        nodeId,
+        kind: env['CRTR_KIND'] ?? null,
+        mode: env['CRTR_MODE'] ?? null,
+        lifecycle: env['CRTR_LIFECYCLE'] ?? null,
+        cwd: env['CRTR_NODE_CWD'] ?? process.cwd(),
+        cycle,
+        contextTokens,
+        logTail,
+    };
+}
+/** Last few lines of a node's job/log.jsonl — best-effort, never throws. Each
+ *  line is truncated so a single fat event can't blow up the issue body. */
+function readLogTail(nodeId, count = 15) {
+    try {
+        const path = join(jobDir(nodeId), 'log.jsonl');
+        if (!existsSync(path))
+            return [];
+        return readFileSync(path, 'utf8')
+            .split('\n')
+            .filter((l) => l.trim() !== '')
+            .slice(-count)
+            .map((l) => (l.length > 600 ? l.slice(0, 600) + '…' : l));
+    }
+    catch {
+        return [];
+    }
+}
+function deriveTitle(raw, message) {
+    const explicit = raw !== undefined && raw.trim() !== '' ? raw.trim() : undefined;
+    const base = explicit ?? message.split('\n')[0].trim();
+    const trimmed = base.length > 80 ? base.slice(0, 79) + '…' : base;
+    return `[feedback] ${trimmed}`;
+}
+function buildBody(message, ctx) {
+    const rows = [
+        `| crtr version | \`${ctx.version}\` |`,
+        `| platform | ${ctx.platform} |`,
+    ];
+    if (ctx.nodeId !== null) {
+        rows.push(`| node id | \`${ctx.nodeId}\` |`);
+        rows.push(`| kind / mode / lifecycle | ${ctx.kind ?? '?'} / ${ctx.mode ?? '?'} / ${ctx.lifecycle ?? '?'} |`);
+        if (ctx.cycle !== null)
+            rows.push(`| cycle | ${ctx.cycle} |`);
+        if (ctx.contextTokens !== null)
+            rows.push(`| context tokens | ${ctx.contextTokens.toLocaleString('en-US')} |`);
+    }
+    if (ctx.cwd !== null)
+        rows.push(`| working dir | \`${ctx.cwd}\` |`);
+    const parts = [
+        message.trim(),
+        '',
+        '---',
+        '_Filed via `crtr sys feedback` — context below auto-attached by the harness._',
+        '',
+        '### Environment',
+        '| | |',
+        '|---|---|',
+        ...rows,
+    ];
+    if (ctx.logTail.length > 0) {
+        parts.push('', `### Recent node activity (last ${ctx.logTail.length} log events)`, '```jsonl', ...ctx.logTail, '```');
+    }
+    return parts.join('\n') + '\n';
+}
+/** Persist a report locally when gh can't file it, so nothing is lost. Returns
+ *  the absolute path written. */
+function saveLocally(title, body) {
+    const dir = join(userScopeRoot(), 'feedback');
+    mkdirSync(dir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const path = join(dir, `${ts}.md`);
+    writeFileSync(path, `# ${title}\n\n${body}`, 'utf8');
+    return path;
+}
+export const sysFeedbackLeaf = defineLeaf({
+    name: 'feedback',
+    description: 'report a crtr harness bug as a GitHub issue',
+    whenToUse: 'a crtr command itself misbehaves — it errors unexpectedly, hangs, churns, double-spawns, or acts contrary to its documented contract. NOT for your task work or decisions a human should make (that is `crtr human ask`); this reports the TOOL, filing an issue against the crtr repo with your node context auto-attached.',
+    help: {
+        name: 'sys feedback',
+        summary: 'file a GitHub issue describing a crtr harness bug, with node context auto-attached',
+        params: [
+            {
+                kind: 'positional',
+                name: 'message',
+                required: true,
+                constraint: 'What broke, in your own words: the command you ran, what you expected, what happened instead. Be concrete — this is the only part a human writes; everything else is auto-collected.',
+            },
+            {
+                kind: 'flag',
+                name: 'title',
+                type: 'string',
+                required: false,
+                constraint: 'Issue title. Default: first line of the message, truncated.',
+            },
+        ],
+        output: [
+            { name: 'status', type: 'string', required: true, constraint: 'filed | saved-locally.' },
+            { name: 'url', type: 'string', required: false, constraint: 'Issue URL when status is filed.' },
+            { name: 'path', type: 'string', required: false, constraint: 'Local report path when status is saved-locally (gh unavailable).' },
+            { name: 'error', type: 'string', required: false, constraint: 'Why filing fell back to local save.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            `Opens a public GitHub issue on ${FEEDBACK_REPO} via gh.`,
+            'On gh failure (missing / unauthenticated), writes the report to ~/.crouter/feedback/ instead — never lost.',
+        ],
+    },
+    run: async (input) => {
+        const message = input['message']?.trim();
+        if (message === undefined || message === '') {
+            throw usage('feedback message is required: describe what broke. Run `crtr sys feedback -h`.');
+        }
+        const ctx = collectContext();
+        const title = deriveTitle(input['title'], message);
+        const body = buildBody(message, ctx);
+        const res = spawnSync('gh', ['issue', 'create', '--repo', FEEDBACK_REPO, '--title', title, '--body-file', '-'], { input: body, encoding: 'utf8' });
+        if (res.error === undefined && res.status === 0) {
+            const url = res.stdout.trim().split('\n').filter((l) => l.startsWith('http')).pop() ?? res.stdout.trim();
+            return { status: 'filed', url };
+        }
+        // gh missing, unauthenticated, or the API call failed — persist locally so
+        // the report survives, and tell the agent how to escalate.
+        const reason = res.error !== undefined
+            ? `gh not available: ${res.error.message}`
+            : (res.stderr?.trim() || `gh exited ${res.status}`);
+        const path = saveLocally(title, body);
+        return { status: 'saved-locally', path, error: reason };
+    },
+});

package/dist/commands/sys.js

@@ -3,19 +3,20 @@
 import { defineBranch } from '../core/command.js';
 import { configBranch } from './sys/config.js';
 import { sysDoctorLeaf } from './sys/doctor.js';
+import { sysFeedbackLeaf } from './sys/feedback.js';
 import { sysUpdateLeaf, sysVersionLeaf } from './sys/update.js';
 export function registerSys() {
     return defineBranch({
         name: 'sys',
         rootEntry: {
             concept: 'crtr configuration, diagnostics, and self-management',
-            desc: 'config, doctor, update, version',
+            desc: 'config, doctor, update, version, feedback',
             useWhen: 'managing the crtr installation',
         },
         help: {
             name: 'sys',
             summary: 'crtr system configuration, diagnostics, and self-management',
         },
-        children: [configBranch, sysDoctorLeaf, sysUpdateLeaf, sysVersionLeaf],
+        children: [configBranch, sysDoctorLeaf, sysFeedbackLeaf, sysUpdateLeaf, sysVersionLeaf],
     });
 }

package/dist/core/__tests__/broker-snapshot-history.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/broker-snapshot-history.test.js

@@ -0,0 +1,105 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-snapshot-history.test.ts
+//
+// BUG-REGRESSION (real, observed; surfaced during the crouter-web build, proven
+// broker-side). After a revive resumes a previously-CLOSED pi session, the
+// broker's `welcome` snapshot must present the SAME ordered, complete turn
+// history the persisted session `.jsonl` holds — no omitted or reordered turn.
+//
+// ROOT CAUSE: the broker's `buildSnapshot` served `session.messages`
+// (= `agent.state.messages`, the agent's LIVE in-memory array). pi's recovery
+// paths — auto-retry, context-overflow recovery, and compaction — SLICE the
+// errored/superseded assistant message out of `state.messages` while
+// DELIBERATELY keeping it on disk ("keep in session for history",
+// agent-session.js). So `session.messages` can OMIT a turn the `.jsonl` still
+// holds. crouter-web's static normalizer reads the full ordered history correctly
+// (pi `SessionManager.buildSessionContext` over the file), so a dormant viewer
+// saw the complete turn — then, after a revive, the broker's live welcome
+// snapshot served the diverged (omitted) array. The fix makes the snapshot
+// reconstruct from the persisted session tree (the SAME source the normalizer
+// uses), so live == persisted == disk (single source of truth).
+//
+// This drives the REAL pi SDK offline (no tmux, no broker process, no network) —
+// exactly the seam where the bug lives: it builds a real resumed broker session,
+// SIMULATES pi's retry slice by popping the last assistant off the live
+// `agent.state.messages` (leaving the persisted tree intact), and asserts the
+// snapshot follows the persisted history, not the sliced live array.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../runtime/broker-sdk.js';
+import { buildBrokerSession, snapshotMessages } from '../runtime/broker.js';
+const realEngine = {
+    createAgentSessionServices,
+    createAgentSessionFromServices,
+    SessionManager,
+    VERSION,
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function userMsg(text) {
+    return { role: 'user', content: [{ type: 'text', text }] };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function assistantMsg(text, stopReason = 'stop') {
+    return {
+        role: 'assistant',
+        content: [{ type: 'text', text }],
+        api: 'anthropic-messages',
+        provider: 'anthropic',
+        model: 'sonnet',
+        usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        stopReason,
+        timestamp: Date.now(),
+    };
+}
+test('broker welcome snapshot serves the persisted history, not pi\u2019s sliced live array (omit-on-revive regression)', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-snaphist-'));
+    try {
+        // 1. Build a real persisted session whose tail mimics an auto-retried turn:
+        //    user \u2192 errored assistant (kept on disk) \u2192 retried assistant. This is what
+        //    pi's `.jsonl` holds after a retryable error (529 / overflow / network).
+        const seed = SessionManager.create(cwd);
+        seed.appendMessage(userMsg('q1'));
+        seed.appendMessage(assistantMsg('a1'));
+        seed.appendMessage(userMsg('q2 — triggers a retryable error'));
+        seed.appendMessage(assistantMsg('errored attempt', 'error')); // kept in session for history
+        seed.appendMessage(assistantMsg('retried answer')); // the successful retry
+        const sessionFile = seed.getSessionFile();
+        assert.ok(sessionFile, 'seed session persisted a .jsonl');
+        // The persisted, ordered history a dormant reader / crouter-web normalizer sees.
+        const persisted = SessionManager.open(sessionFile).buildSessionContext().messages;
+        assert.equal(persisted.length, 5, 'disk holds all five messages incl. the errored attempt');
+        // 2. Revive: the broker resumes the closed session via the SERVICES path.
+        const { session } = await buildBrokerSession(realEngine, {
+            cwd,
+            extensionPaths: [],
+            resumeSessionPath: sessionFile,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        });
+        try {
+            assert.equal(session.messages.length, 5, 'at boot the live array == persisted history');
+            // 3. Simulate pi's auto-retry/overflow slice: it removes the errored
+            //    assistant from agent.state.messages but KEEPS it on disk. We reproduce
+            //    that exact mutation on the live array (the persisted tree is untouched).
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const live = session.agent.state.messages;
+            const popped = live.pop(); // drop the last assistant from the LIVE array only
+            assert.equal(popped.role, 'assistant', 'sliced an assistant off the live array');
+            assert.equal(session.messages.length, 4, 'the live array now OMITS the persisted turn');
+            // 4. The bug: pre-fix `buildSnapshot` served `session.messages` (4) \u2014 omitting
+            //    a turn the .jsonl still holds. The fix serves the persisted history (5),
+            //    byte-identical to the normalizer.
+            const snap = snapshotMessages(session);
+            assert.equal(snap.length, persisted.length, 'snapshot presents the COMPLETE persisted history (omit-on-revive regression)');
+            assert.notEqual(snap.length, session.messages.length, 'snapshot does NOT echo the sliced live array');
+            assert.deepEqual(snap, persisted, 'snapshot is byte-identical to the static normalizer\u2019s buildSessionContext (single source of truth)');
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});