@north-light/cli 0.0.0 → 0.3.413

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

@@ -0,0 +1,16 @@
+export interface PageHelpText {
+    brief: string;
+    authoring: string;
+    componentSelection: readonly string[];
+    pageHint: string;
+    rootUseWhen: string;
+    /** `human send` surfaces. HTML is named only where an HTML page can be read. */
+    sendSummary: string;
+    sendWhenToUse: string;
+    pageFlagConstraint: string;
+    stdinConstraint: string;
+    dirConstraint: string;
+}
+/** The one page authoring model for `human -h`. */
+export declare function pageHelpText(pageSurface?: boolean): PageHelpText;
+export declare function resolveMaxPanes(): number;

package/dist/commands/human/shared.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var n=(e,t)=>o(e,"name",{value:t,configurable:!0});import{readConfig as s}from"../../core/config.js";import{CORE_COMPONENT_SELECTION_LINES as a}from"../../core/human/component-docs.js";const i="Write the page for where it is read. A page projected to the inbox is opened away from this conversation by someone who has not followed the work, so it stands alone; an inline page can lean on what the conversation already said. Title names what is being settled, not the topic it sits under. Subtitle is the single line shown beside the title in the inbox list before anything is opened, so it earns the open \u2014 your recommendation and what is at stake \u2014 rather than summarising the page. Content carries only what is needed to decide. Ask only what changes your next step, and offer only options you would actually take; mark the one you would take `recommended` (at most one per question), because a page whose single question is that picker can be answered straight from the inbox list without ever being opened, which is the cheapest answer you can ask for. The reader takes a page one step at a time, so hold each step \u2014 and a stepless page \u2014 to one question or request for action; several decisions means several `<Step>` children, never one long scroll of stacked context and asks. A page that asks nothing states what happened and what it changes.",r="Use inline pages as the default way to put structured or interactive content in front of the user; the environment renders rich components, so a page is not a special occasion.",d="Use inline pages as the default way to put a question or a decision in front of the user; the viewer draws them in the transcript and in the inbox, so a page is not a special occasion.",h="What costs the reader is being asked, not the page it arrives on: send one when their answer changes what you do next, carry everything else in your next report, and put several decisions in one page as separate steps rather than sending several pages.",l='Write one `.tsx` module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx` that default-exports a component whose root element is `<Page title="\u2026" subtitle="\u2026">`; a multi-step page puts its content in `<Step>` children.',c="Or send a complete `.html` file with a nonempty `<title>`; HTML is delivered verbatim and collects no response.",p="Delivery is chosen by `human send` flags, never a Page prop. Registry components and React are already in scope, so the module contains no `import` and no `require`. Full JS is yours: state, expressions, `.map` over your data, event handlers, plain elements with Tailwind classes. `usePageHost` is a reserved hook whose product-supplied members are opaque here. Never render submit or dismiss chrome \u2014 the host owns it. Display-only pages are first-class: a page with no questions may be sent without inbox or reply delivery. The module is compiled when you submit it and a compile error rejects the submit; there is no pre-check.",u="Context can sit anywhere on the page \u2014 prose and display components around a question are rendered beside it \u2014 so a question's `body` carries what that question needs and the page carries the shared background.",m="Put the context a question needs in that question's own `body`: the reader is shown one question at a time, so page-level prose is not in front of them while they answer, and a question that leans on it cannot be answered.",g="This host draws the page from the components you declared rather than running your module, so layout, Tailwind classes, state, and click handlers never reach the reader \u2014 what survives is each component's `label`, its markdown `body`, and its options, rows, or cards. A chart renders as one line naming it, and a product-registered component cannot be answered here at all.",y="The shadcn display set \u2014 `Card`, `Badge`, `Button`, `Table`, `Tabs`, `Separator`, `Alert`, `Progress`, `Accordion` and their parts \u2014 is in scope too, for presentation only.";function v(e=!1){const t=[e?r:d,h,l,...e?[c]:[],p,e?u:m,...e?[]:[g]].join(" ");return{brief:i,authoring:t,componentSelection:[...a,y],pageHint:"Write the page module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx`; pass that path.",rootUseWhen:e?"a person must decide something or receive structured content from you; use inline pages by default because the environment renders rich components.":"a person must decide, review a document with you, or receive a live display.",sendSummary:e?"send a durable TSX or HTML page":"send a durable TSX page",sendWhenToUse:e?"you need to put structured TSX or HTML content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.":"you need to put structured TSX content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.",pageFlagConstraint:e?"A .tsx file is JSX; .html/.htm is complete HTML. Provide exactly one of --page or stdin.":"Provide exactly one of --page or stdin.",stdinConstraint:e?"The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH. HTML is file-authored.":"The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH.",dirConstraint:e?"Interaction directory holding page.tsx or page.html, optional page.js, page.json, and response lifecycle files when delivery needs them.":"Interaction directory holding page.tsx, optional page.js, page.json, and response lifecycle files when delivery needs them."}}n(v,"pageHelpText");function f(){return s("user").max_panes_per_window}n(f,"resolveMaxPanes");export{v as pageHelpText,f as resolveMaxPanes};

package/dist/commands/human.d.ts

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

package/dist/commands/human.js

@@ -0,0 +1,4 @@
+var s=Object.defineProperty;var r=(e,n)=>s(e,"name",{value:n,configurable:!0});import{defineBranch as i}from"../core/command.js";import{readConfig as m}from"../core/config.js";import{userScopeRoot as c}from"../core/scope.js";import{scopedStoreExists as h}from"../core/scoped-state/db.js";import{userStore as p}from"../core/scoped-state/paths.js";import{humanSend as u,humanShow as l}from"./human/prompts.js";import{humanList as d,humanResolve as f,humanCancel as w}from"./human/queue.js";import{humanReviewBranch as b}from"./human/review.js";import{humanFeedbackBranch as g}from"./human/feedback.js";import{humanComponents as v}from"./human/components.js";import{humanRequestBranch as k}from"./human/request.js";import{pageHelpText as x}from"./human/shared.js";function L(){const e=h(p(c()))&&m("user").page_surface,n=x(e),o=e?"human-in-the-loop decisions and structured pages":"human-in-the-loop decisions, document review, and live display",t="`request` publishes the same page with no bridge at all, for a caller that will have exited before the answer arrives: its outcome is read back or carried to a named local action.",a=e?`Tickets queue in the human inbox; nothing opens on screen. \`send\` routes completion back when the page carries response-bearing components, and publishes a standalone announcement when it does not. ${t}`:`Tickets queue in the human inbox; nothing opens on screen. \`send\` routes completion back when the page carries response-bearing components, and publishes a standalone announcement when it does not. ${t} \`review\` is for live document review with anchored comments; \`show\` is a passive tmux live-watch rather than a ticket.`;return i({name:"human",extensible:!0,rootEntry:{concept:o,desc:e?"send, components, feedback, cancel, list":"send, review new/comment, show, cancel, list",useWhen:n.rootUseWhen},help:{name:"human",summary:o,model:[a,n.brief,n.authoring,n.componentSelection.join(`
+`),"Props, response contracts, and the full component catalog: `crtr human components`; select with `crtr human components list`, then read one with `crtr human components show <component>`."].join(`
+
+`)},children:[v,u(e),...e?[]:[b],g,...e?[]:[l],k,w,d,f]})}r(L,"registerHuman");export{L as registerHuman};

package/dist/commands/node/bash.d.ts

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

package/dist/commands/node/bash.js

@@ -0,0 +1,5 @@
+var w=Object.defineProperty;var r=(e,t)=>w(e,"name",{value:t,configurable:!0});import{envNodeId as _}from"../../shared/env.js";import{defineBranch as j,defineLeaf as c}from"../../core/command.js";import{InputError as s}from"../../core/io.js";import{existsSync as m}from"node:fs";import{activeBackgroundBashJobs as k,backgroundRunningBashJobs as y,bashJobCommandLine as x,bashJobPaths as v,clearJobDeadline as $,formatBashElapsed as g,isSafeBashJobId as f,jobStartedAtMs as I,readJobPgid as D,tailJobLog as T,writeJobDeadlineMs as M}from"../../core/bash-jobs.js";import{parseDurationMs as q}from"../../core/wake.js";import{cliClient as N,getNodeOrNull as h}from"../api-client.js";import{nodeInPane as E}from"../surface/node/placement.js";function u(e,t){const n=e.pane??process.env.TMUX_PANE;let o=e.node;if((o===void 0||o==="")&&(o=E(n)),(o===void 0||o==="")&&(o=_()),o===void 0||o==="")throw new s({error:"no_node",message:t,next:"Run from inside a node, pass --node <id>, or --pane <pane>."});return{id:o,pane:n}}r(u,"resolveBashTarget");const B=c({name:"background",description:"hand the focused node\u2019s running bash command to its background job system",whenToUse:"the tmux prefix menu invokes this when a foreground bash command should stop blocking the agent immediately but keep running as a file-backed background job",tier:"hidden",help:{name:"node bash background",summary:"hand every running foreground bash command for one node to its file-backed background job system",params:[{kind:"flag",name:"node",type:"string",required:!1,constraint:"Node whose running bash command to background. Defaults to the node in --pane, else the caller (CRTR_NODE_ID)."},{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE. The prefix menu passes this for you."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The target node."},{name:"jobs",type:"object[]",required:!0,constraint:"Per handed-off job {job_id, elapsed_ms} \u2014 the foreground elapsed time in milliseconds at the moment of handoff."}],outputKind:"object",effects:["Signals every foreground bash command currently running for the node to return from its tool call immediately while its detached supervisor keeps the command running.","Each handed-off command retains its log under the node context jobs directory and becomes a job object; when it exits, the job\u2019s watchers (its node by default) get an urgent `exited` push carrying the exit code and log path."]},run:r(async e=>{const{id:t}=u(e,"no node found for the bash handoff"),n=await h(t);if(n===null)throw new s({error:"not_found",message:`no node: ${t}`,next:"List nodes with `crtr node inspect list`."});const o=y(n.paths.context_dir),d=Date.now(),i=o.map(l=>({job_id:l.jobId,elapsed_ms:d-(I(l.jobId)??d)}));return{node_id:t,jobs:i}},"run"),render:r(e=>{const t=e.jobs;if(t.length===0)return`No foreground bash command is running for ${e.node_id}.`;const n=Math.max(...t.map(o=>o.elapsed_ms));return`Handed ${t.length} bash command(s) to the background job system for ${e.node_id} \xB7 ran ${g(n)} in the foreground.`},"render")}),R=c({name:"list",description:"list a node\u2019s live background bash jobs",whenToUse:"the Inspector\u2019s jobs section reads this to show what a node handed off to the background",tier:"hidden",help:{name:"node bash list",summary:"read every still-running background bash job owned by one node",params:[{kind:"flag",name:"node",type:"string",required:!1,constraint:"Node whose background jobs to list. Defaults to the node in --pane, else the caller (CRTR_NODE_ID)."},{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE."},{kind:"flag",name:"tail",type:"int",required:!1,default:0,constraint:"Include this many trailing log lines per job (0 = none)."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The target node."},{name:"jobs",type:"object[]",required:!0,constraint:"Oldest-first {job_id, command, purpose, started_at, elapsed_ms, deadline_at, log_path, pgid, log_tail} for every live background job; purpose is a human-readable label or null; deadline_at is the auto-cancel time or null for a job that runs to completion."}],outputKind:"object",effects:["Reads the node context jobs directory. Changes nothing."]},run:r(async e=>{const{id:t}=u(e,"no node found for the bash job list"),n=await h(t);if(n===null)throw new s({error:"not_found",message:`no node: ${t}`,next:"List nodes with `crtr node inspect list`."});const o=Date.now(),d=Math.max(0,Math.trunc(Number(e.tail??0))),i=n.paths.context_dir,l=k(i).map(a=>({job_id:a.jobId,command:a.command,purpose:a.purpose,started_at:new Date(a.startedAtMs).toISOString(),elapsed_ms:o-a.startedAtMs,deadline_at:a.deadlineAtMs===null?null:new Date(a.deadlineAtMs).toISOString(),log_path:a.logPath,pgid:D(i,a.jobId)??null,log_tail:T(a.logPath,d)}));return{node_id:n.node_id,jobs:l}},"run"),render:r(e=>{const t=e.jobs;return t.length===0?`No background bash jobs for ${e.node_id}.`:t.map(n=>`${n.job_id} \xB7 ${g(n.elapsed_ms)} \xB7 ${x(n.command)}${n.purpose===null?"":`
+  purpose: ${n.purpose}`}${n.deadline_at===null?"":`
+  cancels at: ${n.deadline_at}`}
+  log: ${n.log_path}`).join(`
+`)},"render")}),S=c({name:"kill",description:"stop one of a node\u2019s background bash jobs",whenToUse:"the user watching the Inspector or the attach cockpit\u2019s bash row wants a long-running background job to stop now, or an agent is abandoning work it backgrounded",tier:"hidden",help:{name:"node bash kill",summary:"best-effort stop a background bash job and tell the owning node it was canceled",params:[{kind:"positional",name:"job",required:!0,constraint:"Job id, as reported by node bash list."},{kind:"flag",name:"node",type:"string",required:!1,constraint:"Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID)."},{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The owning node."},{name:"signaled",type:"boolean",required:!0,constraint:"True when at least one observed supervisor-tree process received SIGTERM."}],outputKind:"object",effects:["Snapshots the supervisor\u2019s observable process tree, sends SIGTERM then SIGKILL to those processes, and cannot stop a descendant that detached and reparented before the snapshot.","Records the job\u2019s exit so it stops showing as live, and ends its job object as killed; the job\u2019s watchers (its node by default) get an urgent `killed` push."]},run:r(async e=>{const{id:t}=u(e,"no node found for the bash job"),n=await h(t);if(n===null)throw new s({error:"not_found",message:`no node: ${t}`,next:"List nodes with `crtr node inspect list`."});const o=e.job;if(!f(o))throw new s({error:"invalid_job_id",message:`invalid background job id: ${o}`,next:"Use a job id reported by `crtr node bash list`."});const d=await N().stopBashJob(n.node_id,o);return{node_id:n.node_id,signaled:d.signaled}},"run"),render:r(e=>`Canceled a background bash job for ${e.node_id}${e.signaled===!0?"":" (no observed job process was still running)"}.`,"render")}),L=c({name:"extend",description:"claim an auto-backgrounded bash job so the daemon does not cancel it at its deadline",whenToUse:"a command the valve auto-backgrounded is worth keeping past its cancel deadline \u2014 give it more time with --for, or let it run to completion with --keep",tier:"hidden",help:{name:"node bash extend",summary:"move or clear the auto-cancel deadline on one of a node\u2019s live background bash jobs",params:[{kind:"positional",name:"job",required:!0,constraint:"Job id, as reported by node bash list or the auto-background notice."},{kind:"flag",name:"for",type:"string",required:!1,constraint:"New window from now before the job is canceled, as a duration (e.g. 90s, 10m, 1h30m). Mutually exclusive with --keep; give exactly one."},{kind:"flag",name:"keep",type:"bool",required:!1,constraint:"Remove the deadline entirely so the job runs to completion. Mutually exclusive with --for; give exactly one."},{kind:"flag",name:"node",type:"string",required:!1,constraint:"Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID)."},{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The owning node."},{name:"deadline_at",type:"string",required:!1,constraint:"The job\u2019s new auto-cancel time (ISO), or absent when --keep cleared the deadline so the job runs to completion."}],outputKind:"object",effects:["Rewrites or removes the job\u2019s deadline file. The daemon\u2019s deadline lane reads it on its next scan. Signals nothing."]},run:r(async e=>{const{id:t}=u(e,"no node found for the bash job"),n=await h(t);if(n===null)throw new s({error:"not_found",message:`no node: ${t}`,next:"List nodes with `crtr node inspect list`."});const o=e.job;if(!f(o))throw new s({error:"invalid_job_id",message:`invalid background job id: ${o}`,next:"Use a job id reported by `crtr node bash list`."});const d=e.for,i=e.keep===!0;if(i===(d!==void 0&&d!==""))throw new s({error:"invalid_args",message:"give exactly one of --for <duration> or --keep",next:"Extend by a window with --for 10m, or drop the deadline with --keep."});const l=n.paths.context_dir,a=v(l,o);if(!m(a.dir))throw new s({error:"not_found",message:`no background job ${o} for ${n.node_id}`,next:"List live jobs with `crtr node bash list`."});if(!m(a.jobBg)||m(a.jobExit))throw new s({error:"not_running",message:`background job ${o} for ${n.node_id} is no longer running`,next:`It finished or was stopped, so there is no deadline to change. Log: ${a.jobLog}`});if(i)return $(a),{node_id:n.node_id};const b=q(d);if(b===null||b<=0)throw new s({error:"invalid_duration",message:`not a duration: ${d}`,next:"Use a value like 90s, 10m, or 1h30m."});const p=Date.now()+b;return M(a,p),{node_id:n.node_id,deadline_at:new Date(p).toISOString()}},"run"),render:r(e=>e.deadline_at===void 0?`Cleared the deadline \u2014 the background job will run to completion for ${e.node_id}.`:`Background job for ${e.node_id} will be canceled at ${e.deadline_at} unless extended again.`,"render")}),H=j({name:"bash",description:"control file-backed bash jobs owned by a node",whenToUse:"a running bash command must be handed off, listed, stopped, or its auto-cancel deadline changed \u2014 the tmux prefix menu backgrounds, the Inspector\u2019s jobs section lists and cancels",tier:"hidden",help:{name:"node bash",summary:"control file-backed bash jobs owned by a node"},children:[B,R,S,L]});export{H as nodeBash};

package/dist/commands/node/create.d.ts

@@ -0,0 +1,6 @@
+/** Decision road sign for a managed (non-root) child. Normally STD_CHILD_FOLLOW_UP,
+ *  but when the SPAWNER is an orchestrator whose context has already grown past
+ *  YIELD_NUDGE_THRESHOLD, steer it to yield now and let its fresh revive handle
+ *  the child's result. */
+export declare function childFollowUp(spawnerId: string | undefined): Promise<string>;
+export declare const nodeNew: import("../../core/command.js").LeafDef;

package/dist/commands/node/create.js

