@north-light/crouter 0.3.318 → 0.3.319

package/dist/commands/sys/context.js

@@ -1,20 +1 @@
-// `crtr sys context` — inspect and shape the memory context surface: what a
-// node's configuration actually loads, for which event, at which rung, and why.
-// The leaves are landed elsewhere; this file only assembles them.
-import { defineBranch } from '../../core/command.js';
-import { resolveLeaf } from './context/resolve.js';
-import { docLeaf } from './context/doc.js';
-import { sysSyspromptLeaf } from './context/sysprompt.js';
-import { promptReviewLeaf } from './context/prompt-review.js';
-import { adminLeaf } from './context/admin.js';
-export const contextBranch = defineBranch({
-    name: 'context',
-    description: 'inspect and shape what a node\u2019s memory context surface delivers',
-    whenToUse: 'you are asking what a node loads, why a document does or does not reach it, or you want to change the surfaces and caps that decide it',
-    help: {
-        name: 'sys context',
-        summary: 'inspect and shape the memory context a node\u2019s configuration delivers',
-        model: 'A document reaches a node when one of its authored surface entries fires for an event (boot, workspace-open, read, memory-read, command, pre-command), its gates pass, and it wins its canonical name against nearer stores; the profile relationship caps the rung at boot and workspace-open only. resolve answers that forward — snapshot plus event to the delivered set. doc answers it in reverse — one document across every event. sysprompt and prompt-review read assembled prompts (a live node\u2019s captured one, and a hypothetical configuration\u2019s). admin is the interactive surface over all of it.',
-    },
-    children: [resolveLeaf, docLeaf, sysSyspromptLeaf, promptReviewLeaf, adminLeaf],
-});
+import{defineBranch as e}from"../../core/command.js";import{resolveLeaf as o}from"./context/resolve.js";import{docLeaf as a}from"./context/doc.js";import{sysSyspromptLeaf as t}from"./context/sysprompt.js";import{promptReviewLeaf as r}from"./context/prompt-review.js";import{adminLeaf as n}from"./context/admin.js";const h=e({name:"context",description:"inspect and shape what a node\u2019s memory context surface delivers",whenToUse:"you are asking what a node loads, why a document does or does not reach it, or you want to change the surfaces and caps that decide it",help:{name:"sys context",summary:"inspect and shape the memory context a node\u2019s configuration delivers",model:"A document reaches a node when one of its authored surface entries fires for an event (boot, workspace-open, read, memory-read, command, pre-command), its gates pass, and it wins its canonical name against nearer stores; the profile relationship caps the rung at boot and workspace-open only. resolve answers that forward \u2014 snapshot plus event to the delivered set. doc answers it in reverse \u2014 one document across every event. sysprompt and prompt-review read assembled prompts (a live node\u2019s captured one, and a hypothetical configuration\u2019s). admin is the interactive surface over all of it."},children:[o,a,t,r,n]});export{h as contextBranch};

package/dist/commands/sys/daemon.js

