@north-light/crouter 0.3.318 → 0.3.320

package/dist/commands/memory/write.js

@@ -1,235 +1,13 @@
-import { envNodeId, envProfileId } from '../../shared/env.js';
-import { dirname, join } from 'node:path';
-import { defineLeaf } from '../../core/command.js';
-import { usage } from '../../core/errors.js';
-import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
-import { lintMemoryDocument, resolvableCanonicalNames } from '../../core/memory/lint.js';
-import { descendantStoreRoots } from '../../core/nested-stores.js';
-import { projectScopeRoots } from '../../core/scope.js';
-import { loadMemoryTargetView, openProjectMemoryStore } from '../../core/memory-resolver.js';
-import { parsedSubstrateSurfaces } from '../../core/substrate/frontmatter-validation.js';
-import { ensureDir, realpathOrSelf, walkFiles, writeText } from '../../core/fs-utils.js';
-import { associateRepository } from '../../core/memory/repository-association.js';
-import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, } from '../../core/memory/history.js';
-import { DOC_RATIONALE_CONSTRAINT, GUIDE_CANONICAL_NAMES, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, planNewDocumentPlacement, resolveWriteSelector, requireMountedStore, buildOrigin, coerceGate, coerceLintIgnore, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, requireCanonicalName, selectorParam, parseRequestedExtensionChanges, applyExtensionChanges, serializeMemoryDoc, } from './shared.js';
-function emptyMemoryStore(memoryDir) {
-    return walkFiles(memoryDir, (name) => name.endsWith('.md') && name !== 'SKILL.md', (name) => name === '.crouter').length === 0;
-}
-function hasWorkspaceFrontDoor(surfaces) {
-    const workspaceOpen = surfaces.some((entry) => entry['on'] === 'workspace-open' && entry['at'] === 'content');
-    const readEntry = surfaces.some((entry) => {
-        if (entry['on'] !== 'read' || entry['at'] !== 'content')
-            return false;
-        const match = entry['match'];
-        return match === './**' || (Array.isArray(match) && match.includes('./**'));
-    });
-    return workspaceOpen && readEntry;
-}
-// A topic's memory set stays usable only when authors treat cohesion as a creation
-// gate; otherwise small corrections accumulate as overlapping leaves whose routing
-// lines cannot tell a future reader which one owns the topic.
-export const writeLeaf = defineLeaf({
-    name: 'write',
-    description: 'create a memory document',
-    whenToUse: 'you are recording a new knowledge document or preference that does not exist yet. Creation only — a name already taken at the resolved scope is an error, because revising a stored document goes through `crtr memory edit`, which requires a rationale and records the revision.',
-    help: {
-        name: 'memory write',
-        summary: 'create a memory document at the resolved store from frontmatter flags + a stdin body',
-        guide: 'Every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, so default each rung down.\n\n' +
-            'Pick the kind. knowledge is consulted for facts or procedures; preference directs behavior. The kind choice is about how the doc is used, not about how long it is.\n\n' +
-            'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, and cross-repo conventions. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
-            GUIDE_SURFACES + '\n\n' +
-            'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is scratch memory only this running node sees; it rides into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
-            'A workspace front door is an ordinary doc carrying the entry pair {on: workspace-open, at: content} plus {on: read, match: "./**", at: content}: it enters first-message context when cwd/profile mounts its project store and fires on any file read beneath the store’s owning dir. Target the exact project with --dir. Keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` requires this front door on the repository-root guide for a repository managed by the selected profile; nested stores may carry ordinary guides without a missing-door finding.\n\n' +
-            'Choose the hook — boot vs read. A boot entry rides the boot catalog every agent sees; a read entry fires only when a matching file is actually read. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it off boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so skip read entries and route it through boot instead.\n\n' +
-            'Write the routing line (--when-and-why-to-read) first, before storing anything. ' + GUIDE_ROUTING_LINE + '\n\n' +
-            GUIDE_PREDICATE_VOCABULARY + '\n\n' +
-            GUIDE_CANONICAL_NAMES + '\n\n' +
-            GUIDE_DOC_LINKS + '\n\n' +
-            'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]`. Split by subject: a leaf earns its link by covering a different subject a task might need on its own; a leaf of offloaded “further evidence”, examples, or references is never followed, so supporting material either sits in the main doc next to the point it supports or gets cut. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Give reference leaves no surfaces at all — the directory listing and the link from the main doc are how they are found, so any routing entry just double-charges every boot or read for depth the graph already routes. State each fact once. Keep facts that affect action or judgment, including constraints, exceptions, numbers, and exact names. Remove known context, inferable conclusions, filler transitions, and examples that resolve no ambiguity. `crtr memory lint` caps body length by delivery rung and its findings carry the split guidance.\n\n' +
-            'A directory needs no index doc: reading a directory name returns its listing — each member’s routing line — so never author a doc that merely lists, fronts, or paraphrases its siblings. Write a directory-level doc only for synthesis: an operating guide or the cluster’s mechanics, ordering, conditions, and relationships, content no single member can carry. Guided entrance into a topic is an ordinary member doc, found through the listing like any other.\n\n' +
-            'Find before write. Prefer slightly expanding an existing document with `crtr memory edit`, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body whose merge into the existing document would make it harder to route or use. Group related docs with path names (area/topic). Provenance is stamped here and preserved by every later revision.\n\n' +
-            'This leaf validates the document it just wrote and reports any finding; a silent result means it is clean, so there is nothing to run afterwards. The check is scoped to this one document — `crtr memory lint` remains the corpus-wide sweep, and only it catches store-level faults such as a canonical collision or a missing workspace front door.\n\n' +
-            '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. If the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into. Omit the flag when you have no observed gap to record.\n\n' +
-            'Revise an existing doc with `crtr memory edit`.',
-        params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical identity. Project writes require `<namespace>/<local name>`; writing the namespace itself targets the repository-root document. A trailing `/INDEX` is invalid because directory documents answer at the directory name. The identity must be free in the selected exact store.' },
-            overlayParam('kind', { required: true }),
-            overlayParam('when-and-why-to-read', { required: true }),
-            overlayParam('short-form'),
-            overlayParam('unlisted'),
-            overlayParam('surface'),
-            overlayParam('gate'),
-            overlayParam('lint-ignore'),
-            overlayParam('slash'),
-            { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: DOC_RATIONALE_CONSTRAINT },
-            { kind: 'flag', name: 'extension', type: 'string', required: false, repeatable: true, constraint: 'Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is written.' },
-            selectorParam('scope-write'),
-            selectorParam('dir'),
-            selectorParam('profile'),
-            { kind: 'stdin', name: 'body', required: true, constraint: 'Document body (markdown, no frontmatter). Piped on stdin only — this leaf already claims the one positional for NAME, so a second bare argv token is rejected, not silently accepted as the body.' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'The full canonical document name written — the resolved identity, which composes a namespace onto the name you passed when the store declares one.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user, project, profile, or node. The selector rules decide this, so it is the one placement fact the invocation does not already state.' },
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document.' },
-            { name: 'findings', type: 'object[]', required: false, constraint: 'Authoring problems in the document just written, each {severity, rule, message}. ABSENT when the document is clean, which is the normal case — a silent result means it validated. Covers every rule that reads one document: yaml, schema, extension, length, short-preview, local-name, namespace-placement, root-name, nested-store-boot, broad-memory-read, and a workspace front door on a non-root doc. Reference rules (dangling-link, memory-read-route) run only when the document actually carries a `[[link]]` or a memory-read route. The document is written either way: a finding reports what to revise with `crtr memory edit`, it does not mean the write failed.' },
-        ],
-        outputKind: 'object',
-        dynamicState: () => memoryExtensionFieldCatalogHelp('write'),
-        effects: [
-            'Creates the selected physical memory document with the given frontmatter fields + stdin body, and opens its mirrored `.history` sidecar with a `create` record. An empty repository-root store is initialized at its root namespace only when the ordinary workspace front door surfaces are supplied.'
-        ],
-    },
-    run: async (input) => {
-        const name = input['name'];
-        const kind = input['kind'];
-        const scopeArg = input['scope'];
-        const profileArg = input['profile'];
-        const body = input['body'] ?? '';
-        const dirArg = input['dir'];
-        const selector = resolveWriteSelector({ scope: scopeArg, profile: profileArg, dir: dirArg });
-        const { scope, memoryDir, store } = selector;
-        let initializing = false;
-        if (scope === 'project' && store.mountStatus !== 'ready' && dirArg !== undefined && emptyMemoryStore(memoryDir)) {
-            const association = associateRepository(realpathOrSelf(dirArg));
-            if (association.ok) {
-                if (association.association.ownerRelativePath !== '') {
-                    throw usage(`${dirArg} is a nested store in the repository rooted at ${association.association.repositoryRoot}; only the repository root declares a namespace`, {
-                        next: 'crtr memory write <namespace> --dir <repositoryRoot>, or crtr sys migrate --dir <repositoryRoot>',
-                    });
-                }
-                initializing = true;
-            }
-            else if (association.code === 'no-project-root') {
-                initializing = true;
-            }
-        }
-        if (scope === 'project' && store.mountStatus !== 'ready' && !initializing)
-            requireMountedStore(store);
-        let canonicalName;
-        let path;
-        if (initializing) {
-            canonicalName = requireCanonicalName(name);
-            path = join(memoryDir, 'INDEX.md');
-        }
-        else {
-            const placement = planNewDocumentPlacement(store, name);
-            canonicalName = placement.canonicalName;
-            path = placement.path;
-        }
-        const lintIgnore = coerceLintIgnore(input['lintIgnore']);
-        const extensionChanges = parseRequestedExtensionChanges(input['extension'], undefined, memoryExtensionCatalogForDoc({ scope, path }));
-        const frontmatter = {};
-        frontmatter['kind'] = kind;
-        if (initializing)
-            frontmatter['namespace'] = canonicalName;
-        // Provenance is runtime-stamped ONCE, here — who/when/where authored this
-        // doc. Every later revision preserves it, so it always points at the
-        // conversation that created the doc, not the last one to touch it.
-        // `crtr memory origin <name>` derefs it.
-        const origin = buildOrigin();
-        frontmatter['origin'] = origin;
-        const setIf = (key, value) => {
-            if (value !== undefined)
-                frontmatter[key] = value;
-        };
-        setIf('when-and-why-to-read', input['whenAndWhyToRead']);
-        setIf('short-form', input['shortForm']);
-        if (input['unlisted'] === true)
-            frontmatter['unlisted'] = true;
-        if (input['surface'] !== undefined) {
-            frontmatter['surfaces'] = input['surface'].map(coerceSurface);
-        }
-        if (input['gate'] !== undefined)
-            frontmatter['gate'] = coerceGate(input['gate']);
-        setIf('lint-ignore', lintIgnore);
-        if (input['slash'] === true)
-            frontmatter['slash'] = true;
-        setIf('rationale', input['rationale']);
-        applyExtensionChanges(frontmatter, extensionChanges.sets, extensionChanges.unsets);
-        // One field consumers read for recency, live from the first byte.
-        frontmatter['last-updated'] = origin['created'];
-        // A workspace-open entry fires only when cwd/profile mounts the doc's
-        // project store, so outside project scope it is a dead route — reject it
-        // at authoring time.
-        const surfacesVal = frontmatter['surfaces'];
-        if (scope !== 'project' &&
-            Array.isArray(surfacesVal) &&
-            surfacesVal.some((e) => e !== null && typeof e === 'object' && e['on'] === 'workspace-open')) {
-            throw usage('a workspace-open surfaces entry is a project-store mount route; user, profile, and node memory cannot carry one — drop the entry or write to a project store');
-        }
-        if (initializing) {
-            const surfaces = Array.isArray(surfacesVal) ? surfacesVal.filter((entry) => entry !== null && typeof entry === 'object') : [];
-            if (!hasWorkspaceFrontDoor(surfaces)) {
-                throw usage('empty project initialization requires the ordinary workspace front door: --surface \'{on: workspace-open, at: content}\' and --surface \'{on: read, match: "./**", at: content}\'', {
-                    memory: canonicalName,
-                    next: `Pass both front-door surfaces when initializing ${canonicalName} with --dir.`,
-                });
-            }
-        }
-        const after = serializeMemoryDoc(frontmatter, body);
-        ensureDir(memoryDir);
-        writeText(path, after);
-        const logPath = historyLogPathFor(memoryDir, path);
-        appendHistoryRecord(logPath, buildHistoryRecord({ op: 'create', before: '', after }));
-        // Validate what was just authored, here, rather than returning a follow_up
-        // asking the author to go run lint — an obligation every write carries is
-        // the command's job, not a decision to hand back. Scoped to this one
-        // document: a corpus-wide sweep would surface unrelated findings from other
-        // docs on every write, which teaches an author to ignore the output.
-        //
-        // Each rule that needs an index beyond this file is paid for ONLY when the
-        // document can actually trip it. Reference resolution needs every canonical
-        // name in the view — seconds on a large corpus — so it is bought only when
-        // the doc carries a reference; nested-store detection walks the project
-        // roots, so it is bought only when the doc carries a boot entry.
-        const surfaceEntries = parsedSubstrateSurfaces(frontmatter);
-        const carriesReference = docLinkNames(body).length > 0 || surfaceEntries.some((entry) => entry.on === 'memory-read');
-        const carriesBootEntry = surfaceEntries.some((entry) => entry.on === 'boot');
-        // Initializing created the root declaration after selector resolution, so
-        // validate against a freshly described store: the stale descriptor has no
-        // repository-root association yet and would reject its valid namespace.
-        const lintStore = initializing ? openProjectMemoryStore(store.ownerDir ?? dirname(dirname(memoryDir))) : store;
-        const lint = lintMemoryDocument(lintStore, path, {
-            ...(carriesReference
-                ? {
-                    resolvable: resolvableCanonicalNames(loadMemoryTargetView({
-                        cwd: store.ownerDir ?? process.cwd(),
-                        profileId: envProfileId() || null,
-                        nodeId: envNodeId() || null,
-                    }, { quiet: true, includeDescendants: true }).docs),
-                }
-                : {}),
-            ...(carriesBootEntry
-                ? {
-                    nestedStore: descendantStoreRoots(projectScopeRoots(process.cwd(), envProfileId() || null))
-                        .map((root) => realpathOrSelf(join(root, 'memory')))
-                        .includes(realpathOrSelf(memoryDir)),
-                }
-                : {}),
-        });
-        // Findings ride the RESULT only. `memory lint` also streams them to stderr
-        // because it walks hundreds of files and the stream is progress; one
-        // document has no progress to report, and an agent that captures 2>&1
-        // would pay for every finding twice.
-        // The result confirms only what the caller could not already know: the
-        // resolved identity, where the selector rules put it, and anything wrong
-        // with what they just wrote. Echoing back the frontmatter flags just spent
-        // charges the author a second time for text they typed one call ago.
-        return {
-            name: canonicalName,
-            scope,
-            path,
-            ...(lint.findings.length === 0
-                ? {}
-                : {
-                    findings: lint.findings.map((finding) => ({
-                        severity: finding.severity,
-                        rule: finding.rule,
-                        message: finding.message,
-                    })),
-                }),
-        };
-    },
-});
+var U=Object.defineProperty;var h=(t,r)=>U(t,"name",{value:r,configurable:!0});import{envNodeId as _,envProfileId as D}from"../../shared/env.js";import{dirname as q,join as N}from"node:path";import{defineLeaf as G}from"../../core/command.js";import{usage as b}from"../../core/errors.js";import{docLinkNames as F}from"../../core/memory/doc-link-grammar.js";import{lintMemoryDocument as M,resolvableCanonicalNames as W}from"../../core/memory/lint.js";import{descendantStoreRoots as K}from"../../core/nested-stores.js";import{projectScopeRoots as z}from"../../core/scope.js";import{loadMemoryTargetView as V,openProjectMemoryStore as B}from"../../core/memory-resolver.js";import{parsedSubstrateSurfaces as H}from"../../core/substrate/frontmatter-validation.js";import{ensureDir as X,realpathOrSelf as v,walkFiles as $,writeText as Y}from"../../core/fs-utils.js";import{associateRepository as J}from"../../core/memory/repository-association.js";import{appendHistoryRecord as Q,buildHistoryRecord as Z,historyLogPathFor as ee}from"../../core/memory/history.js";import{DOC_RATIONALE_CONSTRAINT as te,GUIDE_CANONICAL_NAMES as oe,GUIDE_DOC_LINKS as re,GUIDE_PREDICATE_VOCABULARY as ne,GUIDE_ROUTING_LINE as ae,GUIDE_SURFACES as ie,planNewDocumentPlacement as se,resolveWriteSelector as ce,requireMountedStore as de,buildOrigin as le,coerceGate as he,coerceLintIgnore as me,coerceSurface as ue,memoryExtensionCatalogForDoc as pe,memoryExtensionFieldCatalogHelp as fe,overlayParam as a,requireCanonicalName as ye,selectorParam as k,parseRequestedExtensionChanges as ge,applyExtensionChanges as we,serializeMemoryDoc as be}from"./shared.js";function ve(t){return $(t,r=>r.endsWith(".md")&&r!=="SKILL.md",r=>r===".crouter").length===0}h(ve,"emptyMemoryStore");function ke(t){const r=t.some(n=>n.on==="workspace-open"&&n.at==="content"),w=t.some(n=>{if(n.on!=="read"||n.at!=="content")return!1;const m=n.match;return m==="./**"||Array.isArray(m)&&m.includes("./**")});return r&&w}h(ke,"hasWorkspaceFrontDoor");const Ue=G({name:"write",description:"create a memory document",whenToUse:"you are recording a new knowledge document or preference that does not exist yet. Creation only \u2014 a name already taken at the resolved scope is an error, because revising a stored document goes through `crtr memory edit`, which requires a rationale and records the revision.",help:{name:"memory write",summary:"create a memory document at the resolved store from frontmatter flags + a stdin body",guide:`Every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, so default each rung down.
+
+Pick the kind. knowledge is consulted for facts or procedures; preference directs behavior. The kind choice is about how the doc is used, not about how long it is.
+
+Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, and cross-repo conventions. Do not store chat summaries, implementation history, or facts already recorded in the repo.
+
+`+ie+'\n\nChoose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile\u2019s bundle of dirs: cross-repo conventions, how the pieces relate, or the user\u2019s stance toward that body of work. `node` is scratch memory only this running node sees; it rides into this node\u2019s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\nA workspace front door is an ordinary doc carrying the entry pair {on: workspace-open, at: content} plus {on: read, match: "./**", at: content}: it enters first-message context when cwd/profile mounts its project store and fires on any file read beneath the store\u2019s owning dir. Target the exact project with --dir. Keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` requires this front door on the repository-root guide for a repository managed by the selected profile; nested stores may carry ordinary guides without a missing-door finding.\n\nChoose the hook \u2014 boot vs read. A boot entry rides the boot catalog every agent sees; a read entry fires only when a matching file is actually read. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it off boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so skip read entries and route it through boot instead.\n\nWrite the routing line (--when-and-why-to-read) first, before storing anything. '+ae+`
+
+`+ne+`
+
+`+oe+`
+
+`+re+"\n\nWhen a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic\u2019s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic\u2019s directory (`area/topic/...`), each pointed at with a `[[link]]`. Split by subject: a leaf earns its link by covering a different subject a task might need on its own; a leaf of offloaded \u201Cfurther evidence\u201D, examples, or references is never followed, so supporting material either sits in the main doc next to the point it supports or gets cut. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Give reference leaves no surfaces at all \u2014 the directory listing and the link from the main doc are how they are found, so any routing entry just double-charges every boot or read for depth the graph already routes. State each fact once. Keep facts that affect action or judgment, including constraints, exceptions, numbers, and exact names. Remove known context, inferable conclusions, filler transitions, and examples that resolve no ambiguity. `crtr memory lint` caps body length by delivery rung and its findings carry the split guidance.\n\nA directory needs no index doc: reading a directory name returns its listing \u2014 each member\u2019s routing line \u2014 so never author a doc that merely lists, fronts, or paraphrases its siblings. Write a directory-level doc only for synthesis: an operating guide or the cluster\u2019s mechanics, ordering, conditions, and relationships, content no single member can carry. Guided entrance into a topic is an ordinary member doc, found through the listing like any other.\n\nFind before write. Prefer slightly expanding an existing document with `crtr memory edit`, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body whose merge into the existing document would make it harder to route or use. Group related docs with path names (area/topic). Provenance is stamped here and preserved by every later revision.\n\nThis leaf validates the document it just wrote and reports any finding; a silent result means it is clean, so there is nothing to run afterwards. The check is scoped to this one document \u2014 `crtr memory lint` remains the corpus-wide sweep, and only it catches store-level faults such as a canonical collision or a missing workspace front door.\n\n--rationale is the gap this doc exists to close \u2014 the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc\u2019s own content. If the rationale is guessable from reading the doc, it is not the real one \u2014 a guessable gap is one agents do not actually fall into. Omit the flag when you have no observed gap to record.\n\nRevise an existing doc with `crtr memory edit`.",params:[{kind:"positional",name:"name",required:!0,constraint:"Full canonical identity. Project writes require `<namespace>/<local name>`; writing the namespace itself targets the repository-root document. A trailing `/INDEX` is invalid because directory documents answer at the directory name. The identity must be free in the selected exact store."},a("kind",{required:!0}),a("when-and-why-to-read",{required:!0}),a("short-form"),a("unlisted"),a("surface"),a("gate"),a("lint-ignore"),a("slash"),{kind:"flag",name:"rationale",type:"string",required:!1,constraint:te},{kind:"flag",name:"extension",type:"string",required:!1,repeatable:!0,constraint:"Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is written."},k("scope-write"),k("dir"),k("profile"),{kind:"stdin",name:"body",required:!0,constraint:"Document body (markdown, no frontmatter). Piped on stdin only \u2014 this leaf already claims the one positional for NAME, so a second bare argv token is rejected, not silently accepted as the body."}],output:[{name:"name",type:"string",required:!0,constraint:"The full canonical document name written \u2014 the resolved identity, which composes a namespace onto the name you passed when the store declares one."},{name:"scope",type:"string",required:!0,constraint:"Scope the document was written to: user, project, profile, or node. The selector rules decide this, so it is the one placement fact the invocation does not already state."},{name:"path",type:"string",required:!0,constraint:"Absolute path to the written document."},{name:"findings",type:"object[]",required:!1,constraint:"Authoring problems in the document just written, each {severity, rule, message}. ABSENT when the document is clean, which is the normal case \u2014 a silent result means it validated. Covers every rule that reads one document: yaml, schema, extension, length, short-preview, local-name, namespace-placement, root-name, nested-store-boot, broad-memory-read, and a workspace front door on a non-root doc. Reference rules (dangling-link, memory-read-route) run only when the document actually carries a `[[link]]` or a memory-read route. The document is written either way: a finding reports what to revise with `crtr memory edit`, it does not mean the write failed."}],outputKind:"object",dynamicState:h(()=>fe("write"),"dynamicState"),effects:["Creates the selected physical memory document with the given frontmatter fields + stdin body, and opens its mirrored `.history` sidecar with a `create` record. An empty repository-root store is initialized at its root namespace only when the ordinary workspace front door surfaces are supplied."]},run:h(async t=>{const r=t.name,w=t.kind,n=t.scope,m=t.profile,x=t.body??"",f=t.dir,R=ce({scope:n,profile:m,dir:f}),{scope:u,memoryDir:d,store:i}=R;let s=!1;if(u==="project"&&i.mountStatus!=="ready"&&f!==void 0&&ve(d)){const e=J(v(f));if(e.ok){if(e.association.ownerRelativePath!=="")throw b(`${f} is a nested store in the repository rooted at ${e.association.repositoryRoot}; only the repository root declares a namespace`,{next:"crtr memory write <namespace> --dir <repositoryRoot>, or crtr sys migrate --dir <repositoryRoot>"});s=!0}else e.code==="no-project-root"&&(s=!0)}u==="project"&&i.mountStatus!=="ready"&&!s&&de(i);let l,c;if(s)l=ye(r),c=N(d,"INDEX.md");else{const e=se(i,r);l=e.canonicalName,c=e.path}const T=me(t.lintIgnore),A=ge(t.extension,void 0,pe({scope:u,path:c})),o={};o.kind=w,s&&(o.namespace=l);const j=le();o.origin=j;const y=h((e,p)=>{p!==void 0&&(o[e]=p)},"setIf");y("when-and-why-to-read",t.whenAndWhyToRead),y("short-form",t.shortForm),t.unlisted===!0&&(o.unlisted=!0),t.surface!==void 0&&(o.surfaces=t.surface.map(ue)),t.gate!==void 0&&(o.gate=he(t.gate)),y("lint-ignore",T),t.slash===!0&&(o.slash=!0),y("rationale",t.rationale),we(o,A.sets,A.unsets),o["last-updated"]=j.created;const g=o.surfaces;if(u!=="project"&&Array.isArray(g)&&g.some(e=>e!==null&&typeof e=="object"&&e.on==="workspace-open"))throw b("a workspace-open surfaces entry is a project-store mount route; user, profile, and node memory cannot carry one \u2014 drop the entry or write to a project store");if(s){const e=Array.isArray(g)?g.filter(p=>p!==null&&typeof p=="object"):[];if(!ke(e))throw b(`empty project initialization requires the ordinary workspace front door: --surface '{on: workspace-open, at: content}' and --surface '{on: read, match: "./**", at: content}'`,{memory:l,next:`Pass both front-door surfaces when initializing ${l} with --dir.`})}const E=be(o,x);X(d),Y(c,E);const C=ee(d,c);Q(C,Z({op:"create",before:"",after:E}));const S=H(o),P=F(x).length>0||S.some(e=>e.on==="memory-read"),L=S.some(e=>e.on==="boot"),O=s?B(i.ownerDir??q(q(d))):i,I=M(O,c,{...P?{resolvable:W(V({cwd:i.ownerDir??process.cwd(),profileId:D()||null,nodeId:_()||null},{quiet:!0,includeDescendants:!0}).docs)}:{},...L?{nestedStore:K(z(process.cwd(),D()||null)).map(e=>v(N(e,"memory"))).includes(v(d))}:{}});return{name:l,scope:u,path:c,...I.findings.length===0?{}:{findings:I.findings.map(e=>({severity:e.severity,rule:e.rule,message:e.message}))}}},"run")});export{Ue as writeLeaf};