@@ -0,0 +1,2 @@
+var K=Object.defineProperty;var a=(e,o)=>K(e,"name",{value:o,configurable:!0});import{envNodeId as Y}from"../../shared/env.js";import{defineLeaf as G}from"../../core/command.js";import{InputError as n}from"../../core/io.js";import{requireScope as V}from"../../core/errors.js";import{mark as q}from"../../core/timing.js";import{OUTPUT_SCHEMA_CONSTRAINTS as X,OUTPUT_SCHEMA_TRANSPORT as Q,parseOutputSchemaValue as Z}from"../../core/runtime/structured-output.js";import{MODEL_SPEC_FORMS as ee,MODEL_SPEC_NEXT as te}from"../../core/runtime/model-selection.js";import{parseDurationMs as oe}from"../../core/wake.js";import{kindsStateBlock as ne,profilesStateBlock as re,resolveProfileViaDaemon as ie}from"../profile/daemon-profiles.js";import{cliClient as F,getNodeOrNull as ae,rethrowAsCliError as L}from"../api-client.js";import{inTmux as $}from"../../core/runtime/placement-tmux.js";import{openSpawnViewer as se}from"../surface/node/placement.js";import{randomUUID as de}from"node:crypto";import{resolve as le}from"node:path";import{isDaemonTransportApiError as H}from"../../api/errors.js";import{ExitCode as ce}from"../../types.js";const ue=1e5,z='--output-schema writes the accepted result to the node\u2019s context/result.json and pushes it as the node\u2019s final report; a node that cannot honestly satisfy the schema declines with `crtr push result --decline "<reason>" --code <token>`, which finishes it with a failure outcome (reason `declined`) whose `declined` field carries { reason, code, retryable } and no result. Name the code tokens you accept in the prompt; crouter carries the code verbatim and you validate it.',W=["A resident is told never to push a final, so the spawner gets no report wake when the work is done.","If it stops mid-task, nothing prompts it to continue.","After 15 unattended minutes it is concluded with only a deferred update, which does not wake the spawner."],B="To re-task a terminal child after its final, use `crtr node message send --reopen`; to make an existing node resident later, use `crtr node config --lifecycle resident`.",N="Do not wait, poll, or duplicate this child's assignment in your own context \u2014 there is no result to await, stopping will not strand you, and duplicated work wastes the delegated context. You're auto-subscribed, so its finish wakes you on its own. Two moves only: do other independent work right now, or stop and end your turn \u2014 the wake brings you back.";async function he(e){if(e===void 0||e==="")return N;const o=await ae(e);if(o===null||o.mode!=="orchestrator")return N;const t=o.context_tokens??null;return t===null||t<ue?N:`Child spawned \u2014 you're auto-subscribed, so its finish wakes you on its own; never wait, poll, or duplicate the child's assignment in your own context. But you're an orchestrator already carrying ~${Math.round(t/1e3)}k of context: rather than hold this window open for the result, bring your document \`roadmap\` current (\`crtr doc edit roadmap\`) and \`crtr node yield\` now. Yielding ends this turn, and the child's completion then revives you fresh against your roadmap \u2014 let that clean revive absorb the result instead of this bloated context.`}a(he,"childFollowUp");function fe(e,o){throw H(e)||L(e),new n({error:"node_create_effect_unknown",message:`Node creation did not receive an acknowledgement after automatic recovery with request key ${o}; its effect is unknown.`,next:"Do not create a replacement node until the daemon is reachable and this request can be recovered."},ce.NETWORK)}a(fe,"createTransportFailure");function me(){return[{kind:"stdin",name:"prompt",required:!1,constraint:"First user message."},{kind:"flag",name:"kind",type:"string",required:!1,constraint:"Persona kind. Defaults to the profile's default kind; `general` when the profile has none. The <kinds> list below names every top-level installable kind."},{kind:"flag",name:"mode",type:"enum",choices:["base","orchestrator"],required:!1,default:"base",constraint:"Persona mode. base for one hands-on unit; orchestrator when the unit itself needs decomposition across children. When you hold several parallel units of one kind, spawn ONE orchestrator child of that kind to own the fan-out rather than spawning the units yourself \u2014 unless you are already an orchestrator of that kind, whose job is exactly that fan-out."},{kind:"flag",name:"cwd",type:"path",required:!1,constraint:"Pin the node to this directory. Without --worktree, defaults to the spawner\u2019s directory for a managed child and the invocation directory for a root. With --worktree, selects the repository used for creation, defaulting to the invocation directory; the child runs in the new checkout."},{kind:"flag",name:"name",type:"string",required:!1,constraint:"Display name."},{kind:"flag",name:"parent",type:"string",required:!1,constraint:"Parent node id. Defaults to the calling node."},{kind:"flag",name:"node-id",type:"string",required:!1,constraint:"Exact id for the new node; lowercase letters, digits, and hyphens only, at most 128 characters. Rejected if already present."},{kind:"flag",name:"root",type:"bool",required:!1,constraint:"Spawn an independent root with no parent or subscription. Mutually exclusive with --worktree."},{kind:"flag",name:"resident",type:"bool",required:!1,constraint:"Birth the node as resident, a conversation partner for a person rather than a worker. Omit unless the user explicitly asks for a node they can talk with back and forth.",focusedHelp:{whenToUse:"Pass it ONLY when the user explicitly asks for a node they can talk with back and forth. Never infer it from task size, from expecting the user to look at the node, or from wanting to follow up later. "+B,value:"Boolean. Roots default to resident, so with --root it changes nothing. Managed children default to terminal; for a managed child the command first refuses, explains the cost, and says how to confirm.",effects:[...W,"It ends by going dormant or by being closed."]}},{kind:"flag",name:"terminal",type:"bool",required:!1,constraint:"Birth the node as terminal: it finalizes when its work is done and leaves nothing wakeable behind. Only meaningful with --root, whose default is resident; managed children are already terminal. Pass it for bounded programmatic work no one will open a viewer on. Mutually exclusive with --resident."},{kind:"flag",name:"force",type:"bool",required:!1,default:!1,hidden:!0,constraint:"Confirm a resident managed child (--resident without --root) after the user explicitly asked for one."},{kind:"flag",name:"worktree",type:"string",required:!1,constraint:"Existing local base branch for this child\u2019s managed worktree. When invoking from a managed worktree, also pass --cwd pointing at the repository\u2019s primary checkout; keep --worktree set to the desired parent branch. Mutually exclusive with --root."},{kind:"flag",name:"fork-from",type:"string",required:!1,constraint:"Fork the new node from an existing node id, absolute session path, or partial pi session uuid."},{kind:"flag",name:"model",type:"string",required:!1,constraint:"Durable model override. Omit unless the task or governing guidance requires a specific model.",focusedHelp:{whenToUse:"Use only when the user, task, or governing agent guidance already requires a specific provider, model, capability tier, or family. Omit it for routine delegation: the selected persona kind and profile own normal model selection, and review personas may enforce a quality floor.",value:`Accepted forms: ${ee}. Concrete provider/id requests must be registered. Portable provider/tier, bare-tier, and family-alias requests resolve through the configured model ladders.`,effects:["The resolved concrete model is stored on the node and in its launch recipe.","A concrete provider/id runs exactly that model on every launch and revive. A portable provider/tier, bare tier, or family alias keeps its tier: when that model's provider is rate-limited or rejects its credential, the node moves to the next model in its route: another provider's model at the same tier first, then the configured fallback tier (strong by default).","A persona quality floor may raise a weaker request before its resolved model is stored."]}},{kind:"flag",name:"profile",type:"string",required:!1,constraint:"Profile override. Use only when the task needs different project purview, owned documents, or environment; otherwise omit for normal inheritance or selection.",focusedHelp:{whenToUse:"Use only when the work must run under a different profile because it needs that profile\u2019s project purview, owned documents, stored environment, or defaults. Do not use it merely to change the working directory, persona kind, model, or graph ownership; those have separate parameters.",value:"Pass a profile id or name from the <profiles> list below; a close-enough name resolves to the nearest profile and the choice is reported on stderr. Omit it inside a node to inherit the caller\u2019s profile; outside a node, omission runs normal cwd-based profile selection.",effects:["The selected profile id is stored on the node and supplies its profile-scoped config, documents, environment, and injected bearings.","It does not change the parent or subscription; --cwd separately pins the working directory."]}},{kind:"flag",name:"situational-context",type:"string",required:!1,constraint:"Hidden ambient context appended to injected bearings, never visible chat."},{kind:"flag",name:"no-kickoff",type:"bool",required:!1,hidden:!0,constraint:"With --root, start the broker and session idle without a first message or model turn. Mutually exclusive with a prompt and --mode orchestrator."},{kind:"flag",name:"deadline",type:"string",required:!1,constraint:"Positive, representable wall-clock duration from spawn. Grammar: one or more positive integer-unit parts; units: s, m, h, d; adjacent parts are summed. Omit for no deadline."},{kind:"flag",name:"outcome-action",type:"string",required:!1,constraint:"Declared human-action name that receives the node outcome. Grammar: 1\u2013128 ASCII letters, digits, dots, underscores, or hyphens; starts with a letter or digit. Omit when no external delivery target is needed."},{kind:"flag",name:"outcome-payload",type:"string",required:!1,constraint:"JSON value, serialized at most 64 KiB, frozen and echoed to --outcome-action. Requires --outcome-action."},{kind:"flag",name:"output-schema",type:"string",required:!1,constraint:"Replace prose completion with a schema-constrained final result. Use only when its consumer requires fixed fields.",focusedHelp:{whenToUse:"Use only when the node\u2019s consumer needs a machine-checkable final object with fixed fields. Omit it for ordinary delegation or when a prose report is enough; structured output replaces the completion protocol, and an over-constrained schema can force retries.",value:`Pass the JSON Schema the result must satisfy. ${Q} ${X}`,effects:["The node must answer with `crtr push result` and cannot finish until the result is accepted; a plain `crtr push final` is blocked while the request is pending.",z,"The managed parent wakes through its existing subscription when the final report arrives; an independent root has no subscriber to wake.","An accepted result, or a decline, removes the request and terminates the node."]}}]}a(me,"nodeNewParams");function pe(){return[{name:"node_id",type:"string",required:!0,constraint:"New node id."},{name:"name",type:"string",required:!0,constraint:"Display name."},{name:"frozen_at",type:"string",required:!1,constraint:"Present when a managed child exists but capacity deferred its broker start."},...$()?[{name:"window",type:"string",required:!1,constraint:"tmux window id when a viewer opens."},{name:"session",type:"string",required:!1,constraint:"tmux session when a viewer opens."}]:[],{name:"follow_up",type:"string",required:!0,constraint:"Managed child: continue unrelated work or stop; its final report wakes you. Root: hand it off; no report wakes you."}]}a(pe,"nodeNewOutput");function we(){return["Creates nodes/<id>/ in the canvas home, indexes the node in canvas.db, and starts its detached broker engine.","A managed child creates an active parent subscription; its pushes wake the parent. --root creates an independent node with spawned_by provenance and no parent subscription.","--worktree creates a managed worktree at ~/.crouter/canvas/worktrees/<node-id>/ on a new crtr/<node-id> branch.",z,"--deadline persists a wall-clock deadline from spawn; expiry cancels the node and records a failure outcome with reason deadline_exceeded.","--outcome-action registers one resolved local human-action target. When the node settles, crouter retries delivery of its outcome document until the target accepts it or permanently rejects it; --outcome-payload is frozen and echoed in that document.",...$()?["--root opens a viewer for the new node in the current tmux session."]:[]]}a(we,"nodeNewEffects");async function ke(e){V("crtr:act","crtr node new");const o=e.prompt??"",t=e.noKickoff===!0;if(!t&&o.trim()==="")throw new n({error:"empty_prompt",message:"a prompt is required (stdin or positional)",next:"Pipe a task on stdin or pass it as an argument, or pass --no-kickoff to spawn an idle node with none."});if(t&&o.trim()!=="")throw new n({error:"no_kickoff_with_prompt",message:"--no-kickoff cannot be combined with a prompt",field:"no-kickoff",next:"Drop --no-kickoff, or drop the prompt."});const l=e.kind,T=e.mode??"base",c=e.cwd?.trim(),u=c!==void 0&&c!==""?le(c):void 0,S=e.name,J=e.parent,r=e.root===!0,h=e.resident===!0,O=e.terminal===!0;if(h&&O)throw new n({error:"lifecycle_conflict",message:"--resident and --terminal cannot both be passed",field:"terminal",next:"Pass the one birth lifecycle you want, or neither to take the default (resident for --root, terminal for a managed child)."});if(h&&!r&&e.force!==!0)throw new n({error:"resident_child_requires_force",message:`--resident on a managed child makes it a conversation partner for a person, not a worker that reports back. ${W.join(" ")}`,field:"resident",next:`If the user did not explicitly ask for a node they can talk with back and forth, drop --resident; a terminal child's final report wakes you. ${B} If the user did explicitly ask for one, re-run with --force.`});const f=e.worktree;if(f!==void 0&&f.trim()==="")throw new n({error:"worktree_base_required",message:"--worktree requires a base branch",field:"worktree",next:"Pass an existing local branch that landing can fast-forward."});const m=f?.trim(),P=e.forkFrom,p=e.model?.trim();if(p==="")throw new n({error:"empty_spec",message:"a model spec is required",field:"model",next:`Run \`crtr node new --model -h\` and read the focused contract. ${te}`});const E=e.profile,D=E===void 0?void 0:(await ie(E)).id,w=e.situationalContext?.trim(),C=w!==void 0&&w!==""?w:void 0,A=Z(e.outputSchema),U=A!==null?JSON.stringify(A):null,d=e.deadline;if(d!==void 0){const s=oe(d),x=s===null?Number.NaN:new Date(Date.now()+s).getTime();if(s===null||!Number.isFinite(s)||s<=0||!Number.isFinite(x))throw new n({error:"invalid_deadline",message:"--deadline must be a positive representable duration",field:"deadline",next:"Pass positive integer-unit parts using s, m, h, or d."})}const k=e.outcomeAction,y=e.outcomePayload;if(y!==void 0&&k===void 0)throw new n({error:"outcome_payload_requires_action",message:"--outcome-payload requires --outcome-action",field:"outcome-payload",next:"Pass the declared delivery action with --outcome-action."});let g;if(y!==void 0)try{g=JSON.parse(y)}catch{throw new n({error:"invalid_outcome_payload",message:"--outcome-payload must be valid JSON",field:"outcome-payload",next:"Pass one valid JSON value."})}const v=e.nodeId?.trim();if(r&&m!==void 0)throw new n({error:"worktree_root_conflict",message:"--worktree is mutually exclusive with --root",field:"worktree",next:"Drop either --root or --worktree."});if(t&&!r)throw new n({error:"no_kickoff_requires_root",message:"--no-kickoff is only valid with --root",field:"no-kickoff",next:"Add --root, or drop --no-kickoff and provide a prompt."});if(t&&T==="orchestrator")throw new n({error:"no_kickoff_orchestrator_unsupported",message:"--no-kickoff cannot be combined with --mode orchestrator",field:"no-kickoff",next:"Drop --no-kickoff and provide a prompt, or spawn in base mode."});const b=Y(),I=J??b;q("node_new.create_start",{root:r});const R=de(),M={...l!==void 0?{kind:l}:{},mode:T,cwd:process.cwd(),...u!==void 0&&u!==""?{pin_cwd:u}:{},...S!==void 0?{name:S}:{},prompt:o,...r?{root:!0}:{parent:I??null},...b!==void 0?{creator:b}:{},...h?{root_lifecycle:"resident"}:{},...O?{root_lifecycle:"terminal"}:{},...m!==void 0?{worktree:m}:{},...P!==void 0?{fork_from:P}:{},...p!==void 0?{model:p}:{},...D!==void 0?{profile:D}:{},...C!==void 0?{situational_context:C}:{},...t?{no_kickoff:!0}:{},...U!==null?{output_schema:U}:{},...d!==void 0?{deadline:d}:{},...k!==void 0?{outcome_delivery:{action:k,...g===void 0?{}:{payload:g}}}:{},...v!==void 0&&v!==""?{node_id:v}:{},...r?{prefer_warm:!0}:{},request_key:R};let i;try{i=await F().createNode(M)}catch(s){H(s)||L(s);try{i=await F().createNode(M)}catch(x){fe(x,R)}}q("node_new.node_created",{node:i.node_id});let _={};r&&(_=se(i.node_id,i.cwd,i.name)),r&&q("node_new.viewer_window_opened");const j=!r&&i.frozen_at!==null;return{node_id:i.node_id,name:i.name,...j?{frozen_at:i.frozen_at}:{},window:_.window,session:_.session,follow_up:r?t?"Independent root spawned idle. No kickoff turn ran; hand it off or attach and prompt it. No report wakes you.":"Independent root spawned. You are not subscribed, so its finish does not wake you; hand it off and move on.":j?"Child row exists, but no broker started because capacity is full. It is frozen and will launch when a broker slot frees; its final report wakes you then.":await he(I)}}a(ke,"runNodeCreation");const Re=G({name:"new",description:"create and start a node immediately",whenToUse:"a unit of work is genuinely separable from what you are doing: a bounded subtask you would otherwise grind out inline, several independent units worth running in parallel (usually via one orchestrator child of the matching kind rather than a flat fan-out from you), a scouting pass over unfamiliar code, a change that wants its own git worktree, or an answer you need in a fixed shape rather than as prose",tier:"important",help:{name:"node new",summary:"create a node immediately and start its detached broker",guide:"The prompt is the child\u2019s entire brief: it wakes with this prompt, its persona, and ambient bearings \u2014 none of your conversation carries over. State the outcome and constraints. Pass an implementation plan only when it is already settled or necessary to preserve an approved decision; otherwise, let the child investigate and choose how. Give the reason along with the request: the larger goal this serves and what the child's output enables, so the child resolves ambiguity toward your intent instead of guessing. Point at every document the task depends on (a spec, an explore map, an earlier child's findings) as `[[<node-id>/<name>]]`, or `[[name]]` for a repo, profile or user document; the child reads each with `crtr canvas read` and receives nothing the prompt does not point at. When the report must carry something specific\u2014findings inline, or pointers to documents it wrote\u2014say so in the prompt.",params:me(),output:pe(),outputKind:"object",effects:we()},helpState:{leaf:ne,flags:{profile:re}},run:a(e=>ke(e),"run"),render:a(e=>{const o=e.window?` in window ${e.window}`:"",t=[`Spawned "${e.name}" (${e.node_id})${o}.`];return e.session&&t.push(`- session: ${e.session}`),t.push("",String(e.follow_up)),t.join(`
+`)},"render")});export{he as childFollowUp,Re as nodeNew};

package/dist/commands/node/inspect.d.ts

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

package/dist/commands/node/inspect.js