@@ -1,313 +1 @@
-// `crtr sys daemon` — thin supervisor daemon management.
-//
-// The daemon (crtrd) polls active+idle nodes and handles engine-container exit
-// (a tmux pane or a headless broker process):
-//   • crash (container gone, no intent) → mark 'dead'
-//   • refresh-yield (intent=refresh) → fresh respawn
-//
-// This subtree starts, checks, and stops the daemon process.
-import { defineLeaf, defineBranch } from '../../core/command.js';
-import { InputError } from '../../core/io.js';
-import { parseDurationMs } from '../../core/wake.js';
-import { DaemonNotPreparedError, probeDaemonHealth, spawnDaemon, stopDaemonProcess, sweepStrayDaemons } from '../../daemon/manage.js';
-import { isDaemonRunning, readPidfile, isPidAlive } from '../../daemon/pidfile.js';
-import { cliClient } from '../api-client.js';
-import { CrtrClient } from '../../api/index.js';
-import { defineSysBranch } from './branch.js';
-// daemon start
-const daemonStart = defineLeaf({
-    name: 'start',
-    description: 'start the daemon in the background',
-    whenToUse: 'bringing the crtrd supervisor up for the first time in a session so node window-exits get handled (no-op only when its Unix API socket already serves)',
-    help: {
-        name: 'sys daemon start',
-        summary: 'start the crtrd supervisor daemon in the background (no-op only if its Unix API socket serves)',
-        params: [
-            { kind: 'flag', name: 'prepare', type: 'bool', required: false, constraint: 'Hold normal daemon work after storage preparation until `sys daemon admit`; omit for ordinary startup.' },
-        ],
-        output: [
-            { name: 'started', type: 'boolean', required: true, constraint: 'True when a new daemon process was spawned; false when one was already running.' },
-            { name: 'pid', type: 'number', required: false, constraint: 'PID of the newly spawned daemon.' },
-            { name: 'existing_pid', type: 'number', required: false, constraint: 'PID of the already-running daemon (when started=false).' },
-            { name: 'running', type: 'boolean', required: false, constraint: 'True only when a live pidfile owner does not serve its Unix API socket.' },
-            { name: 'serving', type: 'boolean', required: false, constraint: 'False only when a live pidfile owner does not answer /healthz.' },
-            { name: 'probe_error', type: 'string', required: false, constraint: 'The final /healthz probe failure when a live owner missed readiness.' },
-            { name: 'startup_phase', type: 'string', required: false, constraint: 'The observed daemon phase when it was reachable.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Spawns dist/daemon/crtrd-cli.js detached + unref\'d; it outlives this process.',
-            'Writes a pidfile at CRTR_PIDFILE if set, otherwise crtrHome()/crtrd.pid.'
-        ],
-    },
-    run: async (input) => {
-        try {
-            const result = await spawnDaemon({ targetPhase: input.prepare === true ? 'prepared' : 'ready' });
-            return result;
-        }
-        catch (error) {
-            if (error instanceof DaemonNotPreparedError) {
-                throw new InputError({
-                    error: 'daemon_not_prepared',
-                    message: error.message,
-                    next: 'Stop the live daemon, then start a new one with `crtr sys daemon start --prepare` before setup.',
-                });
-            }
-            throw error;
-        }
-    },
-});
-// daemon await / admit
-const DAEMON_AWAIT_POLL_MS = 100;
-async function awaitDaemonPhase(phase, timeoutMs) {
-    const startedAt = Date.now();
-    const deadline = startedAt + timeoutMs;
-    let lastPhase = 'initializing';
-    let lastObservation = 'the daemon socket was not reachable';
-    while (Date.now() < deadline) {
-        try {
-            const health = await probeDaemonHealth(Math.min(1_000, Math.max(1, deadline - Date.now())));
-            lastPhase = health.startup_phase;
-            lastObservation = health.startup_blocked ?? `daemon is ${health.startup_phase}`;
-            if (health.startup_phase === 'blocked') {
-                throw new InputError({
-                    error: 'startup_blocked',
-                    message: health.startup_blocked ?? 'daemon startup is blocked',
-                    received: health.startup_phase,
-                    field: 'phase',
-                    next: 'Repair the reported blocker paths with `crtr sys migrate`, then retry the await.',
-                });
-            }
-            if (health.startup_phase === phase)
-                return { startup_phase: phase, waited_ms: Date.now() - startedAt };
-            if (phase === 'prepared' && health.startup_phase === 'ready') {
-                throw new InputError({
-                    error: 'await_missed_phase',
-                    message: 'daemon is already ready and cannot return to prepared in this process',
-                    received: health.startup_phase,
-                    field: 'phase',
-                    next: 'Start a new daemon with `crtr sys daemon start --prepare` before awaiting prepared.',
-                });
-            }
-        }
-        catch (error) {
-            if (error instanceof InputError)
-                throw error;
-            lastObservation = error instanceof Error ? error.message : String(error);
-        }
-        await new Promise((resolve) => setTimeout(resolve, Math.min(DAEMON_AWAIT_POLL_MS, Math.max(0, deadline - Date.now()))));
-    }
-    throw new InputError({
-        error: 'await_timeout',
-        message: `daemon did not reach ${phase} within ${timeoutMs}ms (last phase: ${lastPhase}; last observation: ${lastObservation})`,
-        received: lastPhase,
-        field: 'phase',
-        next: 'Inspect `crtr sys daemon status` and resolve any reported startup blocker before retrying.',
-    });
-}
-const daemonAwait = defineLeaf({
-    name: 'await',
-    description: 'wait for a daemon startup phase',
-    whenToUse: 'a caller started or was given a daemon that must reach prepared or ready before its next step.',
-    help: {
-        name: 'sys daemon await',
-        summary: 'wait for the running daemon to report one startup phase',
-        params: [
-            { kind: 'flag', name: 'phase', type: 'enum', choices: ['prepared', 'ready'], required: true, constraint: 'The phase that permits the caller’s next step.' },
-            { kind: 'flag', name: 'timeout', type: 'string', required: false, default: '5m', constraint: 'Maximum wait as a positive duration such as 90s, 5m, or 1h30m.' },
-        ],
-        output: [
-            { name: 'startup_phase', type: 'string', required: true, constraint: 'The requested phase.' },
-            { name: 'waited_ms', type: 'number', required: true, constraint: 'Elapsed wall-clock time before the phase was observed.' },
-        ],
-        outputKind: 'object',
-        effects: ['Read-only: polls /healthz until the requested phase is observed or the caller-bounded timeout expires.'],
-    },
-    run: async (input) => {
-        const rawTimeout = input.timeout;
-        const timeoutMs = parseDurationMs(rawTimeout);
-        if (timeoutMs === null || timeoutMs <= 0) {
-            throw new InputError({ error: 'invalid_duration', message: `not a positive duration: ${rawTimeout}`, received: rawTimeout, field: 'timeout', next: 'Use a positive duration such as 90s, 5m, or 1h30m.' });
-        }
-        return awaitDaemonPhase(input.phase, timeoutMs);
-    },
-});
-const daemonAdmit = defineLeaf({
-    name: 'admit',
-    description: 'admit normal work after daemon preparation',
-    whenToUse: 'the caller has completed its setup against a prepared daemon and is ready for normal daemon work to start.',
-    help: {
-        name: 'sys daemon admit',
-        summary: 'ask a prepared daemon to start normal services',
-        params: [],
-        output: [
-            { name: 'admitted', type: 'boolean', required: true, constraint: 'True only when this request began admission.' },
-            { name: 'already_admitted', type: 'boolean', required: true, constraint: 'True when admission had already begun or completed.' },
-            { name: 'startup_phase', type: 'string', required: true, constraint: 'The phase after admission settles.' },
-        ],
-        outputKind: 'object',
-        effects: ['Starts normal daemon services when the daemon is prepared.'],
-    },
-    run: async (_input) => {
-        return await CrtrClient.forLocalSocket({ autostart: false }).admitDaemon();
-    },
-});
-// daemon status
-const daemonStatus = defineLeaf({
-    name: 'status',
-    description: 'check whether the daemon is running',
-    whenToUse: 'operator/dev diagnostic — probing whether the crtrd supervisor process is alive while troubleshooting revive/supervision behavior',
-    help: {
-        name: 'sys daemon status',
-        summary: 'check whether the crtrd supervisor daemon is currently running',
-        params: [],
-        output: [
-            { name: 'running', type: 'boolean', required: true, constraint: 'True when the daemon pidfile owner is alive.' },
-            { name: 'serving', type: 'boolean', required: false, constraint: 'True when the live daemon answers /healthz; false when one probe does not.' },
-            { name: 'pid', type: 'number', required: false, constraint: 'PID of the running daemon.' },
-            { name: 'probe_error', type: 'string', required: false, constraint: 'The failed /healthz observation when the live owner did not answer.' },
-            { name: 'startup_phase', type: 'string', required: false, constraint: 'The observed daemon startup phase when the socket answered.' },
-        ],
-        outputKind: 'object',
-        effects: ['Read-only: reads the pidfile, probes the pid, and requests /healthz without autostart.'],
-    },
-    run: async (_input) => {
-        const pid = readPidfile();
-        const running = pid !== null && isPidAlive(pid);
-        if (!running)
-            return { running: false };
-        try {
-            const health = await probeDaemonHealth();
-            return {
-                running: true,
-                serving: health.ok,
-                pid,
-                ...(health.startup_phase === undefined ? {} : { startup_phase: health.startup_phase }),
-            };
-        }
-        catch (error) {
-            return { running: true, serving: false, pid, probe_error: error.message };
-        }
-    },
-});
-// daemon restart
-const daemonRestart = defineLeaf({
-    name: 'restart',
-    description: 'put the selected runtime generation in service via a daemon-owned handover',
-    whenToUse: 'adopting a newly installed runtime generation — the routine restart. Use this instead of stop+start: the daemon answers before it hands over, so a caller running inside a node (whose broker the handover tears down) still gets a settled result and is resumed automatically.',
-    help: {
-        name: 'sys daemon restart',
-        summary: 'ask the running daemon to replace itself with a successor on the selected runtime generation',
-        params: [],
-        output: [
-            { name: 'restarted', type: 'boolean', required: true, constraint: 'True when a running daemon accepted the handover. False when none was running — one was started instead.' },
-            { name: 'started', type: 'boolean', required: false, constraint: 'True when no daemon was running and this call started one (restarted=false).' },
-            { name: 'pid', type: 'number', required: false, constraint: 'The daemon that accepted the handover, or the one just started.' },
-            { name: 'grace_ms', type: 'number', required: false, constraint: 'How long the daemon waits after answering before teardown begins.' },
-            { name: 'note', type: 'string', required: false, constraint: 'What happens next to the calling node. Read it before acting on an interrupted turn.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'The daemon acknowledges immediately, then after a short grace tears its whole broker fleet down, releases its claim, spawns a successor on the runtime generation currently selected, and exits.',
-            'Each torn-down broker hands its foreground bash commands to the file-backed background job system; they keep running and report completion by urgent inbox message.',
-            'Every node it tore down — including the caller — is resolved by the successor through the ordinary row-driven supervision tick.',
-            'The calling process is killed as part of that teardown, AFTER this result is returned.',
-        ],
-    },
-    run: async (_input) => {
-        if (!isDaemonRunning()) {
-            const spawned = await spawnDaemon();
-            return {
-                restarted: false,
-                started: spawned.started,
-                ...(spawned.pid !== undefined ? { pid: spawned.pid } : {}),
-                ...(spawned.existing_pid !== undefined ? { pid: spawned.existing_pid } : {}),
-                note: 'No daemon was running, so there was nothing to hand over; one was started on the selected runtime generation.',
-            };
-        }
-        try {
-            const ack = await cliClient().restartDaemon();
-            return {
-                restarted: ack.accepted,
-                pid: ack.predecessor_pid,
-                grace_ms: ack.grace_ms,
-                note: 'Handover accepted. If you are running inside a node, your broker is about to be torn down and resumed on the new generation — THIS RESTART ALREADY SUCCEEDED. When your turn resumes with this result in the transcript, do not re-run it.',
-            };
-        }
-        catch (err) {
-            throw new InputError({
-                error: 'daemon_restart_failed',
-                message: `the daemon did not accept a handover: ${err.message}`,
-                next: 'Run `crtr sys daemon status` to inspect the daemon.',
-            });
-        }
-    },
-});
-// daemon stop
-const daemonStop = defineLeaf({
-    name: 'stop',
-    description: 'stop the running daemon',
-    whenToUse: 'shutting the crtrd supervisor down for good, ending auto-revival of nodes on window exit. Not the way to pick up a new runtime generation — `restart` is, because stopping kills every broker of this epoch, including the caller\'s own, so this command cannot report its result to an agent that runs it.',
-    help: {
-        name: 'sys daemon stop',
-        summary: 'stop the crtrd supervisor daemon and confirm it exited',
-        params: [],
-        output: [
-            { name: 'stopped', type: 'boolean', required: true, constraint: 'True when a daemon (recorded or stray) was found and killed. False when none was running.' },
-            { name: 'pid', type: 'number', required: false, constraint: 'The recorded pidfile pid that exited (when one was recorded and alive).' },
-            { name: 'strays_killed', type: 'array', required: false, constraint: 'PIDs of stray crtrd daemons (alive but not in the pidfile) swept alongside the recorded one — the backstop against a daemon that survived a prior stop.' },
-            { name: 'force_killed', type: 'boolean', required: false, constraint: 'True when the recorded daemon ignored SIGTERM and had to be SIGKILLed.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Sends SIGTERM to the recorded pid and waits for it to exit and release its pidfile, escalating to SIGKILL if it does not.',
-            'Then sweeps any OTHER live crtrd daemon process (SIGTERM, escalating to SIGKILL after 2s) so a stray daemon orphaned from the pidfile cannot keep supervising.',
-        ],
-    },
-    run: async (_input) => {
-        const pid = readPidfile();
-        const recorded = pid !== null && isPidAlive(pid);
-        try {
-            let forceKilled = false;
-            if (recorded) {
-                forceKilled = (await stopDaemonProcess(pid)) === 'killed';
-            }
-            // Backstop: kill any daemon NOT covered by the pidfile signal above. When
-            // the recorded daemon exited cleanly it is already gone, so keepPid=null
-            // sweeps every remaining crtrd process; a stray that survived its own
-            // prior stop is exactly what this reaches.
-            const straysKilled = sweepStrayDaemons(null);
-            if (!recorded && straysKilled.length === 0)
-                return { stopped: false };
-            return {
-                stopped: true,
-                ...(recorded ? { pid } : {}),
-                ...(straysKilled.length > 0 ? { strays_killed: straysKilled } : {}),
-                ...(forceKilled ? { force_killed: true } : {}),
-            };
-        }
-        catch (err) {
-            throw new InputError({
-                error: 'daemon_stop_failed',
-                message: `failed to stop daemon${recorded ? ` pid ${pid}` : ''}: ${err.message}`,
-                next: 'Run `crtr sys daemon status` to inspect the daemon before retrying.',
-            });
-        }
-    },
-});
-// Export — mounted under `crtr sys`
-export const daemonBranch = defineBranch({
-    name: 'daemon',
-    description: 'manage the crtrd supervisor process',
-    whenToUse: 'managing the crtrd supervisor that auto-revives nodes on window exit — start it, restart it onto a new runtime generation, check its status, or stop it',
-    help: {
-        name: 'sys daemon',
-        summary: 'manage the crtrd canvas supervisor daemon',
-        model: 'crtrd is a thin background daemon that polls active+idle nodes and acts on window exit: crashed windows become dead; refresh-yield windows get a fresh respawn. It holds no orchestration logic — just process supervision. These are operator/dev self-management, not something a normal agent turn needs to check. Picking up a newly installed runtime generation is `restart` (a handover the daemon performs on itself); `stop` is the terminal one, and it kills the caller along with the rest of the fleet.',
-    },
-    children: [daemonStart, daemonAwait, daemonAdmit, daemonRestart, daemonStatus, daemonStop],
-});
-/** The daemon-only `sys` subtree used before scoped user state is available. */
-export function registerDaemonControlSys() {
-    return defineSysBranch([daemonBranch]);
-}
+var c=Object.defineProperty;var s=(r,e)=>c(r,"name",{value:e,configurable:!0});import{defineLeaf as d,defineBranch as w}from"../../core/command.js";import{InputError as o}from"../../core/io.js";import{parseDurationMs as f}from"../../core/wake.js";import{DaemonNotPreparedError as g,probeDaemonHealth as u,spawnDaemon as h,stopDaemonProcess as y,sweepStrayDaemons as b}from"../../daemon/manage.js";import{isDaemonRunning as v,readPidfile as m,isPidAlive as l}from"../../daemon/pidfile.js";import{cliClient as k}from"../api-client.js";import{CrtrClient as _}from"../../api/index.js";import{defineSysBranch as T}from"./branch.js";const q=d({name:"start",description:"start the daemon in the background",whenToUse:"bringing the crtrd supervisor up for the first time in a session so node window-exits get handled (no-op only when its Unix API socket already serves)",help:{name:"sys daemon start",summary:"start the crtrd supervisor daemon in the background (no-op only if its Unix API socket serves)",params:[{kind:"flag",name:"prepare",type:"bool",required:!1,constraint:"Hold normal daemon work after storage preparation until `sys daemon admit`; omit for ordinary startup."}],output:[{name:"started",type:"boolean",required:!0,constraint:"True when a new daemon process was spawned; false when one was already running."},{name:"pid",type:"number",required:!1,constraint:"PID of the newly spawned daemon."},{name:"existing_pid",type:"number",required:!1,constraint:"PID of the already-running daemon (when started=false)."},{name:"running",type:"boolean",required:!1,constraint:"True only when a live pidfile owner does not serve its Unix API socket."},{name:"serving",type:"boolean",required:!1,constraint:"False only when a live pidfile owner does not answer /healthz."},{name:"probe_error",type:"string",required:!1,constraint:"The final /healthz probe failure when a live owner missed readiness."},{name:"startup_phase",type:"string",required:!1,constraint:"The observed daemon phase when it was reachable."}],outputKind:"object",effects:["Spawns dist/daemon/crtrd-cli.js detached + unref'd; it outlives this process.","Writes a pidfile at CRTR_PIDFILE if set, otherwise crtrHome()/crtrd.pid."]},run:s(async r=>{try{return await h({targetPhase:r.prepare===!0?"prepared":"ready"})}catch(e){throw e instanceof g?new o({error:"daemon_not_prepared",message:e.message,next:"Stop the live daemon, then start a new one with `crtr sys daemon start --prepare` before setup."}):e}},"run")}),x=100;async function D(r,e){const n=Date.now(),a=n+e;let i="initializing",p="the daemon socket was not reachable";for(;Date.now()<a;){try{const t=await u(Math.min(1e3,Math.max(1,a-Date.now())));if(i=t.startup_phase,p=t.startup_blocked??`daemon is ${t.startup_phase}`,t.startup_phase==="blocked")throw new o({error:"startup_blocked",message:t.startup_blocked??"daemon startup is blocked",received:t.startup_phase,field:"phase",next:"Repair the reported blocker paths with `crtr sys migrate`, then retry the await."});if(t.startup_phase===r)return{startup_phase:r,waited_ms:Date.now()-n};if(r==="prepared"&&t.startup_phase==="ready")throw new o({error:"await_missed_phase",message:"daemon is already ready and cannot return to prepared in this process",received:t.startup_phase,field:"phase",next:"Start a new daemon with `crtr sys daemon start --prepare` before awaiting prepared."})}catch(t){if(t instanceof o)throw t;p=t instanceof Error?t.message:String(t)}await new Promise(t=>setTimeout(t,Math.min(x,Math.max(0,a-Date.now()))))}throw new o({error:"await_timeout",message:`daemon did not reach ${r} within ${e}ms (last phase: ${i}; last observation: ${p})`,received:i,field:"phase",next:"Inspect `crtr sys daemon status` and resolve any reported startup blocker before retrying."})}s(D,"awaitDaemonPhase");const I=d({name:"await",description:"wait for a daemon startup phase",whenToUse:"a caller started or was given a daemon that must reach prepared or ready before its next step.",help:{name:"sys daemon await",summary:"wait for the running daemon to report one startup phase",params:[{kind:"flag",name:"phase",type:"enum",choices:["prepared","ready"],required:!0,constraint:"The phase that permits the caller\u2019s next step."},{kind:"flag",name:"timeout",type:"string",required:!1,default:"5m",constraint:"Maximum wait as a positive duration such as 90s, 5m, or 1h30m."}],output:[{name:"startup_phase",type:"string",required:!0,constraint:"The requested phase."},{name:"waited_ms",type:"number",required:!0,constraint:"Elapsed wall-clock time before the phase was observed."}],outputKind:"object",effects:["Read-only: polls /healthz until the requested phase is observed or the caller-bounded timeout expires."]},run:s(async r=>{const e=r.timeout,n=f(e);if(n===null||n<=0)throw new o({error:"invalid_duration",message:`not a positive duration: ${e}`,received:e,field:"timeout",next:"Use a positive duration such as 90s, 5m, or 1h30m."});return D(r.phase,n)},"run")}),S=d({name:"admit",description:"admit normal work after daemon preparation",whenToUse:"the caller has completed its setup against a prepared daemon and is ready for normal daemon work to start.",help:{name:"sys daemon admit",summary:"ask a prepared daemon to start normal services",params:[],output:[{name:"admitted",type:"boolean",required:!0,constraint:"True only when this request began admission."},{name:"already_admitted",type:"boolean",required:!0,constraint:"True when admission had already begun or completed."},{name:"startup_phase",type:"string",required:!0,constraint:"The phase after admission settles."}],outputKind:"object",effects:["Starts normal daemon services when the daemon is prepared."]},run:s(async r=>await _.forLocalSocket({autostart:!1}).admitDaemon(),"run")}),E=d({name:"status",description:"check whether the daemon is running",whenToUse:"operator/dev diagnostic \u2014 probing whether the crtrd supervisor process is alive while troubleshooting revive/supervision behavior",help:{name:"sys daemon status",summary:"check whether the crtrd supervisor daemon is currently running",params:[],output:[{name:"running",type:"boolean",required:!0,constraint:"True when the daemon pidfile owner is alive."},{name:"serving",type:"boolean",required:!1,constraint:"True when the live daemon answers /healthz; false when one probe does not."},{name:"pid",type:"number",required:!1,constraint:"PID of the running daemon."},{name:"probe_error",type:"string",required:!1,constraint:"The failed /healthz observation when the live owner did not answer."},{name:"startup_phase",type:"string",required:!1,constraint:"The observed daemon startup phase when the socket answered."}],outputKind:"object",effects:["Read-only: reads the pidfile, probes the pid, and requests /healthz without autostart."]},run:s(async r=>{const e=m();if(!(e!==null&&l(e)))return{running:!1};try{const a=await u();return{running:!0,serving:a.ok,pid:e,...a.startup_phase===void 0?{}:{startup_phase:a.startup_phase}}}catch(a){return{running:!0,serving:!1,pid:e,probe_error:a.message}}},"run")}),P=d({name:"restart",description:"put the selected runtime generation in service via a daemon-owned handover",whenToUse:"adopting a newly installed runtime generation \u2014 the routine restart. Use this instead of stop+start: the daemon answers before it hands over, so a caller running inside a node (whose broker the handover tears down) still gets a settled result and is resumed automatically.",help:{name:"sys daemon restart",summary:"ask the running daemon to replace itself with a successor on the selected runtime generation",params:[],output:[{name:"restarted",type:"boolean",required:!0,constraint:"True when a running daemon accepted the handover. False when none was running \u2014 one was started instead."},{name:"started",type:"boolean",required:!1,constraint:"True when no daemon was running and this call started one (restarted=false)."},{name:"pid",type:"number",required:!1,constraint:"The daemon that accepted the handover, or the one just started."},{name:"grace_ms",type:"number",required:!1,constraint:"How long the daemon waits after answering before teardown begins."},{name:"note",type:"string",required:!1,constraint:"What happens next to the calling node. Read it before acting on an interrupted turn."}],outputKind:"object",effects:["The daemon acknowledges immediately, then after a short grace tears its whole broker fleet down, releases its claim, spawns a successor on the runtime generation currently selected, and exits.","Each torn-down broker hands its foreground bash commands to the file-backed background job system; they keep running and report completion by urgent inbox message.","Every node it tore down \u2014 including the caller \u2014 is resolved by the successor through the ordinary row-driven supervision tick.","The calling process is killed as part of that teardown, AFTER this result is returned."]},run:s(async r=>{if(!v()){const e=await h();return{restarted:!1,started:e.started,...e.pid!==void 0?{pid:e.pid}:{},...e.existing_pid!==void 0?{pid:e.existing_pid}:{},note:"No daemon was running, so there was nothing to hand over; one was started on the selected runtime generation."}}try{const e=await k().restartDaemon();return{restarted:e.accepted,pid:e.predecessor_pid,grace_ms:e.grace_ms,note:"Handover accepted. If you are running inside a node, your broker is about to be torn down and resumed on the new generation \u2014 THIS RESTART ALREADY SUCCEEDED. When your turn resumes with this result in the transcript, do not re-run it."}}catch(e){throw new o({error:"daemon_restart_failed",message:`the daemon did not accept a handover: ${e.message}`,next:"Run `crtr sys daemon status` to inspect the daemon."})}},"run")}),R=d({name:"stop",description:"stop the running daemon",whenToUse:"shutting the crtrd supervisor down for good, ending auto-revival of nodes on window exit. Not the way to pick up a new runtime generation \u2014 `restart` is, because stopping kills every broker of this epoch, including the caller's own, so this command cannot report its result to an agent that runs it.",help:{name:"sys daemon stop",summary:"stop the crtrd supervisor daemon and confirm it exited",params:[],output:[{name:"stopped",type:"boolean",required:!0,constraint:"True when a daemon (recorded or stray) was found and killed. False when none was running."},{name:"pid",type:"number",required:!1,constraint:"The recorded pidfile pid that exited (when one was recorded and alive)."},{name:"strays_killed",type:"array",required:!1,constraint:"PIDs of stray crtrd daemons (alive but not in the pidfile) swept alongside the recorded one \u2014 the backstop against a daemon that survived a prior stop."},{name:"force_killed",type:"boolean",required:!1,constraint:"True when the recorded daemon ignored SIGTERM and had to be SIGKILLed."}],outputKind:"object",effects:["Sends SIGTERM to the recorded pid and waits for it to exit and release its pidfile, escalating to SIGKILL if it does not.","Then sweeps any OTHER live crtrd daemon process (SIGTERM, escalating to SIGKILL after 2s) so a stray daemon orphaned from the pidfile cannot keep supervising."]},run:s(async r=>{const e=m(),n=e!==null&&l(e);try{let a=!1;n&&(a=await y(e)==="killed");const i=b(null);return!n&&i.length===0?{stopped:!1}:{stopped:!0,...n?{pid:e}:{},...i.length>0?{strays_killed:i}:{},...a?{force_killed:!0}:{}}}catch(a){throw new o({error:"daemon_stop_failed",message:`failed to stop daemon${n?` pid ${e}`:""}: ${a.message}`,next:"Run `crtr sys daemon status` to inspect the daemon before retrying."})}},"run")}),A=w({name:"daemon",description:"manage the crtrd supervisor process",whenToUse:"managing the crtrd supervisor that auto-revives nodes on window exit \u2014 start it, restart it onto a new runtime generation, check its status, or stop it",help:{name:"sys daemon",summary:"manage the crtrd canvas supervisor daemon",model:"crtrd is a thin background daemon that polls active+idle nodes and acts on window exit: crashed windows become dead; refresh-yield windows get a fresh respawn. It holds no orchestration logic \u2014 just process supervision. These are operator/dev self-management, not something a normal agent turn needs to check. Picking up a newly installed runtime generation is `restart` (a handover the daemon performs on itself); `stop` is the terminal one, and it kills the caller along with the rest of the fleet."},children:[q,I,S,P,E,R]});function G(){return T([A])}s(G,"registerDaemonControlSys");export{A as daemonBranch,G as registerDaemonControlSys};