package/dist/commands/memory.js

@@ -1,30 +1 @@
-// `crtr memory` subtree — the document substrate (knowledge and preferences)
-// accessed via the CLI. Flat leaves: list, read, find, write, edit, move,
-// history, delete, origin, lint.
-import { defineBranch } from '../core/command.js';
-import { listLeaf } from './memory/list.js';
-import { readLeaf } from './memory/read.js';
-import { findLeaf } from './memory/find.js';
-import { writeLeaf } from './memory/write.js';
-import { editLeaf } from './memory/edit.js';
-import { moveLeaf } from './memory/move.js';
-import { historyLeaf } from './memory/history.js';
-import { deleteLeaf } from './memory/delete.js';
-import { originLeaf } from './memory/origin.js';
-import { lintLeaf } from './memory/lint.js';
-export function registerMemory() {
-    return defineBranch({
-        name: 'memory',
-        rootEntry: {
-            concept: 'a memory document you read on demand — knowledge or a preference',
-            desc: 'list, read, search, and write memory documents',
-            useWhen: 'durable knowledge and preferences shared across nodes and sessions — use when prior guidance may apply to the current task, or when a non-obvious reusable truth should outlive this conversation. Every document has one canonical name, a crtr identifier rather than a file path — read docs through the command surface, never cat or find the markdown off disk. Slash commands are authored here too — one is a document flagged invocable.',
-        },
-        help: {
-            name: 'memory',
-            summary: 'list, read, search, and write memory documents — knowledge and preferences',
-            model: 'One address per document: its canonical name, the store’s namespace composed with its store-local name. A repository declares that namespace once, as `namespace:` on the root `INDEX.md` of `<repository root>/.crouter/memory/`, and a store nested inside the repository composes under that namespace plus its own path from the repository root; user, profile, node, and builtin names carry no namespace, and an installed plugin’s documents mount under the plugin’s own name. Resolution is exact — a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail — so `find` is the discovery surface when you do not know a name and `list` browses the whole inventory. A trailing `INDEX` is never part of an address, so a directory may carry its own document: reading the directory name returns that body together with the directory’s immediate listing. Precedence — node > project stack > profile > user > builtin — picks the winner among documents sharing ONE canonical name; `--paths` reports every physical candidate behind a name, and `--dir <project>` reaches one exact store. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `move` relocates or renames a doc and rewrites inbound `[[refs]]` corpus-wide, `delete` removes, and `history` reads how a document reached its current state. Beyond listings, delivery is explicit `surfaces` routing: each entry names the event that fires it (boot, workspace-open, read, memory-read, command) and how much delivers (name, preview, content). A selected profile widens the project stack to every project in its purview, and each of those relationships caps what its stores deliver to the boot and workspace-open events; `read`, find, listings, and file- and command-routed delivery see the full corpus regardless.',
-        },
-        children: [listLeaf, readLeaf, findLeaf, writeLeaf, editLeaf, moveLeaf, historyLeaf, deleteLeaf, originLeaf, lintLeaf],
-    });
-}
+var a=Object.defineProperty;var e=(r,o)=>a(r,"name",{value:o,configurable:!0});import{defineBranch as t}from"../core/command.js";import{listLeaf as n}from"./memory/list.js";import{readLeaf as s}from"./memory/read.js";import{findLeaf as i}from"./memory/find.js";import{writeLeaf as d}from"./memory/write.js";import{editLeaf as m}from"./memory/edit.js";import{moveLeaf as c}from"./memory/move.js";import{historyLeaf as l}from"./memory/history.js";import{deleteLeaf as h}from"./memory/delete.js";import{originLeaf as p}from"./memory/origin.js";import{lintLeaf as f}from"./memory/lint.js";function A(){return t({name:"memory",rootEntry:{concept:"a memory document you read on demand \u2014 knowledge or a preference",desc:"list, read, search, and write memory documents",useWhen:"durable knowledge and preferences shared across nodes and sessions \u2014 use when prior guidance may apply to the current task, or when a non-obvious reusable truth should outlive this conversation. Every document has one canonical name, a crtr identifier rather than a file path \u2014 read docs through the command surface, never cat or find the markdown off disk. Slash commands are authored here too \u2014 one is a document flagged invocable."},help:{name:"memory",summary:"list, read, search, and write memory documents \u2014 knowledge and preferences",model:"One address per document: its canonical name, the store\u2019s namespace composed with its store-local name. A repository declares that namespace once, as `namespace:` on the root `INDEX.md` of `<repository root>/.crouter/memory/`, and a store nested inside the repository composes under that namespace plus its own path from the repository root; user, profile, node, and builtin names carry no namespace, and an installed plugin\u2019s documents mount under the plugin\u2019s own name. Resolution is exact \u2014 a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail \u2014 so `find` is the discovery surface when you do not know a name and `list` browses the whole inventory. A trailing `INDEX` is never part of an address, so a directory may carry its own document: reading the directory name returns that body together with the directory\u2019s immediate listing. Precedence \u2014 node > project stack > profile > user > builtin \u2014 picks the winner among documents sharing ONE canonical name; `--paths` reports every physical candidate behind a name, and `--dir <project>` reaches one exact store. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `move` relocates or renames a doc and rewrites inbound `[[refs]]` corpus-wide, `delete` removes, and `history` reads how a document reached its current state. Beyond listings, delivery is explicit `surfaces` routing: each entry names the event that fires it (boot, workspace-open, read, memory-read, command) and how much delivers (name, preview, content). A selected profile widens the project stack to every project in its purview, and each of those relationships caps what its stores deliver to the boot and workspace-open events; `read`, find, listings, and file- and command-routed delivery see the full corpus regardless."},children:[n,s,i,d,m,c,l,h,p,f]})}e(A,"registerMemory");export{A as registerMemory};