@@ -0,0 +1,12 @@
+var N=Object.defineProperty;var h=(n,e)=>N(n,"name",{value:e,configurable:!0});import{defineBranch as R,defineLeaf as b}from"../../core/command.js";import{InputError as y}from"../../core/io.js";import{requireScope as P}from"../../core/errors.js";import{isPidAlive as I}from"../../core/canvas/pid.js";import{fullName as k}from"../../core/canvas/labels.js";import{fuzzyMatch as O}from"../../core/tui/fuzzy.js";import{nodeSnapshotLeaf as F}from"../node-snapshot.js";import{nodeTranscriptLeaf as L}from"../node-transcript.js";import{nodeContextLeaf as A}from"../node-context.js";import{cliClient as $,cliCanvasSource as x,rethrowAsCliError as w}from"../api-client.js";import{RemoteCanvasSource as q}from"../../core/canvas/remote-canvas-source.js";import{kindsStateBlock as C,profilesStateBlock as U,resolveProfileViaDaemon as D}from"../profile/daemon-profiles.js";import{focusViewer as z,nodeInPane as E}from"../surface/node/placement.js";const B=b({name:"list",description:"list nodes on the canvas",whenToUse:"you want a flat roster of the nodes on the canvas, sliced by displayed name, status, kind, mode, lifecycle, profile, cwd, and graph scope (--under a node, for that node plus its subscription descendants). The filters AND together. Use `node inspect show` instead to drill into one node and its spine neighbors, `canvas dashboard` for the tree shape, and `canvas attention` to find nodes blocked on the user",help:{name:"node inspect list",summary:"list nodes on the canvas, filtered by any combination of attribute slices and a graph-scope (--under) that AND together",params:[{kind:"flag",name:"status",type:"string",required:!1,constraint:"Filter status (comma-separated for several; accepted values: active, idle, done, dead, canceled). NOTE: `active` means the engine process is live (never closed), NOT that the node is generating right now \u2014 an active node is usually dormant between turns. To tell working-vs-idle, check the pi session-file mtime or CPU, not status."},{kind:"flag",name:"kind",type:"string",required:!1,constraint:"Filter by persona kind (comma-separated for several). The <kinds> list below names every top-level installable kind; a registered sub-kind filters too by exact path even though it is not listed."},{kind:"flag",name:"mode",type:"string",required:!1,constraint:"Filter by mode (comma-separated for several; accepted values: base, orchestrator)."},{kind:"flag",name:"lifecycle",type:"string",required:!1,constraint:"Filter by lifecycle (comma-separated for several; accepted values: terminal, resident)."},{kind:"flag",name:"profile",type:"string",required:!1,constraint:"Filter by profile. On the local canvas, accepts a profile id or manifest name from the <profiles> list below, or a close-enough name that resolves to the nearest profile. Against a remote canvas, pass the exact profile id carried by its node rows."},{kind:"flag",name:"name",type:"string",required:!1,constraint:"Filter by the displayed node label (handle plus generated description) with the canvas browser\u2019s case-insensitive fuzzy subsequence match."},{kind:"flag",name:"cwd",type:"string",required:!1,constraint:"Filter to nodes pinned to this exact cwd (absolute path). Roster is canvas-wide (all cwds) by default."},{kind:"flag",name:"under",type:"string",required:!1,constraint:'Graph scope: restrict to this node and its subscription descendants (the sub-DAG reachable downward \u2014 its reports, theirs, \u2026). This is "one initiative / my subtree". ANDs with every attribute filter above, narrowing any of them to this subtree.'},{kind:"flag",name:"canvas",type:"string",required:!1,constraint:"Read from the named remote canvas target (see `crtr canvas config list`) instead of the local canvas. Overrides `crtr canvas use`."}],output:[{name:"nodes",type:"object[]",required:!0,constraint:"Rows include {node_id, name, kind, mode, lifecycle, status, cwd, profile_id, parent, created}. `name` is the displayed node label searched by --name and shown in canvas views. `profile_id` is the stable profile-directory id (null only for historical no-profile nodes)."}],outputKind:"object",effects:["Read-only: lists nodes through the daemon API."]},helpState:{leaf:h(async()=>(await Promise.all([C(),U()])).join(`
+`),"leaf")},run:h(async n=>{const e=h(r=>{const g=n[r];return g!==void 0&&g!==""?g.split(",").map(v=>v.trim()).filter(v=>v!==""):void 0},"csv"),o=e("status"),s=e("kind"),u=e("mode"),d=e("lifecycle"),f=n.profile,c=n.name,l=n.cwd,i=n.under,p=x({canvasName:n.canvas}),a=p instanceof q?f:f===void 0?void 0:(await D(f)).id;let t;if(i!==void 0&&i!==""){if(await p.getNode(i).catch(w)===null)throw new y({error:"not_found",message:`no node: ${i}`,next:"List nodes with `crtr node inspect list`, then pass a real id to --under."});t=new Set([i,...await p.view(i)])}return{nodes:(await p.listNodes(o!==void 0?{status:o}:void 0).catch(w)).filter(r=>!(t!==void 0&&!t.has(r.node_id)||s!==void 0&&!s.includes(r.kind)||u!==void 0&&!u.includes(r.mode)||d!==void 0&&!d.includes(r.lifecycle)||a!==void 0&&r.profile_id!==a||l!==void 0&&l!==""&&r.cwd!==l)).map(r=>({...r,name:k(r)})).filter(r=>c===void 0||c===""||O(c,r.name))}},"run")}),S=new WeakSet;async function j(n,e){const o=await n.getNode(e.node_id).catch(w);return{node_id:e.node_id,name:o?k(o):"(missing)",kind:o?.kind??"?",status:o?o.intent?`${o.status}/${o.intent}`:o.status:"?",active:e.active}}h(j,"enrichNeighbor");const K=b({name:"show",description:"show a node + its spine neighbors and drill-in pointers",whenToUse:"you want one node in depth \u2014 the debugging entrypoint: a glanceable meta slice, named spine neighbors, a pending-cron count, and exact drill-in paths. Use `node inspect list` for the flat roster or `canvas dashboard` for the whole-tree shape",help:{name:"node inspect show",summary:"show a node in depth \u2014 meta slice, named neighbors, pending-cron count, and drill-in pointers",params:[{kind:"positional",name:"node",required:!0,constraint:"Node id."},{kind:"flag",name:"canvas",type:"string",required:!1,constraint:"Read from the named remote canvas target (see `crtr canvas config list`) instead of the local canvas. Overrides `crtr canvas use`."}],output:[{name:"node",type:"object",required:!0,constraint:"The full node meta (system prompt + every telemetry field). The render surfaces a glanceable slice; `--json` carries the complete dump."},{name:"fault",type:"object",required:!0,constraint:"The active runtime fault projection, or null: {link, kind, retry: {disposition}, since}."},{name:"reports",type:"object[]",required:!0,constraint:"Who this node subscribes to (its reports/down), each enriched with {node_id, name, kind, status, active} \u2014 these are typically its spawned children."},{name:"managers",type:"object[]",required:!0,constraint:"Who subscribes to this node (its managers/up), same enriched shape."},{name:"pending_crons",type:"number",required:!0,constraint:"How many pending crons were created by this node. Inspect with `crtr cron list`."},{name:"paths",type:"object",required:!0,constraint:"Resolved on-disk locations: {context_dir, session_file} \u2014 read these directly to debug. Reports are documents: `crtr canvas read <node>/reports/<name>`."},{name:"follow_up",type:"string",required:!0,constraint:"The concrete next commands to drill deeper."}],outputKind:"object",effects:["Read-only: reads the node, its edges, and pending crons through crtrd."],preview:{suppressOutput:!0}},run:h(async n=>{const e=n.node,o=n.canvas,s=x({canvasName:o});if(s instanceof q){const t=await s.rawShow(e);if(t===null)throw new y({error:"not_found",message:`no node: ${e}`,next:"List nodes with `crtr node inspect list --canvas <name>`."});const m={...t};return S.add(m),m}const u=await s.getNode(e).catch(t=>w(t,"List nodes with `crtr node inspect list`."));if(u===null)throw new y({error:"not_found",message:`no node: ${e}`,next:"List nodes with `crtr node inspect list`."});const d=u,f=$(),c=await Promise.all((await s.subscriptionsOf(e)).map(t=>j(s,t))),l=await Promise.all((await s.subscribersOf(e)).map(t=>j(s,t))),i=(await f.listCrons().catch(w)).filter(t=>t.created_by===e).length,p={context_dir:d.paths.context_dir,...d.pi_session_file!==void 0?{session_file:d.pi_session_file}:{}},a=[];return a.push(`List the documents it owns (reports, plans, notes): \`crtr canvas list --owner ${e}\`.`),a.push(`Browse its context dir (and its subscriptions') in nvim: \`crtr node inspect context ${e}\`.`),p.session_file&&a.push(`Read the raw conversation transcript: ${p.session_file}`),a.push(`On-disk context dir (ls/read directly): ${p.context_dir}`),i>0&&a.push(`It created ${i} pending cron(s): \`crtr cron list\`.`),c.length>0&&a.push(`Drill into a child/report: \`crtr node inspect show <node_id>\` (${c.map(t=>t.node_id).join(", ")}).`),a.push(`Full machine dump (system prompt + all telemetry): \`crtr --json node inspect show ${e}\`.`),{node:d,fault:d.fault??null,reports:c,managers:l,pending_crons:i,paths:p,follow_up:a.join(`
+`)}},"run"),render:h(n=>{const e=n.node,o=String(e.node_id),s=e.pi_pid,d=S.has(n)?"remote (liveness not checked locally)":I(s)?"alive":"dead",f=e.intent?`/${String(e.intent)}`:"",c=n.fault,l=[];l.push(`# ${k(e)}  (${o})`);const i=[`- kind/mode/lifecycle: ${e.kind} / ${e.mode} / ${e.lifecycle}`,`- status: ${e.status}${f}`,...c==null?[]:[`- fault: ${String(c.kind)} / ${String(c.retry?.disposition)} since ${String(c.since)}`],`- broker pid: ${s??"(none)"} \u2014 ${d}`,`- cwd: ${e.cwd}`,`- host: ${e.host_kind}`+(e.profile_id?` \xB7 profile ${e.profile_id}`:""),`- cycles: ${e.cycles} \xB7 created ${e.created}`];e.parent&&i.push(`- parent: ${e.parent}`),i.push(`- creator: ${e.creator??"an external process"}`),e.waiting_for&&i.push(`- waiting for message: ${e.waiting_for}`),l.push(i.join(`
+`));const p=h((a,t)=>{if(t.length===0)return`${a}: none`;const m=["node_id","name","kind","status","active"],_=`| ${m.join(" | ")} |`,r=`| ${m.map(()=>"---").join(" | ")} |`,g=t.map(v=>`| ${m.map(T=>String(v[T]??"").replace(/\|/g,"\\|").replace(/\n/g," ")).join(" | ")} |`).join(`
+`);return`${t.length} ${a}:
+
+${_}
+${r}
+${g}`},"table");return l.push(p("reports (down \u2014 subscriptions, usually children)",n.reports)),l.push(p("managers (up \u2014 subscribers)",n.managers)),l.push(`${n.pending_crons} pending cron(s)`),l.push(`Drill deeper:
+${String(n.follow_up)}`),l.join(`
+
+`)},"render")}),oe=b({name:"fork",description:"fork a node into an independent idle root with the same conversation and durable context",whenToUse:"a conversation has already accumulated the context you want, and you want a new user-driven branch beside it without sending a prompt or inheriting any graph-management responsibility. This copies the conversation and durable context, then waits for the fork\u2019s first real user message to supply its mandate. Use `node new --fork-from` instead when spawning a managed worker with an immediate task",help:{name:"node fork",summary:"create an independent resident root from a node\u2019s conversation and durable context, with no kickoff prompt or model turn",params:[{kind:"flag",name:"node",type:"string",required:!1,constraint:"Source node id. Mutually exclusive with --pane; one of them is required."},{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane showing the source node. Mutually exclusive with --node; one of them is required. The prefix menu passes this for you and the new viewer splits beside this pane."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The new independent root id."},{name:"focused",type:"boolean",required:!0,constraint:"True when a new viewer pane opened beside the caller; false outside tmux."},{name:"session",type:"string",required:!1,constraint:"The tmux session containing the new viewer, when one opened."}],outputKind:"object",effects:["Creates a resident base-mode root with the source node\u2019s copied pi conversation, cwd, profile, kind, model override, and durable context files. Top-level initial-prompt.md, yield-message.md, result.json, and the jobs/ folder of background bash jobs are omitted.","Copies no parent, subscriptions, subscribers, children, crons, worktree, situational context, or lifecycle responsibility. Sends no prompt and consumes no model turn; the first real user message becomes the fork\u2019s mandate.","Inside tmux, opens and focuses a surface-attach viewer as an even-horizontal split in the source pane\u2019s window. Outside tmux, the root is still created but no interactive fallback opens."]},run:h(async n=>{P("crtr:act","crtr node fork");const e=n.pane,o=n.node;if(o!==void 0&&e!==void 0)throw new y({error:"conflicting_target",message:"--node and --pane are mutually exclusive",next:"Pass the source node id or its viewer pane, not both."});let s=o;if(s===void 0&&e!==void 0&&(s=E(e)),s===void 0||s==="")throw new y({error:"no_node",message:"no source node was provided or found in the pane",next:"Pass --node <id>, or --pane <pane-id> for a pane showing a node."});const u=await $().forkNode(s).catch(w),d=await z(u.node_id,{cwd:u.cwd,name:u.name,...e!==void 0?{pane:e}:{},newPane:!0});return{node_id:u.node_id,focused:d.focused,session:d.session}},"run"),render:h(n=>{const e=n.focused===!0?` Viewer opened beside the source${n.session?` in session ${n.session}`:""}.`:" No viewer opened because no tmux pane was available.";return`Forked independent idle root ${n.node_id}.${e} It will make no model call until its first real user message.`},"render")}),ie=R({name:"inspect",description:"read one node \u2014 its graph position, conversation, and context dir",whenToUse:"reading everything about ONE node you can name: enumerate the roster (`list`), inspect a node and its spine neighbors (`show`), or browse its on-disk context dir (`context`). The documents a node owns are `crtr canvas list --owner <id>`. Use `canvas dashboard` instead to render the whole tree SHAPE, or `canvas attention` to find which nodes are blocked on the user",help:{name:"node inspect",summary:"read one node (or the roster) \u2014 topology, conversation, and context dir",model:"Inspection is read-only and never revives a node. The roster is the selection surface; one-node metadata points to progressively heavier views: a parsed broker snapshot, rendered conversation, or context browser."},children:[B,K,F,L,A]});export{oe as nodeFork,ie as nodeInspect};

package/dist/commands/node/lifecycle.d.ts

@@ -0,0 +1,4 @@
+export declare const nodeConfig: import("../../core/command.js").LeafDef;
+export declare const nodePromote: import("../../core/command.js").LeafDef;
+export declare const nodeLifecycle: import("../../core/command.js").BranchDef;
+export declare const nodeYield: import("../../core/command.js").LeafDef;

package/dist/commands/node/lifecycle.js