package/dist/commands/node/bash.js

@@ -1,245 +1,5 @@
-// `crtr node bash` — file-backed background job controls.
-import { envNodeId } from '../../shared/env.js';
-import { defineBranch, defineLeaf } from '../../core/command.js';
-import { InputError } from '../../core/io.js';
-import { contextDir } from '../../core/canvas/paths.js';
-import { existsSync } from 'node:fs';
-import { activeBackgroundBashJobs, backgroundRunningBashJobs, bashJobCommandLine, bashJobPaths, clearJobDeadline, formatBashElapsed, isSafeBashJobId, jobStartedAtMs, readJobPgid, stopBackgroundBashJob, tailJobLog, writeJobDeadlineMs } from '../../core/bash-jobs.js';
-import { parseDurationMs } from '../../core/wake.js';
-import { cliClient, getNodeOrNull } from '../api-client.js';
-import { nodeInPane } from '../surface/node/placement.js';
-function resolveBashTarget(input, missingMessage) {
-    const pane = input['pane'] ?? process.env['TMUX_PANE'];
-    let id = input['node'];
-    if (id === undefined || id === '')
-        id = nodeInPane(pane);
-    if (id === undefined || id === '')
-        id = envNodeId();
-    if (id === undefined || id === '') {
-        throw new InputError({ error: 'no_node', message: missingMessage, next: 'Run from inside a node, pass --node <id>, or --pane <pane>.' });
-    }
-    return { id, pane };
-}
-const nodeBashBackground = defineLeaf({
-    name: 'background',
-    description: 'hand the focused node’s 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: false, 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: false, 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: true, constraint: 'The target node.' },
-            { name: 'jobs', type: 'object[]', required: true, constraint: 'Per handed-off job {job_id, elapsed_ms} — 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 sends the node an urgent inbox message when it exits, which steers the node mid-turn.'],
-    },
-    run: async (input) => {
-        const { id } = resolveBashTarget(input, 'no node found for the bash handoff');
-        if ((await getNodeOrNull(id)) === null) {
-            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
-        }
-        const jobs = backgroundRunningBashJobs(contextDir(id));
-        const now = Date.now();
-        const elapsed = jobs.map((job) => ({ job_id: job.jobId, elapsed_ms: now - (jobStartedAtMs(job.jobId) ?? now) }));
-        // No tmux toast. A tmux status-line message commandeers the whole client's
-        // status bar for seconds over an action the user just took deliberately;
-        // the viewer reports its own handoff in its own status line, which is where
-        // someone watching that pane is already looking.
-        return { node_id: id, jobs: elapsed };
-    },
-    render: (result) => {
-        const jobs = result['jobs'];
-        if (jobs.length === 0)
-            return `No foreground bash command is running for ${result['node_id']}.`;
-        const oldestElapsedMs = Math.max(...jobs.map((job) => job.elapsed_ms));
-        return `Handed ${jobs.length} bash command(s) to the background job system for ${result['node_id']} · ran ${formatBashElapsed(oldestElapsedMs)} in the foreground.`;
-    },
-});
-const nodeBashList = defineLeaf({
-    name: 'list',
-    description: 'list a node’s live background bash jobs',
-    whenToUse: 'the Inspector’s 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: false, 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: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
-            { kind: 'flag', name: 'tail', type: 'int', required: false, default: 0, constraint: 'Include this many trailing log lines per job (0 = none).' },
-        ],
-        output: [
-            { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
-            { name: 'jobs', type: 'object[]', required: true, 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: async (input) => {
-        const { id } = resolveBashTarget(input, 'no node found for the bash job list');
-        const node = await getNodeOrNull(id);
-        if (node === null) {
-            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
-        }
-        const now = Date.now();
-        const tail = Math.max(0, Math.trunc(Number(input['tail'] ?? 0)));
-        const dir = contextDir(node.node_id);
-        const jobs = activeBackgroundBashJobs(dir).map((job) => ({
-            job_id: job.jobId,
-            command: job.command,
-            purpose: job.purpose,
-            started_at: new Date(job.startedAtMs).toISOString(),
-            elapsed_ms: now - job.startedAtMs,
-            deadline_at: job.deadlineAtMs === null ? null : new Date(job.deadlineAtMs).toISOString(),
-            log_path: job.logPath,
-            pgid: readJobPgid(dir, job.jobId) ?? null,
-            log_tail: tailJobLog(job.logPath, tail),
-        }));
-        return { node_id: node.node_id, jobs };
-    },
-    render: (result) => {
-        const jobs = result['jobs'];
-        if (jobs.length === 0)
-            return `No background bash jobs for ${result['node_id']}.`;
-        return jobs.map((job) => `${job.job_id} · ${formatBashElapsed(job.elapsed_ms)} · ${bashJobCommandLine(job.command)}${job.purpose === null ? '' : `\n  purpose: ${job.purpose}`}${job.deadline_at === null ? '' : `\n  cancels at: ${job.deadline_at}`}\n  log: ${job.log_path}`).join('\n');
-    },
-});
-const nodeBashKill = defineLeaf({
-    name: 'kill',
-    description: 'stop one of a node’s background bash jobs',
-    whenToUse: 'the user watching the Inspector or the attach cockpit’s 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: true, constraint: 'Job id, as reported by node bash list.' },
-            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
-            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
-        ],
-        output: [
-            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
-            { name: 'signaled', type: 'boolean', required: true, constraint: 'True when at least one observed supervisor-tree process received SIGTERM.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Snapshots the supervisor’s 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’s exit so it stops showing as live, and sends the owning node an urgent inbox message saying the job was stopped — which steers that node mid-turn.',
-        ],
-    },
-    run: async (input) => {
-        const { id } = resolveBashTarget(input, 'no node found for the bash job');
-        const node = await getNodeOrNull(id);
-        if (node === null) {
-            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
-        }
-        const jobId = input['job'];
-        if (!isSafeBashJobId(jobId)) {
-            throw new InputError({ error: 'invalid_job_id', message: `invalid background job id: ${jobId}`, next: 'Use a job id reported by `crtr node bash list`.' });
-        }
-        const dir = contextDir(node.node_id);
-        const paths = bashJobPaths(dir, jobId);
-        const stopped = await stopBackgroundBashJob(dir, jobId);
-        if (stopped.kind === 'missing') {
-            throw new InputError({ error: 'not_found', message: `no background job ${jobId} for ${node.node_id}`, next: 'List live jobs with `crtr node bash list`.' });
-        }
-        if (stopped.kind === 'retired') {
-            throw new InputError({
-                error: 'not_found',
-                message: `background job ${jobId} for ${node.node_id} is no longer running`,
-                next: `It finished or was already stopped, so nothing was signaled. Log: ${stopped.logPath}`,
-            });
-        }
-        if (stopped.kind === 'not-stoppable') {
-            throw new InputError({
-                error: 'not_stoppable',
-                message: `job ${jobId} recorded no trusted process identity`,
-                next: `It started before crtr persisted its supervisor identity. Stop it by hand, then it will disappear from the list. Log: ${paths.jobLog}`,
-            });
-        }
-        await cliClient().sendMessage(node.node_id, {
-            body: `Background bash job ${jobId} was stopped by the user before it finished. Log: ${paths.jobLog}  Command: ${paths.cmdSh}`,
-            tier: 'urgent',
-        });
-        return { node_id: node.node_id, signaled: stopped.signaled };
-    },
-    render: (result) => `Canceled a background bash job for ${result['node_id']}${result['signaled'] === true ? '' : ' (no observed job process was still running)'}.`,
-});
-const nodeBashExtend = defineLeaf({
-    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 — 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’s live background bash jobs',
-        params: [
-            { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as reported by node bash list or the auto-background notice.' },
-            { kind: 'flag', name: 'for', type: 'string', required: false, 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: false, 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: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
-            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
-        ],
-        output: [
-            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
-            { name: 'deadline_at', type: 'string', required: false, constraint: 'The job’s 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’s deadline file. The daemon’s deadline lane reads it on its next scan. Signals nothing.'],
-    },
-    run: async (input) => {
-        const { id } = resolveBashTarget(input, 'no node found for the bash job');
-        const node = await getNodeOrNull(id);
-        if (node === null) {
-            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
-        }
-        const jobId = input['job'];
-        if (!isSafeBashJobId(jobId)) {
-            throw new InputError({ error: 'invalid_job_id', message: `invalid background job id: ${jobId}`, next: 'Use a job id reported by `crtr node bash list`.' });
-        }
-        const forDuration = input['for'];
-        const keep = input['keep'] === true;
-        if (keep === (forDuration !== undefined && forDuration !== '')) {
-            throw new InputError({ 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 dir = contextDir(node.node_id);
-        const paths = bashJobPaths(dir, jobId);
-        if (!existsSync(paths.dir)) {
-            throw new InputError({ error: 'not_found', message: `no background job ${jobId} for ${node.node_id}`, next: 'List live jobs with `crtr node bash list`.' });
-        }
-        if (!existsSync(paths.jobBg) || existsSync(paths.jobExit)) {
-            throw new InputError({ error: 'not_running', message: `background job ${jobId} for ${node.node_id} is no longer running`, next: `It finished or was stopped, so there is no deadline to change. Log: ${paths.jobLog}` });
-        }
-        if (keep) {
-            clearJobDeadline(paths);
-            return { node_id: node.node_id };
-        }
-        const durationMs = parseDurationMs(forDuration);
-        if (durationMs === null || durationMs <= 0) {
-            throw new InputError({ error: 'invalid_duration', message: `not a duration: ${forDuration}`, next: 'Use a value like 90s, 10m, or 1h30m.' });
-        }
-        const deadlineMs = Date.now() + durationMs;
-        writeJobDeadlineMs(paths, deadlineMs);
-        return { node_id: node.node_id, deadline_at: new Date(deadlineMs).toISOString() };
-    },
-    render: (result) => result['deadline_at'] === undefined
-        ? `Cleared the deadline — the background job will run to completion for ${result['node_id']}.`
-        : `Background job for ${result['node_id']} will be canceled at ${result['deadline_at']} unless extended again.`,
-});
-export const nodeBash = defineBranch({
-    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 — the tmux prefix menu backgrounds, the Inspector’s jobs section lists and cancels',
-    tier: 'hidden',
-    help: {
-        name: 'node bash',
-        summary: 'control file-backed bash jobs owned by a node',
-    },
-    children: [nodeBashBackground, nodeBashList, nodeBashKill, nodeBashExtend],
-});
+var k=Object.defineProperty;var i=(n,t)=>k(n,"name",{value:t,configurable:!0});import{envNodeId as j}from"../../shared/env.js";import{defineBranch as y,defineLeaf as h}from"../../core/command.js";import{InputError as d}from"../../core/io.js";import{contextDir as c}from"../../core/canvas/paths.js";import{existsSync as m}from"node:fs";import{activeBackgroundBashJobs as x,backgroundRunningBashJobs as $,bashJobCommandLine as v,bashJobPaths as f,clearJobDeadline as I,formatBashElapsed as w,isSafeBashJobId as _,jobStartedAtMs as D,readJobPgid as T,stopBackgroundBashJob as M,tailJobLog as q,writeJobDeadlineMs as N}from"../../core/bash-jobs.js";import{parseDurationMs as L}from"../../core/wake.js";import{cliClient as B,getNodeOrNull as u}from"../api-client.js";import{nodeInPane as E}from"../surface/node/placement.js";function b(n,t){const e=n.pane??process.env.TMUX_PANE;let o=n.node;if((o===void 0||o==="")&&(o=E(e)),(o===void 0||o==="")&&(o=j()),o===void 0||o==="")throw new d({error:"no_node",message:t,next:"Run from inside a node, pass --node <id>, or --pane <pane>."});return{id:o,pane:e}}i(b,"resolveBashTarget");const S=h({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 sends the node an urgent inbox message when it exits, which steers the node mid-turn."]},run:i(async n=>{const{id:t}=b(n,"no node found for the bash handoff");if(await u(t)===null)throw new d({error:"not_found",message:`no node: ${t}`,next:"List nodes with `crtr node inspect list`."});const e=$(c(t)),o=Date.now(),r=e.map(s=>({job_id:s.jobId,elapsed_ms:o-(D(s.jobId)??o)}));return{node_id:t,jobs:r}},"run"),render:i(n=>{const t=n.jobs;if(t.length===0)return`No foreground bash command is running for ${n.node_id}.`;const e=Math.max(...t.map(o=>o.elapsed_ms));return`Handed ${t.length} bash command(s) to the background job system for ${n.node_id} \xB7 ran ${w(e)} in the foreground.`},"render")}),R=h({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:i(async n=>{const{id:t}=b(n,"no node found for the bash job list"),e=await u(t);if(e===null)throw new d({error:"not_found",message:`no node: ${t}`,next:"List nodes with `crtr node inspect list`."});const o=Date.now(),r=Math.max(0,Math.trunc(Number(n.tail??0))),s=c(e.node_id),l=x(s).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:T(s,a.jobId)??null,log_tail:q(a.logPath,r)}));return{node_id:e.node_id,jobs:l}},"run"),render:i(n=>{const t=n.jobs;return t.length===0?`No background bash jobs for ${n.node_id}.`:t.map(e=>`${e.job_id} \xB7 ${w(e.elapsed_ms)} \xB7 ${v(e.command)}${e.purpose===null?"":`
+  purpose: ${e.purpose}`}${e.deadline_at===null?"":`
+  cancels at: ${e.deadline_at}`}
+  log: ${e.log_path}`).join(`
+`)},"render")}),U=h({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 sends the owning node an urgent inbox message saying the job was stopped \u2014 which steers that node mid-turn."]},run:i(async n=>{const{id:t}=b(n,"no node found for the bash job"),e=await u(t);if(e===null)throw new d({error:"not_found",message:`no node: ${t}`,next:"List nodes with `crtr node inspect list`."});const o=n.job;if(!_(o))throw new d({error:"invalid_job_id",message:`invalid background job id: ${o}`,next:"Use a job id reported by `crtr node bash list`."});const r=c(e.node_id),s=f(r,o),l=await M(r,o);if(l.kind==="missing")throw new d({error:"not_found",message:`no background job ${o} for ${e.node_id}`,next:"List live jobs with `crtr node bash list`."});if(l.kind==="retired")throw new d({error:"not_found",message:`background job ${o} for ${e.node_id} is no longer running`,next:`It finished or was already stopped, so nothing was signaled. Log: ${l.logPath}`});if(l.kind==="not-stoppable")throw new d({error:"not_stoppable",message:`job ${o} recorded no trusted process identity`,next:`It started before crtr persisted its supervisor identity. Stop it by hand, then it will disappear from the list. Log: ${s.jobLog}`});return await B().sendMessage(e.node_id,{body:`Background bash job ${o} was stopped by the user before it finished. Log: ${s.jobLog}  Command: ${s.cmdSh}`,tier:"urgent"}),{node_id:e.node_id,signaled:l.signaled}},"run"),render:i(n=>`Canceled a background bash job for ${n.node_id}${n.signaled===!0?"":" (no observed job process was still running)"}.`,"render")}),J=h({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:i(async n=>{const{id:t}=b(n,"no node found for the bash job"),e=await u(t);if(e===null)throw new d({error:"not_found",message:`no node: ${t}`,next:"List nodes with `crtr node inspect list`."});const o=n.job;if(!_(o))throw new d({error:"invalid_job_id",message:`invalid background job id: ${o}`,next:"Use a job id reported by `crtr node bash list`."});const r=n.for,s=n.keep===!0;if(s===(r!==void 0&&r!==""))throw new d({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=c(e.node_id),a=f(l,o);if(!m(a.dir))throw new d({error:"not_found",message:`no background job ${o} for ${e.node_id}`,next:"List live jobs with `crtr node bash list`."});if(!m(a.jobBg)||m(a.jobExit))throw new d({error:"not_running",message:`background job ${o} for ${e.node_id} is no longer running`,next:`It finished or was stopped, so there is no deadline to change. Log: ${a.jobLog}`});if(s)return I(a),{node_id:e.node_id};const g=L(r);if(g===null||g<=0)throw new d({error:"invalid_duration",message:`not a duration: ${r}`,next:"Use a value like 90s, 10m, or 1h30m."});const p=Date.now()+g;return N(a,p),{node_id:e.node_id,deadline_at:new Date(p).toISOString()}},"run"),render:i(n=>n.deadline_at===void 0?`Cleared the deadline \u2014 the background job will run to completion for ${n.node_id}.`:`Background job for ${n.node_id} will be canceled at ${n.deadline_at} unless extended again.`,"render")}),Q=y({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:[S,R,U,J]});export{Q as nodeBash};