@@ -0,0 +1,4 @@
+var B=Object.defineProperty;var u=(e,t)=>B(e,"name",{value:t,configurable:!0});import{readFileSync as W}from"node:fs";import{envNodeId as D}from"../../shared/env.js";import{defineBranch as H,defineLeaf as E}from"../../core/command.js";import{InputError as r}from"../../core/io.js";import{cliClient as w,getNodeOrNull as K,rethrowAsCliError as y}from"../api-client.js";import{DEFAULT_BASH_NICENESS as F,MAX_BASH_NICENESS as N,writeBashNiceness as X}from"../../core/bash-jobs.js";import{nodeReviveLeaf as Y}from"../node-lifecycle-revive.js";import{kindsStateBlock as C}from"../profile/daemon-profiles.js";import{MODEL_SPEC_FORMS as J}from"../../core/runtime/model-selection.js";import{closePane as z,paneExists as G,respawnPaneSync as V,viewerEnv as Q,viewerPaneOf as Z,nodeInPane as I}from"../surface/node/placement.js";const ee=E({name:"recycle",description:"finish the agent in your pane + recycle it into a fresh root",whenToUse:"you are at an agent's pane and done with it: finish it cleanly and recycle the pane in one move \u2014 push its last message as a final report to everyone waiting on it, mark it done, then boot a fresh crtr root in the same pane to keep working. The hands-on way to end an agent and immediately start over in place. Use `node lifecycle demote` instead to put it on a finishing track IN PLACE (flip terminal, keep it running) without ending it now, `node lifecycle close` to tear a node and its subtree down WITHOUT finishing (no report, revivable), and `push final` when the agent should finish ITSELF from inside its own turn",help:{name:"node lifecycle recycle",summary:"finish the agent in your current pane and recycle the pane \u2014 push its last message as a final report to everyone waiting on it, mark it done, then boot a fresh crtr root in the same pane",params:[{kind:"flag",name:"node",type:"string",required:!1,constraint:"Node to finish. Defaults to the node occupying --pane (or your current pane)."},{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane id to recycle. Defaults to $TMUX_PANE / your current pane. The Alt+C menu passes this for you."}],output:[{name:"recycled",type:"boolean",required:!0,constraint:"True when the pane was recycled into a fresh root."},{name:"node_id",type:"string",required:!1,constraint:"The finished node."},{name:"new_root",type:"string",required:!1,constraint:"The fresh root node booted into the pane."}],outputKind:"object",effects:["Pushes a final report from the node (fans out to all subscribers) and marks it done.","Kills the agent's pi and respawns a fresh resident root in the same tmux pane."]},run:u(async e=>{const t=e.pane??process.env.TMUX_PANE;let n=e.node;if((n===void 0||n==="")&&(n=I(t)),n===void 0||n==="")throw new r({error:"no_node",message:"no node found in this pane to finish",next:"Pass --node <id>, or run from inside the agent's pane."});const i=await w().getNode(n).catch(f=>y(f,"List nodes with `crtr node inspect list`.")),o=(await w().recycleNode(n).catch(y)).node_id;let h=!1;return t!==void 0&&t!==""&&(h=V({pane:t,cwd:i.cwd,env:Q(),command:"crtr"})),{recycled:h,node_id:n,new_root:o}},"run"),render:u(e=>{if(e.recycled!==!0)return e.new_root?`Finished ${e.node_id} and spawned a fresh broker root (${e.new_root}), but its viewer did not attach \u2014 the new broker did not come up. Re-focus the root to view it.`:`Recycle failed for ${e.node_id??"?"} \u2014 not in tmux, or no agent in this pane.`;const t=[`Recycled the pane \u2014 finished ${e.node_id}.`];return e.new_root&&t.push(`- new root: ${e.new_root}`),t.join(`
+`)},"render")}),ne=E({name:"close",description:"close a node + cascade-cancel its exclusive subtree",whenToUse:"you want to tear a node down WITHOUT finishing it, cascade-cancelling every descendant it exclusively owns: abandoning a line of work, killing a stuck or wrong-turn subtree, clearing a branch you no longer need. A node that never produced substantive assistant output is deleted and cannot be revived; streaming nodes and nodes with an open managed worktree are retained. Other closed nodes keep their pi session and can be revived later (`node lifecycle revive`). Use `node lifecycle recycle` instead to FINISH the agent in your pane with a final report, and `push final` when a worker should end its own work normally (Alt+C \u2192 x)",help:{name:"node lifecycle close",summary:"close a node and cascade-cancel its subtree \u2014 kill its tmux window plus those of every descendant it EXCLUSIVELY owns (down the subscription spine \u2014 the watches each manager holds on its children), mark retained nodes canceled, and leave them a notice they read on resume. A descendant still subscribed to by a manager outside the subtree is left running. A node that never produced substantive assistant output is deleted and cannot be revived; streaming nodes and nodes with an open managed worktree are retained. Other closed nodes keep their pi session and can be revived later (`crtr node lifecycle revive`)",params:[{kind:"flag",name:"node",type:"string",required:!1,constraint:"Node to close. Defaults to the node occupying --pane (or your current pane)."},{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane id whose node to close. Defaults to $TMUX_PANE / your current pane. The Alt+C menu passes this for you."}],output:[{name:"node_id",type:"string",required:!1,constraint:"The node that was closed \u2014 the cascade root."},{name:"count",type:"number",required:!1,constraint:"How many nodes were closed (root + cascaded descendants)."},{name:"closed_ids",type:"string[]",required:!1,constraint:"All closed node ids, kill order (leaves first, root last)."},{name:"spared",type:"string[]",required:!1,constraint:"Descendants left alive because a manager outside the subtree still subscribes to them."}],outputKind:"object",effects:["Marks retained nodes and their exclusive descendants `canceled` and clears intent (the daemon never revives a canceled node).","Deletes a non-streaming node with no substantive assistant output unless it has an open managed worktree; a deleted node cannot be revived.","Kills each closed node's tmux window; retained nodes keep their pi sessions and canvas edges for a later revive.","Appends a cancellation notice to each retained node's inbox, surfaced on its next resume."]},run:u(async e=>{const t=e.pane??process.env.TMUX_PANE;let n=e.node;if((n===void 0||n==="")&&(n=I(t)),n===void 0||n==="")throw new r({error:"no_node",message:"no node found in this pane to close",next:"Pass --node <id>, or run from inside the agent's pane."});const i=await w().closeNode(n,process.ppid>0?{caller_pid:process.ppid}:{}).catch(d=>y(d,"List nodes with `crtr node inspect list`."));return{node_id:i.root,count:i.closed.length,closed_ids:i.closed,spared:i.spared}},"run"),render:u(e=>{const t=e.spared?.length??0;return`Closed ${e.node_id} and its exclusive subtree \u2014 ${e.count} node(s) closed${t>0?`, ${t} spared (still managed from outside the subtree)`:""}.`},"render")}),j="Model change first: a running broker, including one still starting right after `node new`, switches over its socket; a dormant node persists the durable model override and launch recipe for its next revive.",pe=E({name:"config",description:"reconfigure a node's settings headlessly \u2014 model, lifecycle (terminal/resident), kind, mode, name; repair a missing cwd",whenToUse:"you want to reconfigure a node's settings headlessly after spawn \u2014 swap its model/provider, flip it terminal\u2194resident (interactable), respecialize its kind, switch base\u2194orchestrator mode, or rename it \u2014 without opening its viewer. It also repairs a dormant node whose recorded cwd is gone, starting its next revive in a fresh conversation. The durable attribute setter; reuses the same recipes a revive reads. Use `node promote` for the opinionated self-promotion path, and `node lifecycle` for teardown actions (recycle/close/demote).",help:{name:"node config",summary:"reconfigure a node's settings headlessly \u2014 model, lifecycle, kind, mode, name; repair a missing cwd",params:[{kind:"flag",name:"node",type:"string",required:!1,repeatable:!0,constraint:"Target node id. Defaults to the node in --pane, else CRTR_NODE_ID. Repeat it, or use --nodes-from, to apply a --profile or --cwd change to many nodes; a bulk run reports each node and keeps going past a failure."},{kind:"flag",name:"nodes-from",type:"string",required:!1,constraint:"File of node ids, one per line (blank lines and #-comments ignored), or `-` for stdin. Bulk form of --node; only with --profile or --cwd."},{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane id to resolve the node from. Defaults to $TMUX_PANE."},{kind:"flag",name:"model",type:"string",required:!1,constraint:"Durable model change. Omit unless the task or governing guidance requires a different model.",focusedHelp:{whenToUse:"Use only when intentionally changing this node\u2019s durable model because the user, task, or governing agent guidance requires a specific provider, model, capability tier, or family. Omit it to keep the current model; do not use it merely to inspect available models or experiment with a live node.",value:`Accepted durable forms: ${J}. A live broker also accepts a free-text substring matched against its loaded model registry; a dormant node cannot resolve a substring and requires a durable form.`,effects:[j,"A concrete provider/id runs exactly that model on every launch and revive. A portable provider/tier, bare tier, or family alias keeps its tier: when that model's provider is rate-limited or rejects its credential, the node moves to the next model in its route: another provider's model at the same tier first, then the configured fallback tier (strong by default)."]}},{kind:"flag",name:"lifecycle",type:"enum",choices:["terminal","resident"],required:!1,constraint:"Set lifecycle headlessly without closing the viewer. terminal owes a final and reaps when done; resident stays interactable while attached or awaiting something live."},{kind:"flag",name:"kind",type:"string",required:!1,constraint:"Persona kind. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here."},{kind:"flag",name:"mode",type:"enum",choices:["base","orchestrator"],required:!1,constraint:"Set persona mode headlessly. base is hands-on; orchestrator holds a roadmap and delegates. orchestrator creates your document `roadmap` if absent."},{kind:"flag",name:"name",type:"string",required:!1,constraint:"Rename the node; if the node has a live window, also rename that viewer window."},{kind:"flag",name:"nice",type:"int",required:!1,constraint:`Scheduler niceness every command this node's bash tool starts at, 0\u2013${N} (default ${F}). ${F} keeps the node's builds and test suites below the daemon, the brokers, the viewers, and the person's own shell; 0 lets them compete on equal terms with everything else on the host; ${N} makes them yield to it. Applies to the node's very next command, foreground and background alike.`},{kind:"flag",name:"listen",type:"string",required:!1,constraint:`The node's default listening configuration, as JSON mapping an event level ("1".."10") to how events at or above it reach the node: interrupt, steer, after-turn, or next-turn (e.g. '{"3":"next-turn"}' \u2014 events of level 3+ wait for its next turn and never wake it). Applies to every watch with no configuration of its own. Pass \`null\` to reset to the global default.`},{kind:"flag",name:"cwd",type:"string",required:!1,constraint:"Replacement launch directory (absolute, existing). Alone, or with --keep-session / --restart. Without --keep-session it is a repair: only a dormant, non-forked node with no open managed worktree whose recorded cwd is gone, and it clears the saved Pi session (next revive starts fresh). When the new path is the same directory as the recorded one (a symlink alias) it relocates and keeps the conversation automatically \u2014 see --keep-session."},{kind:"flag",name:"keep-session",type:"bool",required:!1,constraint:"With --cwd: assert the new path is the SAME directory as the recorded cwd and relocate WITHOUT clearing the Pi session. Needed only when the recorded path is already gone (e.g. the symlink was deleted); while it still exists the daemon verifies by realpath and refuses a different directory. Allowed for live, idle, dormant and finished nodes, forks included. Rewrites the recorded cwd and the cwd in the node's transcript header so a later resume finds it. Refused while the node owns an open managed worktree."},{kind:"flag",name:"rewrite-prefix",type:"string",required:!1,constraint:'Bulk cwd form, `OLD=NEW` (absolute paths): with several nodes, each node\'s recorded cwd that equals OLD or lies beneath it is relocated to the same place under NEW, keeping its session (as --keep-session); nodes whose cwd is elsewhere are reported as failed "not under OLD". Use instead of --cwd when the nodes sit in different subdirectories.'},{kind:"flag",name:"profile",type:"string",required:!1,constraint:"Reassign the node to this profile (id or exact name; must be an active profile of the node's app that defines the node's kind). Works for live, idle, dormant, finished and profile-less (detached) nodes. Used alone, or with --restart."},{kind:"flag",name:"restart",type:"bool",required:!1,constraint:"With --profile, or --cwd on a live node: after the change, SIGTERM the node's live broker so crtrd resumes it from the same transcript (continuing an interrupted turn) with the new profile/cwd. No effect on a node with no live broker."}],output:[{name:"node_id",type:"string",required:!1,constraint:"The reconfigured node, present for ordinary config changes."},{name:"model",type:"string",required:!1,constraint:"The resolved model, present only when --model changed it."},{name:"lifecycle",type:"string",required:!1,constraint:"The new lifecycle, present only when --lifecycle changed it."},{name:"kind",type:"string",required:!1,constraint:"The new kind, present only when --kind changed it."},{name:"mode",type:"string",required:!1,constraint:"The new mode, present only when --mode changed it."},{name:"name",type:"string",required:!1,constraint:"The new name, present only when --name changed it."},{name:"nice",type:"number",required:!1,constraint:"The new bash niceness, present only when --nice changed it."},{name:"listen",type:"object",required:!1,constraint:"The new default listening configuration (null = global default), present only when --listen changed it."},{name:"cwd",type:"string",required:!1,constraint:"The resolved replacement directory, present only after a cwd change."},{name:"session_kept",type:"boolean",required:!1,constraint:"With a cwd change: true when the node still has its Pi session bound (conversation preserved)."},{name:"profile",type:"string",required:!1,constraint:"The node's profile id after --profile."},{name:"bulk",type:"boolean",required:!1,constraint:"True for a multi-node run."},{name:"applied",type:"number",required:!1,constraint:"Bulk: nodes changed (or already in the requested state)."},{name:"failed",type:"number",required:!1,constraint:"Bulk: nodes that errored; the exit code is 1 when any did."},{name:"results",type:"array",required:!1,constraint:"Bulk: one {node_id, ok, error?} per node, in input order."}],outputKind:"object",effects:[j,"Kind, mode, and lifecycle changes rebuild the launch spec from the fresh node meta; setting mode to orchestrator creates your document `roadmap` if absent.","Name changes update the row and, when the node already has a live window, rename that viewer window to the new full name.","A cwd repair (gone recorded cwd, no --keep-session) writes only the lexically resolved cwd and clears saved Pi session pointers; the old transcript and durable node work remain untouched.","A session-keeping cwd relocation (--keep-session, or --cwd naming a symlink alias of the recorded directory) rewrites the recorded cwd and the cwd line in the header of each of the node's transcripts; the Pi session stays bound and the next revive resumes the same conversation. A LIVE broker keeps the old cwd string in its environment and tools until it restarts: it keeps working while the old path exists, so pass --restart (or revive it) BEFORE deleting an old symlink.","A profile reassignment rewrites the node's profile and rebuilds its launch recipe. Profile env, documents delivered at boot, purview and bearings are read at launch, so a LIVE broker keeps the old profile until it next restarts; --restart bounces it now. Dormant or finished nodes simply carry the new profile into their next revive. The node's deadlines and profile pause follow the new profile immediately.","A niceness change is stored with the node's own bash-job state, so it takes effect on the next command without a revive and survives one.","A listen change sets the node's default listening configuration; it never changes which watches it holds.","Every successful change publishes a `configured` event on the node (level 1) naming the changed settings, so its watchers can see it."]},helpState:{leaf:C},run:u(async e=>{const t=e.pane??process.env.TMUX_PANE,n=e.node,i=Array.isArray(n)?n:n===void 0?[]:[n],d=e.nodesFrom;if(d!==void 0){const a=d==="-"?W(0,"utf8"):W(d,"utf8");for(const A of a.split(`
+`)){const b=A.replace(/#.*/,"").trim();b!==""&&i.push(b)}}const o=e.profile,h=e.cwd,f=e.rewritePrefix;if(i.length>1||d!==void 0||f!==void 0){if(i.length===0)throw new r({error:"no_nodes",message:"bulk config needs at least one node",next:"Pass --node ID (repeatable) or --nodes-from FILE|-."});if(o===void 0&&h===void 0&&f===void 0)throw new r({error:"bulk_unsupported",message:"several nodes are accepted only with --profile, --cwd or --rewrite-prefix",next:"Pass --profile <profile>, --cwd <dir> or --rewrite-prefix OLD=NEW with the node list."});let a;if(f!==void 0){const p=f.indexOf("="),c=p<0?"":f.slice(0,p).replace(/\/+$/,""),m=p<0?"":f.slice(p+1).replace(/\/+$/,"");if(!c.startsWith("/")||!m.startsWith("/"))throw new r({error:"bad_rewrite_prefix",message:`--rewrite-prefix must be OLD=NEW with absolute paths: ${f}`,field:"rewrite-prefix",next:"Pass e.g. --rewrite-prefix /Users/me/Code/northlight=/Users/me/Code/crouter-cloud."});a=[c,m]}const A=w(),b=[];for(const p of[...new Set(i)])try{const c=o!==void 0?{profile:o}:{cwd:h??""};if(a!==void 0){const m=(await A.getNode(p)).cwd;if(m!==a[0]&&!m.startsWith(`${a[0]}/`))throw new Error(`cwd ${m} is not under ${a[0]}`);c.cwd=a[1]+m.slice(a[0].length),c.keep_session=!0}e.keepSession===!0&&(c.keep_session=!0),e.restart===!0&&(c.restart=!0),await A.patchConfig(p,c),b.push({node_id:p,ok:!0})}catch(c){let m=c instanceof Error?c.message:String(c);try{y(c)}catch(U){U instanceof Error&&(m=U.message)}b.push({node_id:p,ok:!1,error:m})}const P=b.filter(p=>!p.ok).length;return P>0&&(process.exitCode=1),{bulk:!0,applied:b.length-P,failed:P,results:b}}const _=await M({...e,node:i[0]},t),x=h;if(x!==void 0&&["model","kind","lifecycle","mode","name","nice","listen","profile"].some(a=>e[a]!==void 0))throw new r({error:"cwd_not_exclusive",message:"cwd cannot be combined with another config flag except --keep-session and --restart",field:"cwd",next:"Pass --cwd alone (plus --keep-session / --restart)."});if(o!==void 0&&["model","kind","lifecycle","mode","name","nice","listen"].some(a=>e[a]!==void 0))throw new r({error:"profile_not_exclusive",message:"profile cannot be combined with another config flag except --restart",field:"profile",next:"Pass --profile alone (plus --restart)."});if(e.keepSession===!0&&x===void 0)throw new r({error:"keep_session_needs_cwd",message:"--keep-session only applies with --cwd",field:"keep-session",next:"Pass --cwd <dir> --keep-session."});if(e.restart===!0&&x===void 0&&o===void 0)throw new r({error:"restart_needs_change",message:"--restart only applies with --profile or --cwd",field:"restart",next:"Pass --profile <profile> or --cwd <dir> with --restart."});const S=e.model?.trim();if(S==="")throw new r({error:"empty_spec",message:"a model spec is required",field:"model",next:"Run `crtr node config --model -h` and read the focused contract before retrying."});const O=e.kind?.trim(),T=e.lifecycle?.trim(),q=e.mode?.trim(),L=e.name,v=e.nice,$=e.listen?.trim();let R;if($!==void 0)try{R=JSON.parse($)}catch{throw new r({error:"invalid_listen",message:`--listen is not JSON: ${$}`,field:"listen",next:`Pass a JSON object such as '{"3":"next-turn"}', or null.`})}if(v!==void 0&&(v<0||v>N))throw new r({error:"bad_nice",message:`niceness must be between 0 and ${N}: ${v}`,field:"nice",next:`A negative niceness needs root, so pass 0\u2013${N}.`});if(T!==void 0&&T.toLowerCase()!=="terminal"&&T.toLowerCase()!=="resident")throw new r({error:"bad_lifecycle",message:`invalid lifecycle: ${T}`,field:"lifecycle",next:"Pass `terminal` or `resident`."});if(q!==void 0&&q.toLowerCase()!=="base"&&q.toLowerCase()!=="orchestrator")throw new r({error:"bad_mode",message:`invalid mode: ${q}`,field:"mode",next:"Pass `base` or `orchestrator`."});const s=[],l={};if(S!==void 0&&(l.model=S,s.push("model")),O!==void 0&&(l.kind=O,s.push("kind")),T!==void 0&&(l.lifecycle=T.toLowerCase(),s.push("lifecycle")),q!==void 0&&(l.mode=q.toLowerCase(),s.push("mode")),L!==void 0&&(l.name=L,s.push("name")),x!==void 0&&(l.cwd=x,s.push("cwd"),e.keepSession===!0&&(l.keep_session=!0),e.restart===!0&&(l.restart=!0)),o!==void 0&&(l.profile=o,s.push("profile"),e.restart===!0&&(l.restart=!0)),$!==void 0&&(l.listen=R??null,s.push("listen")),v!==void 0){const a=await w().getNode(_).catch(A=>y(A));if(X(a.paths.context_dir,v),s.push("nice"),s.length===1)return{node_id:_,nice:v}}if(s.length===0)throw new r({error:"no_change",message:"no config changes requested",next:"Pass at least one of --model, --lifecycle, --kind, --mode, --name, --nice, --listen, --cwd."});const g=await w().patchConfig(_,l).catch(a=>y(a,"List nodes with `crtr node inspect list`."));if(x!==void 0)return{cwd:g.cwd,node_id:_,...l.keep_session===!0||g.pi_session_id!=null?{session_kept:g.pi_session_id!=null}:{}};if(o!==void 0)return{node_id:_,profile:g.profile_id??null};const k={node_id:_};return s.includes("model")&&(k.model=g.model_override??S),s.includes("lifecycle")&&(k.lifecycle=g.lifecycle),s.includes("kind")&&(k.kind=g.kind),s.includes("mode")&&(k.mode=g.mode),s.includes("name")&&(k.name=g.name),s.includes("nice")&&(k.nice=v),s.includes("listen")&&(k.listen=l.listen),k},"run"),render:u(e=>{if(e.bulk===!0){const n=e.results;return[`Applied to ${e.applied} node(s), ${e.failed} failed.`,...n.filter(i=>!i.ok).map(i=>`  FAILED ${i.node_id}: ${i.error}`)].join(`
+`)}if(e.cwd!==void 0)return`Set cwd of ${e.node_id}: ${e.cwd}${e.session_kept===!0?" (conversation kept)":""}.`;if(e.profile!==void 0)return`Reassigned ${e.node_id} to profile ${e.profile}.`;const t=[];return e.model!==void 0&&t.push(`model=${e.model}`),e.lifecycle!==void 0&&t.push(`lifecycle=${e.lifecycle}`),e.kind!==void 0&&t.push(`kind=${e.kind}`),e.mode!==void 0&&t.push(`mode=${e.mode}`),e.name!==void 0&&t.push(`name=${e.name}`),e.nice!==void 0&&t.push(`nice=${e.nice}`),e.listen!==void 0&&t.push(`listen=${JSON.stringify(e.listen)}`),`Configured ${e.node_id} \u2014 ${t.join(", ")}`},"render")}),me=E({name:"promote",description:"become an orchestrator of a chosen kind",whenToUse:"the remaining work contains independent units that can run in parallel, and the task is large enough that coordinating and integrating them will materially improve intelligence, productivity, or elapsed throughput. Become a long-lived, roadmap-holding orchestrator whose primary job is steering those children across refreshes (`node yield`). Keep sequential or tightly coupled work in base mode even when it spans phases or context windows; spawning one helper does not itself require promotion",tier:"important",help:{name:"node promote",summary:"promote yourself to an orchestrator when worthwhile parallel delegation should make coordination your primary job; task duration, sequential phases, or one helper do not qualify. Mode only \u2014 lifecycle stays as-is unless you pass --resident",params:[{kind:"flag",name:"kind",type:"string",required:!1,constraint:"Specialize as this kind of orchestrator. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here. For an exact composed persona list, use `crtr sys context prompt-review --list --kind <kind>` with the target kind. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one \u2014 it sets the orchestrator persona you revive into."},{kind:"flag",name:"resident",type:"bool",required:!1,constraint:"ALSO flip lifecycle\u2192resident: make the node interactable \u2014 it is never forced to submit a final, and unattended grace parks it after a summary turn instead, leaving it revivable fresh against its goal and roadmap. Omit to stay terminal/orchestrator (delegates + holds a roadmap, but still owes a final up the spine and reaps when done)."},{kind:"flag",name:"model",type:"enum",choices:["ultra","strong"],required:!1,constraint:"Change the model you run on, by capability tier: `ultra` (frontier \u2014 reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus \u2014 regular dev work). Omit to keep your current model. An orchestrator steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives."},{kind:"flag",name:"node",type:"string",required:!1,constraint:"Node to promote. Defaults to the caller (CRTR_NODE_ID)."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The promoted node."},{name:"kind",type:"string",required:!0,constraint:"The kind it now orchestrates as."},{name:"model",type:"string",required:!1,constraint:"The model tier it now runs on, present only when you changed it with --model."},{name:"lifecycle",type:"string",required:!0,constraint:'"resident" if you passed --resident, else unchanged (typically "terminal").'},{name:"roadmap_written",type:"boolean",required:!0,constraint:"True if the `roadmap` document was created by this call."},{name:"roadmap_ref",type:"string",required:!0,constraint:"Your roadmap document (`<node>/roadmap`) \u2014 author your plan with `crtr doc edit roadmap`."},{name:"goal_path",type:"string",required:!0,constraint:"Absolute path to your goal doc (context/initial-prompt.md) \u2014 the mandate you were spawned with."}],outputKind:"object",effects:["Flips mode\u2192orchestrator + kind\u2192chosen (lifecycle unchanged unless --resident, which also flips lifecycle\u2192resident); --model durably sets the model; rewrites the launch spec to that kind's orchestrator persona; creates your document `roadmap` (rule `on: boot`, `deliver: content`) if absent.","The next model request is gated on appending and persisting your new-role guidance. If a fresh context starts first, its rebuilt baseline carries the new role."]},helpState:{leaf:C},run:u(async e=>{const t=e.node??D();if(t===void 0||t==="")throw new r({error:"no_node",message:"no node to promote (set CRTR_NODE_ID or pass --node)",next:"Run from inside a node, or pass --node <id>."});const n=e.kind,i=e.model,d=e.resident===!0,o=await w().promoteNode(t,{...n!==void 0?{kind:n}:{},...d?{resident:!0}:{},...i!==void 0?{model:i}:{}}).catch(h=>y(h));return{node_id:o.node_id,kind:o.kind,lifecycle:o.lifecycle,...i!==void 0&&o.model_override!=null?{model:o.model_override}:{},roadmap_written:o.roadmap_written??!1,roadmap_ref:o.roadmap_ref??"",goal_path:o.goal_path??""}},"run")});async function M(e,t){let n=e.node;if((n===void 0||n==="")&&(n=I(t)),(n===void 0||n==="")&&(n=D()),n===void 0||n==="")throw new r({error:"no_node",message:"no node (set CRTR_NODE_ID, pass --node, or run from the agent's pane)",next:"Run from inside a node, pass --node <id>, or --pane <pane>."});if(await K(n)===null)throw new r({error:"not_found",message:`no node: ${n}`,next:"List nodes with `crtr node inspect list`."});return n}u(M,"resolveLifecycleNode");const te=E({name:"demote",description:"demote a node to terminal in place; it stays focused and running but now owes a final; --detach also closes its viewer (broker keeps running off-screen)",whenToUse:"you are watching a resident/interactive node and want to put it on a finishing track WITHOUT disturbing it: flip it terminal IN PLACE \u2014 it keeps its viewer and your focus, keeps running, but now owes a final report up the spine and reaps when done. The friendly counterpart to `node promote`. You can also let go entirely and close its viewer so the agent finishes off-screen on its broker. Use `node lifecycle recycle` instead to FINISH it now and reboot a fresh root in its pane, and `node config --lifecycle` for the orthogonal low-level flip (incl. terminal\u2192resident)",help:{name:"node lifecycle demote",summary:"demote a node to terminal IN PLACE \u2014 it stays focused and running but now owes a final up the spine and reaps when done. Pairs with `node promote` (mode\u2191); `--detach` also closes its viewer (the broker engine keeps running off-screen)",params:[{kind:"flag",name:"node",type:"string",required:!1,constraint:"Node to demote. Defaults to the node in --pane, else the caller (CRTR_NODE_ID)."},{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane id whose node to demote, when --node is omitted. Defaults to $TMUX_PANE. The Alt+C menu passes this for you."},{kind:"flag",name:"detach",type:"bool",required:!1,constraint:"After flipping terminal, stop foregrounding the agent by closing its viewer pane. The broker engine keeps generating off-screen and \u2014 now terminal \u2014 pushes a final up the spine when done; a later `focus` reattaches a viewer. The Alt+C \u2192 D move."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The demoted node."},{name:"detached",type:"boolean",required:!1,constraint:"True when --detach closed the agent's viewer pane (broker keeps running)."}],outputKind:"object",effects:["Flips the node's lifecycle\u2192terminal and rebuilds its launch spec so a future revive boots terminal \u2014 it stays focused and running, now owing a final up the spine.","The next model request is gated on appending and persisting the role transition. If a fresh context starts first, its rebuilt baseline carries the new lifecycle.","With --detach: closes the agent's viewer pane WITHOUT touching the broker engine \u2014 it keeps generating off-screen, reconnectable by a later `focus`."]},run:u(async e=>{const t=e.pane??process.env.TMUX_PANE,n=await M(e,t),i=await w().patchConfig(n,{lifecycle:"terminal"}).catch(o=>y(o));let d=!1;if(e.detach===!0){const o=Z(n)??t;o!==void 0&&o!==""&&G(o)&&(d=z(o))}return{node_id:i.node_id,detached:d}},"run"),render:u(e=>`Demoted ${e.node_id} \u2014 lifecycle now terminal (in place)${e.detached===!0?", viewer closed (broker still running off-screen)":""}.`,"render")}),ge=H({name:"lifecycle",description:"lifecycle actions \u2014 recycle, close, demote, or revive a node",whenToUse:"you are ending, transitioning, or bringing back one node you can name: finish the agent in your pane and reboot a fresh root (`recycle`), tear a node + its exclusive subtree down without finishing (`close`), flip a node onto a finishing track in place (`demote`), or bring a dormant node back (`revive`). To merely SET the terminal/resident attribute headlessly use `node config --lifecycle`; to FINISH from inside a node's own turn use `crtr push final`; to mass-reconnect EVERY disconnected node at once use `canvas revive --all`.",help:{name:"node lifecycle",summary:"end, transition, or revive a node \u2014 recycle the pane, close + cascade-cancel a subtree, demote to terminal in place, or revive a dormant node",model:"Lifecycle actions preserve or replace an existing node identity. Finishing is permanent, closing is revivable, demotion changes the completion obligation in place, and revival relaunches a dormant broker. Teardown cascades only through descendants exclusively managed by the affected subtree."},children:[ee,ne,te,Y]}),we=E({name:"yield",description:"refresh your context, same mode, against your roadmap or goal",whenToUse:"your context is filling but the mandate remains; refresh in the same mode, or combine the refresh with promotion when meaningful independent work can run in parallel and coordinating it should become your primary job",help:{name:"node yield",summary:"request a fresh context window against your roadmap or original goal; mode stays unchanged unless --promote is passed",guide:"The yield aborts your turn the instant this command returns: no text or tool call you planned after it will run. So anything the user is owed \u2014 an answer, a status \u2014 must already be a visible message in the conversation before you call it; never plan to reply after yielding. Before invoking: (1) If you hold a document `roadmap`, bring it current (`crtr doc edit roadmap`). It, not the yield note, carries your task into the fresh window. It has four sections: Goal (its first line is also the roadmap\u2019s preview, so set it with `--preview` whenever the goal changes), Exit criteria, Where things stand, and Working set. Keep it at your own level of abstraction. Detail below your level belongs to the node or document that holds it: link to it, don\u2019t copy it. Where things stand is present tense; delete what is done instead of marking it. Name units by what they are and how they fit, never by child node id or status: your bearings already list your children with their status. Working set holds `[[links]]`. Their previews load with the roadmap, so write no note beside a link. When a unit lands, delete its links: its evidence belongs in its report. (2) Give content its own document when it lives on a different timescale from the roadmap (exploration that outlives the current work), goes to a different reader (a brief for a child), or matters only when something specific happens. Link each such document from the Working set. Anything you had to re-derive in this window that a future window will need again belongs in a document: one you own for this task, `--owner repo` for lessons that would help others in the repo. A document that only points at other documents is not worth the extra hop. (3) Actions waiting on one specific event (\u201Cwhen X reports, send Y first\u201D) go in the yield note, not the roadmap. They are spent once they fire. (4) Send any pending human question; asks already in flight survive the refresh.",params:[{kind:"flag",name:"promote",type:"bool",required:!1,constraint:"Also become an orchestrator as you refresh. Pass only when (1) the remaining work contains independent units that can run in parallel and (2) the task is large enough that parallel execution will materially improve intelligence, productivity, or elapsed throughput after coordination and synthesis. Task length, context exhaustion, sequential phases, or one helper are not enough; keep hands-on work in base mode and yield again as needed. Promote when coordinating and integrating children becomes your primary job. Already an orchestrator? This is not an error: your mode stays orchestrator and a missing roadmap is seeded."},{kind:"flag",name:"kind",type:"string",required:!1,constraint:"Respecialize as you refresh. The <kinds> list below names every top-level available kind and when to choose it; a registered sub-kind is valid too by exact path but not listed here. Defaults to your current kind. With --promote it sets the orchestrator kind you become; without --promote it changes the kind while preserving your current mode."},{kind:"flag",name:"model",type:"enum",choices:["ultra","strong"],required:!1,constraint:"Change the model your fresh revive runs on, by capability tier: `ultra` (frontier \u2014 reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus \u2014 regular dev work). Omit to keep your current model. A node steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives."},{kind:"stdin",name:"message",required:!0,constraint:"A note to your future self \u2014 what you just tried, where things stand, the first move on waking, and any action waiting on a specific event: enough to continue efficiently, no more. Never describe a reply as sent unless it is visible in the conversation above this call. Your task and its state belong in the roadmap. Surfaced as <yield-message> in the next revive. Pass as a positional or pipe via heredoc."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The yielding node."},{name:"model",type:"string",required:!1,constraint:"The model tier your fresh revive will run on, present only when you changed it with --model."}],outputKind:"object",effects:["Aborts your current turn as soon as this command returns \u2014 nothing after it runs \u2014 then the daemon revives the node fresh.","--kind and/or --model durably reshape the node (kind respecialization, model change) before the refresh-revive; --promote additionally flips mode\u2192orchestrator and creates your document `roadmap` \u2014 mode is otherwise left exactly as it was."]},helpState:{leaf:C},run:u(async e=>{const t=D();if(t===void 0||t==="")throw new r({error:"no_node",message:"no node to yield (CRTR_NODE_ID unset)",next:"Run from inside a node."});const n=e.kind,i=e.model,d=e.promote===!0,o=typeof e.message=="string"?e.message.trim():"";if(o==="")throw new r({error:"empty_message",message:"a yield message is required (stdin or positional)",next:"Pass a note to your future self as an argument or pipe it on stdin."});const h=await w().yieldNode(t,{note:o,...n!==void 0?{kind:n}:{},...i!==void 0?{model:i}:{},...d?{promote:!0}:{}}).catch(f=>y(f));return{node_id:h.node_id,...i!==void 0&&h.model_override!=null?{model:h.model_override}:{}}},"run")});export{pe as nodeConfig,ge as nodeLifecycle,me as nodePromote,we as nodeYield};

package/dist/commands/node/message.d.ts

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

package/dist/commands/node/message.js

@@ -0,0 +1 @@
+var _=Object.defineProperty;var i=(e,n)=>_(e,"name",{value:n,configurable:!0});import{envNodeId as y}from"../../shared/env.js";import{defineBranch as C,defineLeaf as w}from"../../core/command.js";import{InputError as o}from"../../core/io.js";import{requireScope as N}from"../../core/errors.js";import{OUTPUT_SCHEMA_CONSTRAINTS as R,OUTPUT_SCHEMA_TRANSPORT as P,parseOutputSchemaValue as E}from"../../core/runtime/structured-output.js";import{cliClient as A,getNodeOrNull as O,rethrowAsCliError as $}from"../api-client.js";function D(e,n){const t=e[n];if(t!==void 0&&(typeof t!="string"||t.trim()==="")){const r=n.replace(/[A-Z]/g,a=>`-${a.toLowerCase()}`);throw new o({error:"empty_discriminant",message:`--${r} must contain non-whitespace text`,received:typeof t=="string"?t:String(t),field:r,next:`Pass a non-empty --${r} value, or omit the flag.`})}}i(D,"requireNonBlankDiscriminant");async function U(e,n){const t=e.to?.trim(),r=e.self===!0,a=t!==void 0&&t!=="";if(a===r)throw new o({error:"bad_target",message:a&&r?"--to and --self are mutually exclusive":n?"no target given \u2014 the message body is not a node id":"exactly one of --to or --self is required",field:a?void 0:"to",next:a?"Pass --to <node-id> or --self.":n?"Pass the node id with --to <node-id> and provide the message body as a positional argument or on stdin, or use --self.":"Pass --to <node-id> or --self."});if(r){const s=y();if(s===void 0||s==="")throw new o({error:"no_node",message:"no node to target with --self (CRTR_NODE_ID unset)",next:"Run from inside a node, or pass --to <node-id>."});return{targetId:s,isSelf:!0}}if(await O(t)===null)throw new o({error:"not_found",message:`no node: ${t}`,field:"to",next:"List nodes with `crtr node inspect list`."});return{targetId:t,isSelf:!1}}i(U,"resolveMsgTarget");function v(){return[{name:"revived",type:"boolean",required:!1,constraint:"True when this request synchronously revived the target; ordinary durable delivery to an active or idle dormant target queues lifecycle revival instead."},{name:"guidance",type:"string",required:!0,constraint:"Immediate action confirmation."}]}i(v,"messageOutput");function b(e){const n=e.to?.trim();if(!(n!==void 0&&n!==""||e.self===!0))return{message:"no target given \u2014 the positional argument is the message body, not a node id",field:"to",next:"Pass the node id with --to <node-id> and pipe the message body on stdin, or use --self."}}i(b,"missingMessageTargetForBody");function I(){return[{kind:"stdin",name:"body",required:!1,constraint:"Visible message body. Required unless --situational-context is supplied.",positionalStdinConflict:b},{kind:"flag",name:"to",type:"string",required:!1,constraint:"Target an existing node by id. Exactly one of --to or --self is required."},{kind:"flag",name:"self",type:"bool",required:!1,constraint:"Target the calling node. Exactly one of --to or --self is required."},{kind:"flag",name:"tier",type:"enum",choices:["critical","urgent","normal","deferred"],required:!1,default:"normal",constraint:"Delivery urgency. Deferred never wakes an idle node, except a terminal one, which has no later cycle to read it on and is raised to urgent."},{kind:"flag",name:"situational-context",type:"string",required:!1,constraint:"Non-empty hidden ambient context delivered beside the message, or alone."},{kind:"flag",name:"reopen",type:"bool",required:!1,constraint:"Re-task the target: commits it resident and clears any finalization latch before delivery. Valid for live, parked, and finalized targets."}]}i(I,"messageSendParams");function M(){return[{kind:"stdin",name:"body",required:!1,constraint:"Visible message body. The schema alone is a complete request.",positionalStdinConflict:b},{kind:"flag",name:"to",type:"string",required:!1,constraint:"Target an existing node by id. Exactly one of --to or --self is required."},{kind:"flag",name:"self",type:"bool",required:!1,constraint:"Target the calling node. Exactly one of --to or --self is required."},{kind:"flag",name:"tier",type:"enum",choices:["critical","urgent","normal"],required:!1,default:"normal",constraint:"Delivery urgency. Every accepted tier queues lifecycle revival for an active or idle dormant target because the request must be answered; deferred is rejected for that reason."},{kind:"flag",name:"output-schema",type:"string",required:!0,constraint:`JSON Schema the result must satisfy. ${P} The target answers with \`crtr push result\` (or declines with \`crtr push result --decline "<reason>" --code <token>\`), then keeps working. ${R}`},{kind:"flag",name:"situational-context",type:"string",required:!1,constraint:"Non-empty hidden ambient context delivered beside the message, or alone."},{kind:"flag",name:"reopen",type:"bool",required:!1,hidden:!0,constraint:"Clear a finalized target latch before delivery or fresh revive."}]}i(M,"messageRequestParams");async function x(e){N("crtr:act","crtr node message");const n=e.situationalContext!==void 0,t=e.situationalContext?.trim();if(n&&t==="")throw new o({error:"empty_situational_context",message:"--situational-context must contain non-whitespace text",field:"situational-context",next:"Pass non-whitespace text, or omit --situational-context."});const r=e.body,a=r!==void 0?r.trim():void 0,m=a!==void 0&&a!=="",{targetId:s}=await U(e,m),u=e.tier,q=u!==void 0&&u!=="",f=E(e.outputSchema),c=f!==null?JSON.stringify(f):null,g=t!==void 0&&t!=="",k=e.reopen===!0;if(c!==null&&u==="deferred")throw new o({error:"output_schema_deferred_tier",message:"--output-schema cannot combine with --tier deferred because the target must answer",field:"tier",next:"Use normal, urgent, or critical tier, or drop --output-schema."});const h=y(),T=A();if(!m&&!g&&c===null)throw new o({error:"empty_body",message:"a message body is required unless --output-schema or --situational-context is supplied",field:"body",next:"Pass the message on stdin, or supply one of the documented alternatives."});const p=q?u:"normal",d=await T.sendMessage(s,{body:a??"",tier:p,...k?{reopen:!0}:{},...g?{situational_context:t}:{},...c!==null?{output_schema:c}:{},...h!==void 0?{from:h}:{}}).catch($);if(d.wake_failed!==void 0){const l=d.wake_failed;return{revived:!1,guidance:`Accepted but NOT delivered to a running node \u2014 waking the target failed (${l.error}): ${l.message}${l.next===void 0?"":` ${l.next}`} The message is queued durably (${l.message_id}); do not resend it.`}}const S=d.revived?"Delivered \u2014 the dormant target was revived to receive it.":p!=="deferred"?"Delivered.":d.delivered_tier===void 0?"Delivered \u2014 held for the target's next natural cycle; not revived.":"Delivered \u2014 the target is terminal and takes no later cycle, so it was raised to urgent rather than held.";return{revived:d.revived,guidance:S}}i(x,"runMessageEngine");const j=w({name:"send",description:"deliver an inbox message to an existing node immediately",whenToUse:"a target chosen with `--to <node-id>` or `--self` should have information or new direction now \u2014 steering a worker mid-task, handing over a finding it needs, correcting a wrong turn, or waking a dormant node with fresh work. The target reads it and decides what to do with it. Use `node message request` instead when you need an answer back in a shape you specify, and `node subscription add` when the target should keep receiving this node\u2019s pushes rather than this one delivery",help:{name:"node message send",summary:"deliver an inbox message to an existing node immediately",params:I(),output:v(),outputKind:"object",effects:["Appends one inbox entry. Critical, urgent, and normal delivery queues lifecycle revival for an active or idle dormant target; deferred waits for its next natural cycle.","--reopen commits the target resident and clears any finalization latch before delivery, allowing it to take a new mandate; it is valid for live, parked, and finalized targets. Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted."]},run:i(e=>x(e),"run"),render:i(e=>String(e.guidance),"render")}),z=w({name:"request",description:"deliver an immediate typed-output request to an existing node",whenToUse:"a target chosen with `--to <node-id>` or `--self` must hand back one answer in a shape you fix \u2014 a choice among options, a structured extraction, a verdict your own logic will branch on \u2014 or must be held to answering at all before it goes quiet. Use `node message send` instead when prose in the target\u2019s own judgment is enough, and `node new --output-schema` when no node holds the context yet and the work needs a fresh agent",help:{name:"node message request",summary:"deliver an immediate typed-output request to an existing node",params:M(),output:v(),outputKind:"object",effects:["Installs the one-off output schema before appending the request."]},run:i(e=>(D(e,"outputSchema"),x(e)),"run"),render:i(e=>String(e.guidance),"render")}),G=C({name:"message",description:"deliver immediate inbox work to an existing node",whenToUse:"you need one immediate delivery: send ordinary information, or request one schema-constrained result",help:{name:"node message",summary:"deliver one immediate inbox entry to an existing node",model:"Both children append one inbox entry to a node that already exists, targeted with `--to <node-id>` or `--self`, and may revive it if it is dormant. They differ in what the delivery obligates. An ordinary message obligates nothing: the target reads it and acts however it judges best. A request installs a one-off output schema and holds the target awake and owing until it answers; the answer is validated against the schema, written to the target\u2019s result file, and pushed as an update report to the TARGET\u2019S subscribers, so subscribe to it first if the answer has to reach you. Neither child creates that standing relationship \u2014 a durable delivery edge is `node subscription`, and work that needs a fresh agent is `node new`."},children:[j,z]});export{G as nodeMessage};

package/dist/commands/node/outcome.d.ts

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

package/dist/commands/node/outcome.js

@@ -0,0 +1,4 @@
+var l=Object.defineProperty;var n=(e,t)=>l(e,"name",{value:t,configurable:!0});import{isSafeNodeId as c}from"../../api/index.js";import{defineBranch as m,defineLeaf as a}from"../../core/command.js";import{InputError as i}from"../../core/io.js";import{cliClient as d,rethrowAsCliError as s}from"../api-client.js";function u(e){const t=typeof e.node=="string"?e.node.trim():"";if(!c(t))throw new i({error:"invalid_node",message:`invalid node id: ${t===""?"(empty)":t}`,field:"node",next:"Pass the exact node id returned when the node was created."});return t}n(u,"nodeId");function o(e){return e==null?"none":JSON.stringify(e)}n(o,"renderedJson");const p=a({name:"read",description:"read or briefly await a node\u2019s durable terminal outcome",whenToUse:"an external caller needs the durable result or failure reason for one node, optionally blocking for its terminal outcome without consuming or claiming it",help:{name:"node outcome read",summary:"read a node\u2019s durable outcome, optionally awaiting it for up to 25 seconds",params:[{kind:"positional",name:"node",required:!0,constraint:"Node id whose durable outcome to read."},{kind:"flag",name:"wait",type:"int",required:!1,default:0,constraint:"Whole seconds to await settlement: 0\u201325. Omit or use 0 to return the current pending/settled state immediately."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The requested node id."},{name:"state",type:"string",required:!0,constraint:"`pending` while the node has no terminal outcome, otherwise `settled`."},{name:"outcome",type:"object",required:!0,constraint:"The durable result/failure record when settled \u2014 kind/reason, revision, settled time, report basename/path, structured result, failure detail, and `declined` ({ reason, code, retryable } for a failure with reason `declined`, else null) \u2014 otherwise null."},{name:"node_status",type:"string",required:!0,constraint:"The node status observed with the outcome."},{name:"deadline_at",type:"string",required:!0,constraint:"The absolute spawn deadline, or null when unbounded."}],outputKind:"object",effects:["Read-only: calls the daemon\u2019s replay-safe GET outcome route. With --wait, the daemon polls the durable row for no more than 25 seconds."]},run:n(async e=>{const t=u(e),r=e.wait;if(typeof r!="number"||!Number.isInteger(r)||r<0||r>25)throw new i({error:"invalid_wait",message:"--wait must be an integer between 0 and 25 seconds",field:"wait",received:r,next:"Pass a whole number from 0 through 25, or omit --wait to poll immediately."});return{...await d().getNodeOutcome(t,{waitSeconds:r}).catch(s)}},"run"),render:n(e=>{const t=e.outcome;return t===null?[`<outcome state="pending" node_id="${e.node_id}">`,`- node status: ${e.node_status}`,`- deadline: ${e.deadline_at??"none"}`,"</outcome>"].join(`
+`):[`<outcome kind="${t.kind}" reason="${t.reason}" state="settled" node_id="${e.node_id}" revision="${t.revision}">`,`- final report: ${t.final_report===null||t.final_report===void 0?"none":`${t.final_report} (read with \`crtr canvas read ${t.final_report}\`)`}`,`- structured result: ${o(t.structured_result)}`,`- declined: ${o(t.declined)}`,`- failure detail: ${o(t.detail)}`,`- settled at: ${t.settled_at}`,`- node status: ${e.node_status}`,`- deadline: ${e.deadline_at??"none"}`,"</outcome>"].join(`
+`)},"render")}),h=a({name:"delivery",description:"inspect a node outcome-delivery registration",whenToUse:"you need the durable state of the local action target registered to receive a node\u2019s outcome",help:{name:"node outcome delivery",summary:"inspect the registered outcome-delivery target for one node",params:[{kind:"positional",name:"node",required:!0,constraint:"Node id whose outcome-delivery registration to inspect."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The node whose outcome is delivered."},{name:"state",type:"string",required:!0,constraint:"`armed`, `pending`, `running`, `accepted`, or `permanent_failed`."},{name:"action",type:"string",required:!0,constraint:"The resolved configured action name."},{name:"attempt",type:"number",required:!0,constraint:"How many delivery attempts have been claimed."},{name:"next_attempt_at",type:"string",required:!0,constraint:"ISO-8601 time of the next retry, or null before a retry is scheduled (including while armed)."},{name:"accepted_at",type:"string",required:!0,constraint:"When the target accepted the document, or null."},{name:"permanent_failed_at",type:"string",required:!0,constraint:"When the target permanently rejected the document, or null."},{name:"last_failure",type:"object",required:!0,constraint:"The most recent retryable or permanent delivery failure, or null."},{name:"created_at",type:"string",required:!0,constraint:"When this delivery registration was created."},{name:"updated_at",type:"string",required:!0,constraint:"When this delivery registration was last updated."}],outputKind:"object",effects:["Read-only: calls the daemon outcome-delivery inspection route."]},run:n(async e=>{const t=u(e);return{...await d().getOutcomeDelivery(t).catch(s)}},"run"),render:n(e=>[`<outcome-delivery state="${e.state}" node_id="${e.node_id}">`,`- attempt: ${e.attempt}`,`- next retry: ${e.next_attempt_at??"none"}`,`- last failure: ${o(e.last_failure)}`,`- action: ${e.action}`,`- accepted at: ${e.accepted_at??"none"}`,`- permanently failed at: ${e.permanent_failed_at??"none"}`,`- registered at: ${e.created_at}`,`- updated at: ${e.updated_at}`,"</outcome-delivery>"].join(`
+`),"render")}),b=m({name:"outcome",description:"read a node\u2019s terminal outcome or its delivery state",whenToUse:"you need the durable terminal result/failure of one node, or the state of its registered outcome-delivery target",help:{name:"node outcome",summary:"read one node\u2019s durable terminal outcome or its delivery registration",model:"Outcome reads never consume the terminal record. Read returns the durable result or failure and can wait briefly for settlement; delivery inspects the separate action-registration attempt state."},children:[p,h]});export{b as nodeOutcome,h as nodeOutcomeDelivery};

package/dist/commands/node/pyramid.d.ts

@@ -0,0 +1,2 @@
+import type { SlashSpec } from '../../core/command.js';
+export declare const pyramidSlash: SlashSpec;

package/dist/commands/node/pyramid.js

@@ -0,0 +1,2 @@
+const e={name:"pyramid",description:"Explain a topic as a live-building Minto pyramid diagram, backed by parallel explore agents.",argumentHint:"<topic to explain>",body:["# Pyramid explanation","","Explain **$ARGUMENTS** as a *pyramid*: lead with the answer, support it with a few key pillars, ground each pillar in evidence. You build this as a LIVE termrender diagram that fills in as parallel research lands \u2014 the user watches the skeleton grow into a complete picture.","","## The pyramid (Minto principle)","- **Apex** \u2014 ONE crisp sentence: the single governing answer/claim, the thing worth remembering.","- **Pillars** \u2014 2\u20134 MECE supporting arguments that together prove the apex.","- **Base** \u2014 concrete evidence under each pillar (mechanisms, `file:line` refs, numbers, sources).","","Top-down: the reader gets the conclusion first, then descends for as much support as they want.","","## Workflow","","1. **Frame it.** Restate the topic in one line and commit to a *working* apex hypothesis (you will sharpen it). Name the 2\u20134 pillars you expect to need.","","2. **Scaffold the live diagram FIRST.** Write the termrender skeleton below to `./pyramid-<slug>.md` (apex = your hypothesis, pillars = titles, every base entry marked `[?]` pending). Then open it live so the user watches it build:","   ```bash","   termrender pane open ./pyramid-<slug>.md --watch   # detached tmux side-pane; re-renders on every save","   ```","   Not in tmux? Tell the user to run `termrender doc watch ./pyramid-<slug>.md` in another terminal, then continue regardless.","","3. **Investigate in parallel \u2014 do not block.** Fan out ONE explore agent per pillar/unknown AND dig into what you can answer yourself, concurrently:","   ```bash",'   crtr node new "Investigate: <focused question for this pillar>. Report findings with sources / file:line refs." --kind explore',"   ```","   You auto-subscribe; each finish wakes you. Never poll or wait \u2014 kick them all off, then start filling in what you already know.","","4. **Live-update as findings land.** Every time you learn something \u2014 your own digging or an explore report \u2014 EDIT the diagram file: flip a `[?]` to `[x]` (or `[!]` for a caveat/risk), add evidence under the right pillar, sharpen or rewrite the apex, drop a pillar that did not hold. Each save re-renders the pane. The diagram visibly grows skeleton \u2192 complete.","","5. **Land it.** When the apex is one crisp sentence, the pillars are MECE, and the base is concrete, do a final pass for accuracy, then give the user a 3\u20134 sentence spoken summary that mirrors apex \u2192 pillars. Tell them the diagram file path.","","## termrender skeleton (write this verbatim, then keep editing it)","","Apex panel on top, a divider, then the pillars as a row of boxes below \u2014 a literal pyramid: 1 claim over N supports.","```markdown",':::panel{title="<TOPIC>" color="cyan"}',"**<one-line apex answer \u2014 your governing claim>**",":::","",':::divider{label="why"}',":::","","::::::columns",':::::col{width="33%"}','::::panel{title="Pillar 1 \u2014 <claim>" color="green"}',":::tree","evidence A [x]","evidence B [?]",":::","::::",":::::",':::::col{width="33%"}','::::panel{title="Pillar 2 \u2014 <claim>" color="green"}',":::tree","evidence C [?]",":::","::::",":::::",':::::col{width="34%"}','::::panel{title="Pillar 3 \u2014 <claim>" color="green"}',":::tree","evidence D [?]",":::","::::",":::::","::::::","```","","**Nesting rule (termrender will reject the file otherwise): an OUTER directive needs strictly MORE colons than the directive nested inside it.** Hence `::::::columns` (6) wraps `:::::col` (5) wraps `::::panel` (4) wraps `:::tree` (3). Every block closes with a bare run of its OWN colon count on its own line. Run `termrender doc check ./pyramid-<slug>.md` after each edit \u2014 if it errors, fix the colon counts before re-saving.","","Markers inside a tree: `[x]` \u2192 \u2714 confirmed, `[!]` \u2192 \u26A0 caveat/risk; `[?]` is not a marker and stays literal \u2014 use it for still-pending. Write structure only \u2014 termrender draws every box, border, and guide line; never hand-draw ASCII. Keep the apex to one sentence; push all detail into the base."].join(`
+`)};export{e as pyramidSlash};

package/dist/commands/node/subscription.d.ts

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

package/dist/commands/node/subscription.js

@@ -0,0 +1 @@
+var b=Object.defineProperty;var r=(e,s)=>b(e,"name",{value:s,configurable:!0});import{envNodeId as h}from"../../shared/env.js";import{defineBranch as p,defineLeaf as n}from"../../core/command.js";import{InputError as o}from"../../core/io.js";import{cliClient as a,rethrowAsCliError as u}from"../api-client.js";function c(e){const s=e.subscriber??h();if(s===void 0||s==="")throw new o({error:"no_subscriber",message:"no subscriber (set CRTR_NODE_ID or pass --subscriber)",field:"subscriber",next:"Run from inside a node, or pass --subscriber <id>."});return s}r(c,"resolveSubscriber");const l=n({name:"add",description:"make one node watch another, so it receives that node's pushes (active or --passive)",whenToUse:"you want to make one node receive another node\u2019s pushes, actively or passively. Managed-child creation already adds its active edge; use this for other subscriber-to-publisher pairs",help:{name:"node subscription add",summary:"make one node watch another so it receives that node's pushes \u2014 the subscriber can be you (default) or, with --subscriber, ANY node, to ANY publisher. Re-running flips an existing subscription's active/passive mode.",params:[{kind:"positional",name:"publisher",required:!0,constraint:"The node to subscribe TO \u2014 whose pushes get delivered to the subscriber."},{kind:"flag",name:"subscriber",type:"string",required:!1,constraint:"Who receives the pushes. Defaults to the calling node (CRTR_NODE_ID). Pass any node id to wire a third party."},{kind:"flag",name:"passive",type:"bool",required:!1,constraint:"Passive subscription: pushes ACCUMULATE without waking the subscriber, then auto-inject as timestamped XML pre-text on its next message. Omit for an active (wake-on-push) subscription."}],output:[],outputKind:"object",effects:["Records an ask watch from the subscriber on the publisher in canvas.db; --passive sets its listening configuration to deliver on the next turn only.","Passive subscriptions never wake the subscriber and do not hold it alive (excluded from the stop-guard)."]},run:r(async e=>{const s=e.publisher,i=c(e),t=e.passive===!0;if(i===s)throw new o({error:"self_subscribe",message:"a node cannot subscribe to itself",next:"Pick a different publisher."});return await a().subscribe(i,{target:s,active:!t}).catch(d=>u(d)),{}},"run"),render:r(()=>"Subscription added.","render")}),m=n({name:"remove",description:"stop one node watching another for pushes",whenToUse:"you want to stop one node receiving a publisher\u2019s pushes; removal is idempotent",help:{name:"node subscription remove",summary:"drop a subscription (a node watch) \u2014 the subscriber (you by default, or any node via --subscriber) stops receiving the publisher's pushes.",params:[{kind:"positional",name:"publisher",required:!0,constraint:"The node to stop subscribing to."},{kind:"flag",name:"subscriber",type:"string",required:!1,constraint:"Who to detach. Defaults to the calling node (CRTR_NODE_ID)."}],output:[],outputKind:"object",effects:["Removes the subscriber's subscription watch on the publisher from canvas.db; a watch from reading or messaging the same node survives."]},run:r(async e=>{const s=e.publisher,i=c(e);return await a().unsubscribe(i,s).catch(t=>u(t)),{}},"run"),render:r(()=>"Subscription removed.","render")}),k=p({name:"subscription",description:"manage push-delivery edges between nodes",whenToUse:"you need an ongoing active or passive subscriber-to-publisher delivery edge that spawn did not create, or need to remove one",help:{name:"node subscription",summary:"add or remove subscriber-to-publisher push-delivery edges",model:"Subscriptions point from a subscriber to a publisher and control future push delivery. A subscription is a watch the subscriber holds on the publisher (`crtr canvas edges <node> --type watches` lists every watch, including plain reads and messages; the subscribers of a node are the `managers` in `crtr node inspect show <node>`, and the nodes it subscribes to are its `reports`). Active subscriptions wake on each push; passive ones accumulate pushes for the subscriber\u2019s next turn. Removing either kind stops subsequent delivery without changing messages already received."},children:[l,m]});export{k as nodeSubscription};

package/dist/commands/node/wait.d.ts

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

package/dist/commands/node/wait.js

@@ -0,0 +1,7 @@
+var p=Object.defineProperty;var o=(e,n)=>p(e,"name",{value:n,configurable:!0});import{envNodeId as m,envProfileId as g}from"../../shared/env.js";import{defineBranch as y,defineLeaf as u}from"../../core/command.js";import{InputError as i}from"../../core/io.js";import{requireScope as _}from"../../core/errors.js";import{parseWhen as b}from"../../core/wake.js";import{cliClient as h,getNodeOrNull as x,rethrowAsCliError as f}from"../api-client.js";import{shellQuote as v}from"../surface/node/placement.js";function k(){const e=m();if(e===void 0||e==="")throw new i({error:"no_node",message:"no node to anchor a deadline cron (CRTR_NODE_ID unset)",next:"Run from inside a node."});return e}o(k,"armerId");function I(e,n){return n!==void 0&&n.trim()!==""?{tz:n,now:e}:{now:e}}o(I,"parseOpts");function T(e){const n={wake_in_past:'Pick a future instant \u2014 a positive duration ("5m","2h") or an ISO time later than now.',bad_when:'Use a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00").',bad_cadence:'Use a duration ("6h"), a 5-field cron ("0 9 * * *"), or an @alias ("@daily").',unknown_zone:'Pass --tz with an IANA zone name (e.g. "America/New_York").',cadence_too_fast:'Use a cadence of at least 60s (e.g. "1m","5m","1h").'};throw new i({error:e.code,message:e.message,received:e.received,next:n[e.code]??"Fix the time value and retry."})}o(T,"throwTimeError");function $(e,n){const t=new Date(e).getTime()-n.getTime();if(!Number.isFinite(t)||t<=0)return"";const r=Math.round(t/6e4);if(r<60)return` (~${r}m)`;const a=Math.round(t/36e5);return a<48?` (~${a}h)`:` (~${Math.round(t/864e5)}d)`}o($,"etaHint");function D(e,n){let t="CRTR_DEADLINE",r=0;const a=new Set(e.split(`
+`));for(;a.has(t);)t=`CRTR_DEADLINE_${++r}`;return`crtr cron cancel "$CRTR_CRON_ID"
+crtr node message send --to ${v(n)} --tier urgent <<'${t}'
+${e}
+${t}`}o(D,"deadlineHeredoc");const R=u({name:"deadline",description:"race this node\u2019s next wake against one urgent deadline cron",whenToUse:"you are waiting on an event nothing can push for, so a self-scheduled deadline must settle the wait",help:{name:"node wait deadline",summary:"arm one cancel-on-wake deadline cron for this node",params:[{kind:"stdin",name:"body",required:!0,constraint:"Policy delivered urgently to this node if the deadline fires first."},{kind:"flag",name:"until",type:"string",required:!0,constraint:"Future duration, zoned ISO timestamp, or bare ISO timestamp interpreted in --tz or host-local time."},{kind:"flag",name:"tz",type:"string",required:!1,constraint:"IANA timezone for a bare ISO --until value."}],output:[{name:"id",type:"string",required:!0,constraint:"The armed cron id."},{name:"name",type:"string",required:!0,constraint:"The cron label."},{name:"fires_at",type:"string",required:!0,constraint:"Absolute UTC deadline."},{name:"guidance",type:"string",required:!0,constraint:"How to inspect the cron and dorm."}],outputKind:"object",effects:["Arms one anchored cancel-on-wake cron. Any wake of this node cancels it; otherwise it urgently sends the body to this node at the deadline.","Re-arming replaces this node\u2019s pending deadline rather than stacking a second."]},run:o(async e=>{_("crtr:schedule","crtr node wait deadline");const n=k(),t=typeof e.body=="string"?e.body.trim():"";if(t==="")throw new i({error:"empty_body",message:"a deadline body is required",field:"body",next:"Pass the timeout policy on stdin."});const r=typeof e.until=="string"?e.until.trim():"";if(r==="")throw new i({error:"missing_until",message:"--until is required",field:"until",next:"Pass a future duration or timestamp."});const a=typeof e.tz=="string"&&e.tz.trim()!==""?e.tz:void 0,c=new Date,s=b(r,I(c,a));"error"in s&&T(s.error);const l=g(),d=await h().armCron({name:`deadline:${n}`,command:D(t,n),fire_at:s.fireAt,recur:null,tz:a??null,created_by:n,cwd:process.cwd(),profile:l!==void 0&&l!==""?l:null,scope:"profile",on_output:"on-failure",sink:null,tier:"normal",expires_at:null,anchor_node:n,cancel_on_wake:!0,run_timeout_s:300,overlap:"skip"}).catch(f),w=`Deadline cron armed for ${d.fire_at}${$(d.fire_at,c)}. End your turn to dorm; any earlier wake cancels it. Inspect pending schedules with \`crtr cron list\`.`;return{id:d.cron_id,name:d.name,fires_at:d.fire_at,guidance:w}},"run"),render:o(e=>`Deadline cron armed \u2014 ${e.name} (${e.id}), fires ${e.fires_at}.
+
+${e.guidance}`,"render")}),N=u({name:"controller",description:"wait durably for a named controller message",whenToUse:"you are a terminal node blocked on one specific live parent or controller and have no managed-child subscription whose report will wake you",help:{name:"node wait controller",summary:"declare that your next stop may dorm only until one live controller delivers an inbox message",params:[{kind:"positional",name:"controller",type:"string",required:!0,constraint:"Live node id expected to send the message. It may be your parent or another named controller, but cannot be yourself."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The terminal node that declared the wait."}],outputKind:"object",effects:["Durably records the controller on this node. The stop guard permits dormancy only while that controller remains active or idle; its next inbox delivery clears the record before the delivery wakes this node."]},run:o(async e=>{const n=m();if(n===void 0||n==="")throw new i({error:"no_node",message:"no node to wait (CRTR_NODE_ID unset)",next:"Run from inside the terminal node that is blocked."});const t=await x(n);if(t===null)throw new i({error:"not_found",message:`no node: ${n}`,next:"Run from a live canvas node."});if(t.lifecycle!=="terminal")throw new i({error:"resident_node",message:`node ${n} is resident and may already dorm on its inbox`,next:"Use this only from a terminal node that needs the stop guard to recognize a controller dependency."});const r=String(e.controller).trim();if(r===n)throw new i({error:"self_controller",message:"a node cannot wait for its own message",field:"controller",next:"Name the parent or external controller expected to send the message."});return await h().waitNode(n,{controller:r}).catch(a=>f(a)),{node_id:n}},"run"),render:o(()=>"Waiting for the controller. End your turn to dorm; its next message wakes you and clears this wait.","render")}),P=y({name:"wait",description:"declare a durable controller or deadline wait",whenToUse:"a terminal node must dorm for one named controller, or race its inbox against a self-scheduled deadline",help:{name:"node wait",summary:"declare durable wait state; choose the event that settles it",model:"Both waits belong to the calling terminal node and settle on one future event. A controller wait records an existing node as the wake source; a deadline wait arms an urgent one-shot cron that races any earlier inbox delivery and is canceled when that delivery wins."},children:[N,R]});export{P as nodeWaitBranch};

package/dist/commands/node-context.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const nodeContextLeaf: LeafDef;

package/dist/commands/node-context.js

@@ -0,0 +1,2 @@
+var m=Object.defineProperty;var s=(o,t)=>m(o,"name",{value:t,configurable:!0});import{envNodeId as p}from"../shared/env.js";import{spawnSync as f}from"node:child_process";import{existsSync as u,mkdirSync as h,mkdtempSync as v,rmSync as x,symlinkSync as b}from"node:fs";import{tmpdir as y}from"node:os";import{dirname as g,join as d}from"node:path";import{defineLeaf as w}from"../core/command.js";import{InputError as a}from"../core/io.js";import{nvimArgs as T,nvimAvailable as S}from"../core/nvim-launch.js";import{cliClient as $,rethrowAsCliError as R}from"./api-client.js";function l(o){return o.replace(/[^A-Za-z0-9._-]+/g,"-").replace(/^-+|-+$/g,"")||"node"}s(l,"sanitize");async function _(o){const t=await $().getContext(o),n=[];for(const e of t.roots){const r=e.dir,i=e.node_id.slice(0,8),c=e.self?`self-${l(e.label)}`:`${l(e.label)}-${i}`;n.push({nodeId:e.node_id,label:c,dir:g(r),self:e.self,fileCount:e.files,contextDir:r})}return n}s(_,"resolveRoots");function C(o){const t=v(d(y(),"crtr-context-"));for(const n of o){const e=n.self?`0-${n.label}`:n.label,r=d(t,e);h(r,{recursive:!0});try{u(n.contextDir)&&b(n.contextDir,d(r,"context"),"dir")}catch{}}return t}s(C,"buildSymlinkTree");const P=w({name:"context",description:"browse this node + its subscriptions\u2019 context dirs in an nvim popup",whenToUse:"you want to SEE what the nodes you subscribe to have written \u2014 open a read-only nvim file explorer over this node\u2019s context dir and every subscribed node\u2019s context dir at once (reports are documents: `crtr canvas read <node>/reports/<name>`). The /context popup shells this. Piped it prints the roster instead",help:{name:"node inspect context",summary:"open a read-only nvim file explorer over this node\u2019s context dir and those of every node it subscribes to",params:[{kind:"flag",name:"node",type:"string",required:!1,constraint:"Node id to root on. Defaults to $CRTR_NODE_ID (the calling node)."}],output:[{name:"roots",type:"object[]",required:!0,constraint:"Resolved browse roots: {node_id, label, dir, self, files}. Returned on the piped/non-TTY path."}],outputKind:"object",effects:["TTY: builds a temp dir of labelled node dirs, symlinking each available `context` dir inside it, then execs `nvim -R` on the tree; the temp links are removed on exit (real dirs untouched).","Requires nvim on PATH (a crtr strong dependency). Missing nvim -> error with an install hint.","Non-TTY / piped: prints the resolved roster and exits 0; opens nothing."]},run:s(async o=>{const t=o.node?.trim()||p();if(t===void 0||t==="")throw new a({error:"no_node",message:"no current node: $CRTR_NODE_ID is unset and --node was not given",field:"node",next:"Run this from inside a canvas node (the /context popup does), or pass --node <id>."});let n;try{n=await _(t)}catch(i){R(i)}const e=n.map(i=>({node_id:i.nodeId,label:i.label,dir:i.dir,self:i.self,files:i.fileCount}));if(!process.stdout.isTTY)return{roots:e};if(!S())throw new a({error:"nvim_missing",message:"nvim is not on PATH \u2014 `crtr node inspect context` opens the context explorer in nvim",next:"Install Neovim (macOS: `brew install neovim`; Debian/Ubuntu: `apt install neovim`), then retry."});const r=C(n);try{f("nvim",[...T("readonly"),"."],{cwd:r,stdio:"inherit"})}finally{x(r,{recursive:!0,force:!0})}return{roots:e}},"run"),render:s(o=>{const t=o.roots??[];if(t.length===0)return"No node dirs to show (no subscriptions with written context or reports, and this node\u2019s own context dir is empty/absent).";const n=t.map(e=>{const r=e.self===!0?" (self)":"";return`  ${String(e.label)}${r}	${String(e.files)} files	${String(e.dir)}`});return[`Context roots (${t.length}):`,...n].join(`
+`)},"render")});export{P as nodeContextLeaf};

package/dist/commands/node-lifecycle-revive.d.ts

@@ -0,0 +1,12 @@
+import type { LeafDef } from '../core/command.js';
+import type { NodeFaultDTO } from '../api/dto/nodes.js';
+/** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
+ *  (kick it early instead of waiting out the schedule), or any fault the
+ *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
+ *  disposition that otherwise has NO sanctioned recovery verb.
+ *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
+ *  (redialing) already in flight, and refuses any OTHER link — notably a
+ *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
+ *  the runaway subprocess; see `wedged-child-on-runaway-bash`). */
+export declare function isNowEligibleFault(fault: NodeFaultDTO | null): boolean;
+export declare const nodeReviveLeaf: LeafDef;

package/dist/commands/node-lifecycle-revive.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var s=(e,r)=>w(e,"name",{value:r,configurable:!0});import{defineLeaf as g}from"../core/command.js";import{InputError as a}from"../core/io.js";import{requireScope as p}from"../core/errors.js";import{cliClient as y,rethrowAsCliError as u}from"./api-client.js";import{recordedPidLiveness as k}from"../core/canvas/pid.js";import{fullName as b}from"../core/canvas/labels.js";import{faultNeedsYou as x}from"../core/canvas/status-glyph.js";import{waitForViewSocketReady as R}from"../core/runtime/view-socket.js";function E(e){return e===null||e.link!=="pi\u2192provider"?!1:x(e)?!0:e.retry.by==="daemon"}s(E,"isNowEligibleFault");const C=g({name:"revive",description:"reopen a window for a done/idle/dead/canceled node",whenToUse:"you want to bring a dormant node back yourself \u2014 reopen a window for one that is done, idle, dead, or canceled: resume a node you closed with `node lifecycle close`, reopen a finished worker for a follow-up, or restart a crashed one now instead of waiting. It resumes the saved conversation by default, or can restart the node clean. You rarely need this for crashes \u2014 the daemon auto-revives those; reach for it to bring a node back on demand, to revive a canceled node the daemon will never touch on its own, or to kick a hanging one early (--now). To mass-reconnect EVERY disconnected node at once (after a reboot, a killed login/tmux session, or the daemon being down a while), use `canvas revive --all` instead",help:{name:"node lifecycle revive",summary:"relaunch a node's broker engine (resuming its saved conversation), or kick a hanging one (--now)",params:[{kind:"positional",name:"node",required:!0,constraint:"Node id to revive."},{kind:"flag",name:"fresh",type:"bool",required:!1,default:!1,constraint:"When set, do NOT do a true resume. If the node already has a session `.jsonl`, this instead CYCLES it in place \u2014 reuses that SAME file, resets the tree leaf, and roots a fresh `crtr-cycle` branch (a clean-context restart that still carries the file's history, output `resumed:false`). Only when no `.jsonl` exists yet does this start a genuinely brand-new session (also `resumed:false`). Default (no --fresh): a true resume \u2014 replays the existing `.jsonl` as-is (`resumed:true`)."},{kind:"flag",name:"now",type:"bool",required:!1,default:!1,constraint:'On-demand kick of an active-fault node (parked on a `pi\u2192provider` fault, broker still alive). Its broker pid is alive, so an ordinary revive no-ops (double-launch guard) \u2014 --now SIGTERMs the live broker instead, so the daemon\'s crash\u2192grace\u2192resume path brings it back in ~20s. Valid for a live `pi\u2192provider` fault that is either a daemon-owned auto retry (kicks it early), or ANY fault the canvas dashboard flags "needs you" (e.g. exhausted retries, an auth fault you just fixed) \u2014 that disposition otherwise has no recovery verb. Mutually exclusive with --fresh.'},{kind:"flag",name:"reopen",type:"bool",required:!1,default:!1,constraint:"Clear a latched node's finalization latch (final_report/finalized_at only \u2014 the old report file and every delivered feed event are untouched) before reviving it. Rejected against a node that is not finalized. Mutually exclusive with --now."}],output:[{name:"resumed",type:"boolean",required:!1,constraint:"True ONLY for a true resume (the existing `.jsonl` replayed as-is). False for a --fresh revive, whether that landed as an in-place CYCLE (an existing `.jsonl` reused with a fresh `crtr-cycle` branch \u2014 pi is still told --session, but this is not a resume) or a genuinely fresh launch (no `.jsonl` existed). Absent for a --now kick."},{name:"ready",type:"boolean",required:!1,constraint:"True when the revived broker's view.sock accepted a connection before return \u2014 the node is immediately attachable/drivable. Absent for a --now kick."},{name:"kicked",type:"boolean",required:!1,constraint:"True when --now SIGTERM'd the hanging node's live broker (the daemon resumes it on the saved session within ~20s). Absent for an ordinary revive."},{name:"message",type:"string",required:!1,constraint:"Kick confirmation naming the signalled node, pid, and the daemon's ~20s resume handoff. Present only for --now."}],outputKind:"object",effects:["Launches the node's detached headless broker engine (no tmux window).","Updates the node's canvas record: status=active, intent=null.","Blocks until the broker's view.sock accepts a connection (up to ~30s), so a caller can attach/dial immediately on return.","--now: SIGTERMs the live broker instead of launching anything (the daemon's own crash-grace path resumes it)."]},run:s(async e=>{p("crtr:act","crtr node lifecycle revive");const r=e.now??!1,n=e.node,l=e.fresh??!1,d=e.reopen??!1;if(r&&d)throw new a({error:"conflicting_args",message:"`--now` kicks a LIVE broker (nothing to reopen \u2014 a finalized node has no live broker); `--reopen` is meaningless there.",next:"Run `crtr node lifecycle revive <node> --now` on a hanging node, or `crtr node lifecycle revive <node> --reopen` (no --now) to re-task a finalized one."});if(r&&l)throw new a({error:"conflicting_args",message:"`--now` kicks a live hanging broker (SIGTERM \u2192 daemon resumes the SAVED session); `--fresh` is meaningless there.",next:"Run `crtr node lifecycle revive <node> --now` (resumes), or `crtr node lifecycle revive <node> --fresh` (no --now) to relaunch clean."});const c=y();if(r){let o;try{o=await c.getNode(n)}catch(v){u(v)}const t=o.pi_pid,m=o.fault??null;if(t==null||k(t,o.pi_pid_identity??null)!=="alive")throw new a({error:"not_hanging",message:`${n} has no live broker \u2014 nothing to kick. --now is for a HANGING node (live broker parked on an active fault).`,next:"Revive a dormant node with `crtr node lifecycle revive "+n+"` (no --now)."});if(!E(m))throw new a({error:"not_hanging",message:`${n} is live but has no pi\u2192provider fault eligible for --now (either healthy, or a client-owned retry / non-provider fault already being handled elsewhere) \u2014 --now refuses to SIGTERM a node that isn't stuck on a kickable provider fault.`,next:"Use --now only on a node the canvas shows as hanging (\u26A0) with a `pi\u2192provider` fault. For a routine relaunch, omit --now."});if(o.streaming===!0)throw new a({error:"busy",message:`${n} is mid-turn right now (busy) \u2014 --now refuses to SIGTERM a working engine; it has recovered on its own.`,next:"Re-check the canvas \u2014 if it's no longer marked hanging (\u26A0), nothing to do."});try{process.kill(t,"SIGTERM")}catch{}return{kicked:!0,message:`Sent SIGTERM to ${b(o)} (${n}, pid ${t}). The daemon will resume it on the saved session within ~20s (crash\u2192grace\u2192resume).`}}const i=process.env.CRTR_CRON_ID;let h;try{h=await c.reviveNode(n,{resume:!l,reopen:d,...i!==void 0&&i!==""?{cron_id:i}:{}})}catch(o){u(o)}const f=await R(n);return{resumed:h.resumed,ready:f}},"run")});export{E as isNowEligibleFault,C as nodeReviveLeaf};

package/dist/commands/node-snapshot.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const nodeSnapshotLeaf: LeafDef;

package/dist/commands/node-snapshot.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var n=(t,s)=>o(t,"name",{value:s,configurable:!0});import{defineLeaf as r}from"../core/command.js";import{cliClient as a,rethrowAsCliError as i}from"./api-client.js";const m=r({name:"snapshot",description:"read a dormant node session snapshot without launching its broker",whenToUse:"you need a read-only broker-compatible snapshot of a dormant node; it copies the session JSONL before parsing and never revives the node",tier:"hidden",help:{name:"node inspect snapshot",summary:"read-only dormant node snapshot in the broker welcome shape",params:[{kind:"positional",name:"id",type:"string",required:!0,constraint:"Canvas node id."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The node id."},{name:"snapshot",type:"object",required:!0,constraint:"BrokerSnapshot-compatible {messages, stats, state, display}; `display` is always empty here \u2014 extension display state is live broker process state, not persisted."},{name:"commands",type:"object[]",required:!0,constraint:"Builtin slash commands only: {name,description,source:'builtin'}."}],outputKind:"object",effects:["Read-only: crtrd copies the session JSONL to a temp dir, parses the copy, then deletes the temp dir. Does not launch or revive brokers."],preview:{suppressOutput:!0}},run:n(async t=>{const s=t.id;try{const e=await a().getSnapshot(s);return{node_id:e.node_id,snapshot:e.snapshot,commands:e.commands}}catch(e){i(e)}},"run")});export{m as nodeSnapshotLeaf};

package/dist/commands/node-transcript.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const nodeTranscriptLeaf: LeafDef;

package/dist/commands/node-transcript.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var e=(r,t)=>c(r,"name",{value:t,configurable:!0});import{spawnSync as p}from"node:child_process";import{mkdtempSync as d,rmSync as m,writeFileSync as v}from"node:fs";import{tmpdir as u}from"node:os";import{join as s}from"node:path";import{defineLeaf as f}from"../core/command.js";import{InputError as l}from"../core/io.js";import{nvimArgs as h,nvimAvailable as y}from"../core/nvim-launch.js";import{cliClient as T,rethrowAsCliError as g}from"./api-client.js";const j=f({name:"transcript",description:"read a node\u2019s saved conversation without reviving it",whenToUse:"you have a node id and need to inspect its past conversation without changing its lifecycle or launching an agent",help:{name:"node inspect transcript",summary:"open a node\u2019s saved conversation read-only in nvim; never launches or revives its broker",params:[{kind:"positional",name:"node-id",required:!0,constraint:"The node whose saved conversation to inspect."}],output:[{name:"transcript",type:"string",required:!0,constraint:"Markdown transcript on the non-TTY path."}],outputKind:"object",effects:["TTY: opens a temporary read-only nvim buffer and deletes it after exit. Non-TTY: prints the transcript. Never changes node status or starts a broker."]},run:e(async r=>{const t=r.nodeId;let n;try{n=(await T().getTranscript(t)).markdown}catch(a){g(a)}if(!process.stdout.isTTY)return{transcript:n};if(!y())throw new l({error:"nvim_missing",message:"nvim is not on PATH \u2014 `crtr node inspect transcript` opens saved conversations in nvim",next:"Install Neovim, then retry."});const i=d(s(u(),"crtr-transcript-")),o=s(i,"transcript.md");try{v(o,n),p("nvim",[...h("readonly"),o],{stdio:"inherit"})}finally{m(i,{recursive:!0,force:!0})}return{transcript:n}},"run"),render:e(r=>String(r.transcript),"render")});export{j as nodeTranscriptLeaf};

package/dist/commands/node-worktree.d.ts

@@ -0,0 +1,2 @@
+import { type BranchDef } from '../core/command.js';
+export declare const nodeWorktreeBranch: BranchDef;

package/dist/commands/node-worktree.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var r=(e,t)=>u(e,"name",{value:t,configurable:!0});import{envNodeId as s}from"../shared/env.js";import{defineBranch as m,defineLeaf as d}from"../core/command.js";import{InputError as c}from"../core/io.js";import{ApiError as p}from"../api/index.js";import{cliClient as h}from"./api-client.js";function w(){const e=s();if(e===void 0||e.trim()==="")throw new c({error:"no_node_context",message:"CRTR_NODE_ID is not set \u2014 worktree commands run inside a canvas node.",next:"Run this command from a node process spawned by the runtime."});return e.trim()}r(w,"requireCallerNode");function l(e){if(e instanceof p){const t=e.details??{};throw new c({error:e.code,message:e.message,...typeof t.received=="string"?{received:t.received}:{},next:typeof t.next=="string"?t.next:"Inspect the error and adjust the call. See -h for the schema."})}throw e}r(l,"mapWorktreeApiError");const b=d({name:"abandon",description:"remove a node worktree and preserve any branch work",whenToUse:"a canceled, dead, or otherwise finished node holds work you will not land now: remove its checkout without reviving it, retain its branch work, and release its worktree ownership so finalization or deletion can continue",help:{name:"node worktree abandon",summary:"remove a node-managed checkout, retain its work, and commit dirty changes first",params:[{kind:"positional",name:"node",required:!0,constraint:"Node id whose open managed worktree to abandon. The node must be stopped, with no live broker process."}],output:[{name:"node_id",type:"string",required:!0,constraint:"The node whose worktree was abandoned."},{name:"branch",type:"string",required:!0,constraint:"The branch that retains abandoned work, or the deleted empty branch."},{name:"tip_sha",type:"string",required:!0,constraint:"The preserved work tip, or the deleted empty branch tip."},{name:"worktree_path",type:"string",required:!0,constraint:"The removed managed checkout path."},{name:"branch_deleted",type:"boolean",required:!0,constraint:"Whether the empty branch was deleted; false means the branch retains work or cleanup needs manual completion."}],outputKind:"object",effects:["Requires a stopped node with no live broker process; a running owner must not abandon its own checkout. Use `node worktree close` to land locally, or `push final` after making the checkout clean and pushing its current tip to origin. Removes the checkout. A clean zero-commit worktree deletes its empty branch. Otherwise commits all worktree state to the branch, retains that branch, records abandoned provenance, and repoints the node cwd to the repository root without changing lifecycle status."]},run:r(async e=>{const t=e.node;try{return{...await h().abandonWorktree(t,{by:s()??"human"})}}catch(a){l(a)}},"run"),render:r(e=>e.branch_deleted===!0?`Managed empty worktree abandoned \u2014 checkout and empty branch ${String(e.branch)} removed.`:`Managed worktree abandoned \u2014 checkout removed; branch ${String(e.branch)} kept at ${String(e.tip_sha)}.`,"render")}),k=d({name:"close",description:"land or safely close the current node-managed worktree",whenToUse:"you are inside the node that owns an open managed worktree and are ready to land its recorded branch into the local base, or to close a moved real branch whose already-delivered content can be safely preserved while its checkout is disposed later",help:{name:"node worktree close",summary:"land or safely close the current node-managed worktree",params:[],output:[{name:"node_id",type:"string",required:!0,constraint:"The caller node id whose managed worktree was closed."},{name:"branch",type:"string",required:!0,constraint:"The branch whose delivered content is retained: fast-forwarded into the recorded local base in an ordinary close, or preserved unchanged when a moved real branch is authorized for disposal."},{name:"landed_sha",type:"string",required:!0,constraint:"The retained branch tip: fast-forwarded into the local base in an ordinary close, or proven already contained in the local base or its upstream before a moved real branch is authorized for disposal."},{name:"worktree_path",type:"string",required:!0,constraint:"The managed worktree path whose cleanup is deferred until its caller exits."},{name:"worktree_removed",type:"boolean",required:!0,constraint:"Always false for an active caller: its checkout remains intact rather than being removed beneath the node."},{name:"worktree_remove_error",type:"string",required:!0,constraint:"The named deferred-cleanup state and safe manual follow-up after the caller exits."},{name:"branch_deleted",type:"boolean",required:!0,constraint:"False while the deferred-cleanup checkout still has this branch checked out."},{name:"branch_delete_error",type:"string",required:!0,constraint:"The safe branch-cleanup follow-up after the checkout is removed."},{name:"base_checkout_stash",type:"string",required:!1,constraint:"Present when conflicting base-checkout changes were retained in a stash; names the exact stash SHA and command required to recover them."}],outputKind:"object",effects:["Rebases the worktree onto its recorded local base branch and fast-forwards that base onto it (never pushes to origin), marking the node-managed worktree closed with cleanup pending and leaving the active caller checkout and branch intact. When the recorded branch is gone because ordinary work moved this checkout onto a real branch, and that branch's content is already contained in the recorded base, closes by authorizing the checkout's later removal instead of landing \u2014 preserving that branch rather than deleting it."]},run:r(async()=>{const e=w();try{return{...await h().closeWorktree(e)}}catch(t){l(t)}},"run"),render:r(e=>{const t=String(e.branch??""),a=String(e.landed_sha??""),i=String(e.worktree_path??"");let o=`Managed worktree closed \u2014 ${t} at ${a} is retained.`;const n=[];return e.worktree_removed===!1?n.push(String(e.worktree_remove_error??`worktree checkout at ${i} could not be removed automatically.`)):o+=` Worktree removed at ${i}.`,e.branch_deleted===!1&&n.push(String(e.branch_delete_error??`local branch ${t} could not be deleted automatically.`)),typeof e.base_checkout_stash=="string"&&n.push(`Warning: ${e.base_checkout_stash}`),n.length>0?`${o} Note: ${n.join(" ")}`:o},"render")}),T=m({name:"worktree",description:"manage a node-owned git worktree \u2014 land it or explicitly abandon it",whenToUse:"you need to dispose of a managed checkout: close lands the current node\u2019s work onto its base; abandon removes any node\u2019s checkout while retaining its work on the branch",help:{name:"node worktree",summary:"manage a node-owned git worktree \u2014 land it, or explicitly abandon its checkout while retaining work",model:"Close merges work into its recorded base. Abandon requires a stopped node and removes its checkout without changing lifecycle state; it retains work on the branch and deletes only a clean zero-commit branch."},children:[k,b]});export{T as nodeWorktreeBranch};

package/dist/commands/node.d.ts

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

package/dist/commands/node.js

@@ -0,0 +1 @@
+var t=Object.defineProperty;var e=(o,n)=>t(o,"name",{value:n,configurable:!0});import{defineBranch as a}from"../core/command.js";import{nodeNew as i}from"./node/create.js";import{nodeInspect as r,nodeFork as s}from"./node/inspect.js";import{nodeLifecycle as d,nodeConfig as c,nodePromote as m,nodeYield as h}from"./node/lifecycle.js";import{nodeMessage as p}from"./node/message.js";import{nodeWaitBranch as f}from"./node/wait.js";import{nodeSubscription as l}from"./node/subscription.js";import{nodeBash as g}from"./node/bash.js";import{pyramidSlash as u}from"./node/pyramid.js";import{nodeWorktreeBranch as w}from"./node-worktree.js";import{nodeOutcome as y}from"./node/outcome.js";function C(){return a({name:"node",slash:u,rootEntry:{concept:"a unit of the agent runtime \u2014 an agent on the canvas with its own context dir and pi vehicle. Spawning nodes is how work gets done here, not an optimization you reach for late",desc:"spawn, inspect, and navigate nodes on the canvas",useWhen:"delegating a genuinely independent subtask, or walking the subscription graph. Base nodes work hands-on; orchestrators fan out. Give each child a bounded outcome distinct from your whole assignment so delegation moves work toward completion instead of recursively passing it down. Once delegated, do not duplicate the child\u2019s work; its finish wakes you. Use the help surface for the exact node contract before invoking it."},help:{name:"node",summary:"create, inspect, message, and change canvas nodes",model:"A node is one agent on the canvas. Immediate actions, durable waits, subscriptions, lifecycle changes, and scheduled crons are separate intent families; choose the family by when the effect happens and what persistent state it changes."},children:[i,s,p,f,l,y,r,d,w,c,m,h,g]})}e(C,"registerNode");export{C as registerNode};

package/dist/commands/pkg/browse/actions.d.ts

@@ -0,0 +1,7 @@
+import type { ActionPresentation, ActionRequest, ActionOutcome } from './model.js';
+/** How an action reads before it runs — and whether it needs confirming. */
+export declare function presentAction(request: ActionRequest): ActionPresentation;
+/** Actions available for a request's subject right now, in offer order. */
+export declare function availableActions(request: Pick<ActionRequest, "entry" | "marketplace" | "scope">): ActionRequest[];
+/** Run one action. Never throws: a failure comes back as `ok: false`. */
+export declare function runAction(request: ActionRequest): Promise<ActionOutcome>;

package/dist/commands/pkg/browse/actions.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var o=(e,n)=>g(e,"name",{value:n,configurable:!0});import{marketAdd as y,marketRemove as $,marketUpdate as b}from"../market-manage.js";import{pluginDisable as h,pluginEnable as v,pluginInstall as A,pluginRemove as R,pluginUpdate as C}from"../plugin-manage.js";import{listAllMarketplaces as w}from"../../../core/resolver.js";import{projectScopeRoot as U}from"../../../core/scope.js";function s(e){return e.entry?.name??"plugin"}o(s,"pluginName");function p(e){return e.marketplace??"marketplace"}o(p,"marketplaceName");function N(e){switch(e.kind){case"install":return{label:`Install into ${e.scope??"user"} scope`,progress:`Installing ${s(e)}\u2026`};case"remove":return{label:`Remove ${s(e)}`,progress:`Removing ${s(e)}\u2026`,confirm:`Remove ${s(e)} and delete its files?`};case"enable":return{label:`Enable ${s(e)}`,progress:`Enabling ${s(e)}\u2026`};case"disable":return{label:`Disable ${s(e)}`,progress:`Disabling ${s(e)}\u2026`};case"update":return{label:`Update ${s(e)}`,progress:`Updating ${s(e)}\u2026`};case"market-add":return{label:"Add marketplace",progress:`Adding ${e.url??"marketplace"}\u2026`};case"market-update":return{label:`Update ${p(e)}`,progress:`Updating ${p(e)}\u2026`};case"market-remove":return{label:`Remove ${p(e)}`,progress:`Removing ${p(e)}\u2026`,confirm:`Remove ${p(e)} and its sourced plugins?`}}return{label:"Run action",progress:"Running action\u2026"}}o(N,"presentAction");function L(e){if(e.entry!==void 0){const{entry:n}=e;if(n.install.kind==="absent")return[{kind:"install",entry:n,scope:"user"},...U()===null?[]:[{kind:"install",entry:n,scope:"project"}]];const a=[{kind:n.install.enabled?"disable":"enable",entry:n}];return n.install.scope!=="builtin"&&a.push({kind:"remove",entry:n}),n.install.updateAvailable&&a.push({kind:"update",entry:n}),a}if(e.marketplace!==void 0){const n=m(e.marketplace),a=n.length===1?n[0].scope:e.scope;return[...a===void 0?[]:[{kind:"market-update",marketplace:e.marketplace,scope:a}],...a===void 0?[]:[{kind:"market-remove",marketplace:e.marketplace,scope:a}]]}return[]}o(L,"availableActions");function m(e){try{return w().filter(n=>n.name===e)}catch{return[]}}o(m,"marketplacesNamed");function i(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)?e:{}}o(i,"asRecord");function f(e){return Array.isArray(e)?e.filter(n=>typeof n=="string"):[]}o(f,"strings");function u(e){const n=i(e),a=f(n.mounts),l=Array.isArray(n.issues)?n.issues:[];return[...a.map(t=>`Mounted: crtr ${t}`),...l.map(t=>{const c=i(t).message;return`Command issue: ${typeof c=="string"?c:"invalid command manifest"}`})]}o(u,"commandDetail");function k(e,n){return(Array.isArray(i(e).updated)?i(e).updated:[]).flatMap(l=>{const t=i(l),d=typeof t.name=="string"?t.name:n.toLowerCase(),c=typeof t.sha=="string"&&t.sha!==""?` at ${t.sha.slice(0,12)}`:"";return[t.updated===!0?`${n} ${d} updated${c}.`:`${n} ${d} is already current${c}.`,...u(t.commands),...typeof t.error=="string"?[`${n} ${d}: ${t.error}`]:[]]})}o(k,"updateDetail");function r(e){return{ok:!1,message:e}}o(r,"missing");async function S(e){try{switch(e.kind){case"install":{if(e.entry===void 0)return r("Choose a plugin to install.");if(e.scope===void 0)return r("Choose an install scope.");if(e.entry.marketplace!==void 0&&m(e.entry.marketplace).length>1)return r(`Cannot safely install ${e.entry.name}: marketplace "${e.entry.marketplace}" exists in more than one scope.`);const n=await A.run({installRef:e.entry.ref,scope:e.scope}),a=i(n),l=typeof a.name=="string"?a.name:e.entry.name,t=typeof a.scope=="string"?a.scope:e.scope;return{ok:!0,message:`Installed ${l} in ${t} scope.`,detail:u(a.commands)}}case"remove":{if(e.entry===void 0||e.entry.install.kind!=="installed")return r("Choose an installed plugin to remove.");const n=i(await R.run({name:e.entry.name,scope:e.entry.install.scope})),a=f(n.scopes);return{ok:!0,message:`Removed ${e.entry.name}${a.length>0?` from ${a.join(", ")} scope${a.length===1?"":"s"}`:""}.`}}case"enable":{if(e.entry===void 0||e.entry.install.kind!=="installed")return r("Choose an installed plugin to enable.");const n=i(await v.run({name:e.entry.name,scope:e.entry.install.scope})),a=typeof n.scope=="string"?n.scope:e.entry.install.scope;return{ok:!0,message:`Enabled ${e.entry.name} in ${a} scope.`}}case"disable":{if(e.entry===void 0||e.entry.install.kind!=="installed")return r("Choose an installed plugin to disable.");const n=i(await h.run({name:e.entry.name,scope:e.entry.install.scope})),a=typeof n.scope=="string"?n.scope:e.entry.install.scope;return{ok:!0,message:`Disabled ${e.entry.name} in ${a} scope.`}}case"update":{if(e.entry===void 0||e.entry.install.kind!=="installed")return r("Choose an installed plugin to update.");const n=await C.run({name:e.entry.name,scope:e.entry.install.scope}),a=k(n,"Plugin");return{ok:!0,message:a[0]??`Updated ${e.entry.name}.`,detail:a}}case"market-add":{if(e.url===void 0||e.url==="")return r("Enter a marketplace git URL.");const n=i(await y.run({url:e.url,...e.ref!==void 0?{ref:e.ref}:{},...e.scope!==void 0?{scope:e.scope}:{}})),a=typeof n.name=="string"?n.name:e.url,l=typeof n.scope=="string"?n.scope:e.scope;return{ok:!0,message:`Added marketplace ${a}${l===void 0?"":` in ${l} scope`}.`}}case"market-update":{if(e.marketplace===void 0)return r("Choose a marketplace to update.");if(e.scope===void 0)return r("Choose a marketplace scope to update.");const n=await b.run({name:e.marketplace,scope:e.scope}),a=k(n,"Marketplace");return{ok:!0,message:a[0]??`Updated ${e.marketplace}.`,detail:a}}case"market-remove":return e.marketplace===void 0?r("Choose a marketplace to remove."):e.scope===void 0?r("Choose a marketplace scope to remove."):(await $.run({name:e.marketplace,scope:e.scope}),{ok:!0,message:`Removed marketplace ${e.marketplace}.`})}return r("Unsupported action.")}catch(n){return{ok:!1,message:n instanceof Error?n.message:String(n)}}}o(S,"runAction");export{L as availableActions,N as presentAction,S as runAction};