@north-light/crouter 0.3.275 → 0.3.276

package/dist/commands/cron.js

@@ -134,7 +134,7 @@ const addLeaf = defineLeaf({
             { kind: 'flag', name: 'at', type: 'string', required: false, constraint: 'One-shot: run the stored bash once at <when> — a duration ("90s","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", interpreted in --tz else host zone). Exactly one of --at / --every is required. The row is deleted after its run unless the run\'s disposition pauses it.' },
             { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'Recurring: run the stored bash at each cadence — a fixed interval ("6h" — first fire one interval from now), a 5-field cron ("0 9 * * *"), or an @alias ("@daily"). Each fire is another bash run. Minimum cadence 60s. Exactly one of --at / --every is required. For a gated cron (a command that exits 75 while ineligible), pick a LONG cadence: each natural slot is only the backstop re-check, and the daemon poke supplies the latency — "6h" plus poke beats "15m" polling on both latency and cost.' },
             { kind: 'flag', name: 'tz', type: 'string', required: false, constraint: 'IANA zone (e.g. "America/New_York") for a bare-ISO --at or a calendar --every. Defaults to the host zone.' },
-            { kind: 'flag', name: 'on-output', type: 'enum', choices: ['silent', 'on-failure', 'always', 'on-change'], required: false, default: 'on-failure', constraint: 'What each run does with its output. silent: record in the run log, tell nobody — never escalate. on-failure (default): no success delivery; a failing run pauses the cron and spawns a node to deal with it. always: deliver stdout every run to --sink at --tier. on-change: deliver stdout only when it differs from the previous run\'s — the shape polling wants.' },
+            { kind: 'flag', name: 'on-output', type: 'enum', choices: ['silent', 'on-failure', 'always', 'on-change'], required: false, constraint: 'What each run does with its output. Defaults to on-change for a node:<id> sink; otherwise on-failure. silent: record in the run log, tell nobody — never escalate. on-failure: no success delivery; a failing run pauses the cron and spawns a node to deal with it. always: deliver stdout every run to --sink at --tier. on-change: deliver stdout only when it differs from the previous run\'s — the shape polling wants.' },
             { kind: 'flag', name: 'sink', type: 'string', required: false, constraint: 'Where always/on-change stdout deliveries go: "node:<id>" (an existing node\'s inbox — must exist now; gone/finalized at fire time is a failure), "spawn:<kind>" (each delivered output creates a self-finishing node with stdout as kickoff — a managed child while its creator exists, otherwise a terminal parentless root), or "human" (the humanloop inbox). Required by always/on-change, rejected otherwise.' },
             { kind: 'flag', name: 'tier', type: 'enum', choices: ['normal', 'urgent', 'critical'], required: false, default: 'urgent', constraint: 'Inbox priority of a node-sink delivery. urgent (default): steers the target mid-turn, or wakes it when dormant — a fire is news the node asked for on a schedule, so it should land now. normal: waits for the running turn to settle. critical: aborts the running turn outright.' },
             { kind: 'flag', name: 'expires', type: 'string', required: false, constraint: 'Clock bound (same grammar as --at): the row is deleted once this instant passes. The self-limiting half of a poll-until pattern. For a held one-shot (last run exited 75), expiry bounds the wait for eligibility — the row is deleted UNFIRED, never fired blind at expiry.' },
@@ -254,7 +254,7 @@ const addLeaf = defineLeaf({
             env_json: envJson,
             profile: profile ?? null,
             scope,
-            on_output: input['onOutput'] ?? 'on-failure',
+            on_output: input['onOutput'],
             sink: typeof input['sink'] === 'string' && input['sink'] !== '' ? input['sink'] : null,
             tier: input['tier'] ?? 'urgent',
             expires_at: expiresAt,
@@ -525,7 +525,7 @@ export function registerCron() {
         help: {
             name: 'cron',
             summary: 'scheduled bash commands, daemon-run',
-            model: 'A cron stores and daemon-runs arbitrary bash at its clock. Use ordinary bash for ordinary work; choose node:<id> for stdout as inbox information to an existing node, an existing node\'s lifecycle fresh-revive action in the bash for a clean re-check without inbox output, or spawn:<kind> to route each output-producing fire to a fresh self-finishing node (a managed child while its creator exists, otherwise a terminal parentless root). Per-fire fresh agent work belongs on the existing spawn:<kind> sink, not an independent resident-root birth. A gate is bash, at the top of the command. Exit 0 after deciding not to act and the occurrence is simply spent — right when the recurrence is your polling cadence. Exit 75 and the occurrence is OWED: the row is held, fires again the moment the daemon receives an eligibility poke from the host platform, and otherwise re-checks at its next natural slot (a held one-shot instead waits for a poke until --expires deletes it unfired). Any other nonzero exit is a real failure and escalates per --on-output. Use 75 for "not yet — retry when conditions change" (a device coming online); keep gate ERRORS nonzero so a broken probe is loud instead of silently parked. Beyond the exit-code contract, cron has no native predicate-trigger semantics. --at runs once and deletes the row unless the run\'s disposition pauses it; --every runs each cadence. Output disposition (--on-output) records silently, escalates failures, or routes stdout to its --sink. Anchor a cron to delete it with a node; --cancel-on-wake instead deletes it when the anchor wakes. An unanchored recurring cron ends through --expires, explicit cancellation, or self-cancellation from its bash. Every run lands in a bounded per-cron run log (`cron show`); cwd, env, and profile are snapshotted at arm time, and --scope controls who lists and cancels it.',
+            model: 'A cron stores and daemon-runs arbitrary bash at its clock. Use ordinary bash for ordinary work; choose node:<id> for stdout as inbox information to an existing node (its disposition defaults to on-change), an existing node\'s lifecycle fresh-revive action in the bash for a clean re-check without inbox output, or spawn:<kind> to route each output-producing fire to a fresh self-finishing node (a managed child while its creator exists, otherwise a terminal parentless root). Per-fire fresh agent work belongs on the existing spawn:<kind> sink, not an independent resident-root birth. A gate is bash, at the top of the command. Exit 0 after deciding not to act and the occurrence is simply spent — right when the recurrence is your polling cadence. Exit 75 and the occurrence is OWED: the row is held, fires again the moment the daemon receives an eligibility poke from the host platform, and otherwise re-checks at its next natural slot (a held one-shot instead waits for a poke until --expires deletes it unfired). Any other nonzero exit is a real failure and escalates per --on-output. Use 75 for "not yet — retry when conditions change" (a device coming online); keep gate ERRORS nonzero so a broken probe is loud instead of silently parked. Beyond the exit-code contract, cron has no native predicate-trigger semantics. --at runs once and deletes the row unless the run\'s disposition pauses it; --every runs each cadence. Output disposition (--on-output) records silently, escalates failures, or routes stdout to its --sink. Anchor a cron to delete it with a node; --cancel-on-wake instead deletes it when the anchor wakes. An unanchored recurring cron ends through --expires, explicit cancellation, or self-cancellation from its bash. Every run lands in a bounded per-cron run log (`cron show`); cwd, env, and profile are snapshotted at arm time, and --scope controls who lists and cancels it.',
         },
         children: [addLeaf, listLeaf, showLeaf, runLeaf, pauseLeaf, resumeLeaf, cancelLeaf],
     });

package/dist/commands/node/create.js

@@ -12,6 +12,7 @@ import { stateBlock } from '../../core/help.js';
 import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
 import { inTmux } from '../../core/runtime/placement-tmux.js';
 import { openSpawnViewer } from '../surface/node/placement.js';
+import { resolve } from 'node:path';
 const YIELD_NUDGE_THRESHOLD = 100_000;
 const NODE_NEW_OUTPUT_SCHEMA_EFFECT = '--output-schema writes the accepted result to the node’s context/result.json and pushes it as the node’s final report.';
 const STD_CHILD_FOLLOW_UP = "Do not wait, poll, or duplicate this child's assignment in your own context — there is no result to await, stopping will not strand you, and duplicated work wastes the delegated context. You're auto-subscribed, so its finish wakes you on its own. Two moves only: do other independent work right now, or stop and end your turn — the wake brings you back.";
@@ -177,7 +178,8 @@ async function runNodeCreation(input) {
     }
     const kind = input['kind'];
     const mode = (input['mode'] ?? 'base');
-    const pinCwd = input['cwd']?.trim();
+    const pinCwdRaw = input['cwd']?.trim();
+    const pinCwd = pinCwdRaw !== undefined && pinCwdRaw !== '' ? resolve(pinCwdRaw) : undefined;
     const name = input['name'];
     const parent = input['parent'];
     const root = input['root'] === true;

package/dist/commands/node-worktree.js

@@ -71,16 +71,16 @@ const worktreeAbandon = defineLeaf({
 });
 const worktreeClose = defineLeaf({
     name: 'close',
-    description: 'land and close the current node-managed worktree',
-    whenToUse: 'you are inside the node that owns an open managed worktree and are ready to rebase it onto its recorded local base branch and fast-forward that base before finishing; its active checkout is retained for deferred cleanup',
+    description: 'land or safely close the current node-managed worktree',
+    whenToUse: 'you are inside the node that owns an open managed worktree and are ready to land its recorded branch into the local base, or to close a moved real branch whose already-delivered content can be safely preserved while its checkout is disposed later',
     help: {
         name: 'node worktree close',
-        summary: 'land and close the current node-managed worktree',
+        summary: 'land or safely close the current node-managed worktree',
         params: [],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The caller node id whose managed worktree was closed.' },
-            { name: 'branch', type: 'string', required: true, constraint: 'The worktree branch that was fast-forwarded into its recorded local base branch.' },
-            { name: 'landed_sha', type: 'string', required: true, constraint: 'The commit SHA that the recorded local base branch was fast-forwarded onto.' },
+            { name: 'branch', type: 'string', required: true, constraint: 'The branch whose delivered content is retained: fast-forwarded into the recorded local base in an ordinary close, or preserved unchanged when a moved real branch is authorized for disposal.' },
+            { name: 'landed_sha', type: 'string', required: true, constraint: 'The retained branch tip: fast-forwarded into the local base in an ordinary close, or proven already contained in the local base or its upstream before a moved real branch is authorized for disposal.' },
             { name: 'worktree_path', type: 'string', required: true, constraint: 'The managed worktree path whose cleanup is deferred until its caller exits.' },
             { name: 'worktree_removed', type: 'boolean', required: true, constraint: 'Always false for an active caller: its checkout remains intact rather than being removed beneath the node.' },
             { name: 'worktree_remove_error', type: 'string', required: true, constraint: 'The named deferred-cleanup state and safe manual follow-up after the caller exits.' },
@@ -89,7 +89,7 @@ const worktreeClose = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Rebases the worktree onto its recorded local base branch, fast-forwards that base onto it (never pushes to origin), marks the node-managed worktree closed with cleanup pending, and leaves the active caller checkout and branch intact.',
+            'Rebases the worktree onto its recorded local base branch and fast-forwards that base onto it (never pushes to origin), marking the node-managed worktree closed with cleanup pending and leaving the active caller checkout and branch intact. When the recorded branch is gone because ordinary work moved this checkout onto a real branch, and that branch\'s content is already contained in the recorded base, closes by authorizing the checkout\'s later removal instead of landing — preserving that branch rather than deleting it.',
         ],
     },
     run: async () => {
@@ -105,7 +105,7 @@ const worktreeClose = defineLeaf({
         const branch = String(r['branch'] ?? '');
         const sha = String(r['landed_sha'] ?? '');
         const path = String(r['worktree_path'] ?? '');
-        let base = `Managed worktree landed — its local base branch fast-forwarded to ${branch} at ${sha}.`;
+        let base = `Managed worktree closed — ${branch} at ${sha} is retained.`;
         const notes = [];
         if (r['worktree_removed'] === false) {
             notes.push(String(r['worktree_remove_error'] ?? `worktree checkout at ${path} could not be removed automatically.`));

package/dist/commands/pkg/plugin-manage.js

@@ -1,6 +1,6 @@
 import { envProfileId } from '../../shared/env.js';
 import { dirname, join, resolve, isAbsolute, relative, sep } from 'node:path';
-import { renameSync, writeFileSync } from 'node:fs';
+import { chmodSync, renameSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { defineLeaf } from '../../core/command.js';
 import { notFound, usage, general, network } from '../../core/errors.js';
@@ -282,6 +282,15 @@ function writeStagedBundle(stagingRoot, manifest, bundle) {
         ensureDir(resolve(target, '..'));
         writeFileSync(target, document.bytes);
     }
+    if (bundle.hooks !== undefined) {
+        writeFileSync(stagedPath(stagingRoot, 'hooks.json'), bundle.hooks.manifest);
+        for (const file of bundle.hooks.files) {
+            const target = stagedPath(stagingRoot, file.path);
+            ensureDir(resolve(target, '..'));
+            writeFileSync(target, file.bytes);
+        }
+        chmodSync(stagedPath(stagingRoot, 'hooks/dispatch'), 0o755);
+    }
 }
 async function validateStagedBundle(name, scope, root, scopeRootPath, manifest) {
     const memory = await assertPluginCandidateValid(manifest, root, scope, scopeRootPath, `${root}/.crouter-plugin/plugin.json`);
@@ -345,6 +354,7 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
         // later archive that no longer declares them is what retires them.
         ...(validated.bundle.page_components !== undefined ? { page_components: validated.bundle.page_components } : {}),
         ...(validated.bundle.memory_extensions !== undefined ? { memory_extensions: validated.bundle.memory_extensions } : {}),
+        ...(validated.bundle.hooks !== undefined ? { hooks: 'hooks.json', hookExecutable: 'hooks/dispatch' } : {}),
     };
     const tmpRoot = join(scopeRootPath, 'tmp');
     const staging = join(tmpRoot, `${name}.${process.pid}`);
@@ -390,7 +400,8 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
     const commands = await commandReport(name, scope);
     if (commands === undefined)
         throw general(`bundle plugin "${name}" has no staged command report`);
-    return { name, scope, path: root, transport: 'http', version, docs: validated.bundle.memory.length, kinds: Object.keys(validated.bundle.kinds ?? {}).length, pageComponents: (validated.bundle.page_components ?? []).length, commands, ...(memory !== undefined ? { memory } : {}) };
+    const hooks = await hookLifecycleReport(name, scope);
+    return { name, scope, path: root, transport: 'http', version, docs: validated.bundle.memory.length, kinds: Object.keys(validated.bundle.kinds ?? {}).length, pageComponents: (validated.bundle.page_components ?? []).length, commands, ...(hooks !== undefined ? { hooks } : {}), ...(memory !== undefined ? { memory } : {}) };
 }
 async function installHttpPlugin(name, endpoint, authEnv, scope) {
     const source = validateHttpInstall(name, endpoint, authEnv);
@@ -674,7 +685,7 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
     const sourceInstalled = isSourceInstalled(plugin);
     if (!sourceInstalled && plugin.manifest.bundle !== undefined) {
         const replaced = await replaceBundlePlugin(plugin.name, plugin.manifest.bundle, plugin.scope, { enable: plugin.enabled });
-        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, kinds: replaced.kinds, pageComponents: replaced.pageComponents, commands: replaced.commands, ...(replaced.memory !== undefined ? { memory: replaced.memory } : {}) };
+        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, kinds: replaced.kinds, pageComponents: replaced.pageComponents, commands: replaced.commands, ...(replaced.hooks !== undefined ? { hooks: replaced.hooks } : {}), ...(replaced.memory !== undefined ? { memory: replaced.memory } : {}) };
     }
     if (plugin.manifest.transport?.kind === 'http' && !sourceInstalled)
         rejectLegacyHttpPlugin(plugin.name);
@@ -729,16 +740,16 @@ export const pluginInstall = defineLeaf({
             { name: 'kinds', type: 'integer', required: false, constraint: 'Kind-registry entry count declared by an --endpoint archive\u2019s bundle.json.' },
             { name: 'pageComponents', type: 'integer', required: false, constraint: 'Page-component registration count declared by an --endpoint archive\u2019s bundle.json.' },
             { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest. {mounts: string[] (accepted top-level command names now live for the next invocation), issues: object[] (typed validation issues that rejected a contribution — {code, path?, message, received, expected, next})}. Validated statically; commands are never executed.' },
-            { name: 'hooks', type: 'object', required: false, constraint: 'Present only when the source plugin declares hooks. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], lifecycle?: {event, phase, op, description, effects}[], issues: object[], trust: string}. Command targets, lifecycle events, and replacement collisions are validated statically; hook executables are never run.' },
+            { name: 'hooks', type: 'object', required: false, constraint: 'Present only when the plugin declares hooks. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], lifecycle?: {event, phase, op, description, effects}[], issues: object[], trust: string}. Command targets, lifecycle events, and replacement collisions are validated statically; hook executables are never run.' },
             { name: 'warnings', type: 'string[]', required: false, constraint: 'Advisory missing PATH executable requirements declared by the installed plugin. The install still succeeds and leaves the plugin enabled.' },
             { name: 'memory', type: 'object', required: false, constraint: 'Present only when the plugin ships a memory store. {docs: integer (documents checked), migrated: string[] (store-relative documents rewritten to reach exact canonical identity), linkedSource?: string (the caller-owned directory converged in place, present only when the install keeps that directory as a live link)}.' },
         ],
         outputKind: 'object',
         effects: [
             'A ref install clones, links, or copies the plugin into the scope plugins directory and registers it with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.',
-            'An --endpoint install fetches and validates one authenticated uncompressed tar archive before writing. It replaces the complete plugin directory with synthesized provenance and invocation metadata, commands.json, memory docs, any kind-registry entries the bundle.json declares (they join the launch registry below this scope\u2019s own config.json kinds), and any page components it declares (they join the active page-component catalog alongside the user config entries); a fetch or validation failure preserves the prior package.',
+            'An --endpoint install fetches and validates one authenticated uncompressed tar archive before writing. It replaces the complete plugin directory with synthesized provenance and invocation metadata, commands.json, memory docs, and, when declared, hooks.json plus the hooks/ tree; it also copies any kind-registry entries the bundle.json declares (they join the launch registry below this scope\u2019s own config.json kinds), and any page components it declares (they join the active page-component catalog alongside the user config entries); a fetch or validation failure preserves the prior package.',
             'If the plugin declares a command manifest, its commands go live on the next crtr invocation. Exec commands run trusted local code only when explicitly invoked; HTTP commands call their declared endpoint only when explicitly invoked.',
-            'Source plugin command hooks go live on the next crtr invocation. They run implicitly with caller authority, may receive normalized inputs and after results, may block or replace declared targets, and may transmit received data. Lifecycle hooks run unprompted at every declared event before node launch and may transmit node identity and resolved paths. Hook executables are never run during install or update validation.',
+            'Plugin command hooks go live on the next crtr invocation. They run implicitly with caller authority, may receive normalized inputs and after results, may block or replace declared targets, and may transmit received data. Lifecycle hooks run unprompted at every declared event before node launch and may transmit node identity and resolved paths. Hook executables are never run during install or update validation.',
             'A plugin manifest `requires` declaration is checked against the PATH a node bash receives after install. Missing executables emit a warning with the declared install hint but never fail the install, disable the plugin, or remove its bare-binary contributions.',
             'Before activation the candidate\u2019s memory corpus is migrated to exact canonical identity and refused if it cannot mount. A staged candidate is migrated in staging and rolls back with the package; a local path or marketplace-relative source stays a live link, so its own directory is rewritten in place, keeps that rewrite whether or not the install completes, and is named as `memory.linkedSource`. A refused corpus writes nothing and installs nothing.',
         ],
@@ -895,7 +906,7 @@ export const pluginDisable = defineLeaf({
 export const pluginUpdate = defineLeaf({
     name: 'update',
     description: 'update installed plugin content',
-    whenToUse: 'refreshing one named plugin or all installed plugins: archive plugins replace commands and memory together, while source-installed plugins retain their source update behavior',
+    whenToUse: 'refreshing one named plugin or all installed plugins: archive plugins replace their complete package, while source-installed plugins retain their source update behavior',
     help: {
         name: 'pkg plugin update',
         summary: 'refresh one or all installed plugins',
@@ -904,7 +915,7 @@ export const pluginUpdate = defineLeaf({
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, kinds?, pageComponents?, commands?, hooks?, memory?, warnings?, error?}. memory is present for a plugin shipping a memory store and reports the same corpus migration install performs: {docs, migrated, linkedSource?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, kinds is the declared kind-registry entry count, and pageComponents is the declared page-component registration count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}. hooks is present for source hook plugins: {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], lifecycle?: {event, phase, op, description, effects}[], issues: object[], trust: string}; it is static and never executes hooks. warnings lists advisory PATH requirements that remain absent after update.' }
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, kinds?, pageComponents?, commands?, hooks?, memory?, warnings?, error?}. memory is present for a plugin shipping a memory store and reports the same corpus migration install performs: {docs, migrated, linkedSource?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, kinds is the declared kind-registry entry count, and pageComponents is the declared page-component registration count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}. hooks is present for plugins declaring hooks: {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], lifecycle?: {event, phase, op, description, effects}[], issues: object[], trust: string}; it is static and never executes hooks. warnings lists advisory PATH requirements that remain absent after update.' }
         ],
         outputKind: 'object',
         effects: [

package/dist/commands/push.js

@@ -71,7 +71,7 @@ function makePushLeaf(kind) {
                 ...(kind === 'final'
                     ? [
                         'Marks the node done (status + intent) server-side; its engine shuts down on next stop.',
-                        'When this node owns a managed worktree with zero commits ahead of its base and no uncommitted changes, the server auto-drops it instead of blocking on `node worktree close`; a worktree with real commits or real uncommitted changes still blocks with open_managed_worktree.',
+                        'When this node owns a clean managed worktree already contained in its local base, the server auto-drops it instead of blocking on `node worktree close`. A clean worktree whose exact branch tip is already on origin may also finalize while retaining its branch and checkout; uncommitted changes or a branch tip not on origin still block with open_managed_worktree.',
                     ]
                     : []),
             ],

package/dist/core/__tests__/helpers/harness.d.ts

@@ -10,6 +10,7 @@ export interface WaitOpts {
     intervalMs?: number;
     label?: string;
 }
+export declare function readLines(path: string): string[];
 export interface Injected {
     content: string;
     deliverAs?: string;

package/dist/core/__tests__/helpers/harness.js

@@ -123,6 +123,18 @@ async function waitFor(probe, opts = {}) {
         await new Promise((r) => setTimeout(r, intervalMs));
     }
 }
+export function readLines(path) {
+    try {
+        const content = readFileSync(path, 'utf8');
+        const lines = content.split('\n');
+        if (!content.endsWith('\n'))
+            lines.pop();
+        return lines.filter((l) => l.trim() !== '');
+    }
+    catch {
+        return [];
+    }
+}
 /** Thin wrapper: a headless-only harness (broker-hosted, paneless nodes). */
 export async function createHeadlessHarness(opts = {}) {
     return createHarness({ ...opts, headless: true });
@@ -377,16 +389,6 @@ export async function createHarness(opts = {}) {
             return [];
         }
     }
-    function readLines(path) {
-        try {
-            return readFileSync(path, 'utf8')
-                .split('\n')
-                .filter((l) => l.trim() !== '');
-        }
-        catch {
-            return [];
-        }
-    }
     function cli(nodeId, args) {
         const runtimeArgs = TSX_ESM === null ? [] : ['--import', TSX_ESM];
         const res = spawnSync(process.execPath, [...runtimeArgs, CLI_ENTRY, ...args], {

package/dist/core/__tests__/integration/worktree-land.test.js

@@ -440,8 +440,13 @@ test('close concludes a clean child after parent-first closure removes its check
         run(['commit', '-m', 'init'], repo);
         const parent = createManagedWorktree(repo, 'wt-parent-first-parent');
         createNode(node('wt-parent-first-parent', { cwd: parent.path, managed_worktree: parent }));
-        const child = createManagedWorktree(parent.path, 'wt-parent-first-child', parent.branch);
-        createNode(node('wt-parent-first-child', { cwd: child.path, managed_worktree: child }));
+        // Creation now refuses a managed worktree as its base (`managed_worktree_base`),
+        // so the child is cut from the real repository against the parent's BRANCH, and
+        // its record carries the parent checkout as `repo_root` — the exact legacy shape
+        // this case is about, still on disk for every record created before that guard.
+        const child = createManagedWorktree(repo, 'wt-parent-first-child', parent.branch);
+        const childRecord = { ...child, repo_root: parent.path };
+        createNode(node('wt-parent-first-child', { cwd: child.path, managed_worktree: childRecord }));
         assert.equal(gitSync(['rev-parse', 'HEAD'], child.path).stdout.trim(), child.base_sha, 'the child must be a clean zero-commit checkout at its recorded base');
         closeManagedWorktree('wt-parent-first-parent');
         run(['worktree', 'remove', parent.path], repo);

package/dist/core/__tests__/seam/broker-provider-retry.test.js

@@ -9,7 +9,7 @@ import { test, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { createHeadlessHarness } from '../helpers/harness.js';
+import { createHeadlessHarness, readLines } from '../helpers/harness.js';
 import { createAttachKit } from '../helpers/broker-clients.js';
 import { defaultModelLaddersConfig } from '../../../types.js';
 import { admitProviderRetryEpisode, readFault, readProviderRetryEpisode } from '../../runtime/fault.js';
@@ -63,21 +63,8 @@ function overflowOutcome(id) {
 // re-drive is a fresh session.prompt → emitTurn, which fires one 'agent_start';
 // counting them is the observable proof of how many times the turn was re-driven.
 function agentStartCount(id) {
-    try {
-        return readFileSync(join(h.home, 'nodes', id, 'fake-pi.events.jsonl'), 'utf8')
-            .split('\n')
-            .filter((l) => {
-            try {
-                return JSON.parse(l).event === 'agent_start';
-            }
-            catch {
-                return false;
-            }
-        }).length;
-    }
-    catch {
-        return 0;
-    }
+    return readLines(join(h.home, 'nodes', id, 'fake-pi.events.jsonl'))
+        .filter((line) => JSON.parse(line).event === 'agent_start').length;
 }
 async function crashAndRespawn(id, boots) {
     const pid = h.node(id)?.pi_pid;

package/dist/core/canvas/types.d.ts

@@ -106,6 +106,24 @@ export interface ManagedWorktree {
         blocked: string;
     };
     sweep?: ManagedWorktreeSweep;
+    /** Recorded ONLY by an explicit branch-moved `close` when the checkout's
+     *  actual branch has drifted from `branch` (its recorded `crtr/*` ref is
+     *  gone — ordinary PR work moved it there) but that branch's content was
+     *  proven, immediately before this was written, already contained in the
+     *  recorded base or its upstream. Authorizes ONLY the daemon sweep's later
+     *  checkout removal for this EXACT path + git common dir + observed branch
+     *  + observed SHA — the sweep re-verifies all four before acting and NEVER
+     *  deletes `observed_branch`, since it is not a `crtr/*` branch crouter
+     *  created. A mismatch on re-verification invalidates the authorization; a
+     *  fresh explicit close must re-establish it. Absent for every ordinary
+     *  managed worktree, and for `abandon`'s branch-moved path (which disposes
+     *  immediately instead of deferring, so it needs no persisted grant). */
+    disposal?: {
+        observed_branch: string;
+        observed_sha: string;
+        common_dir: string;
+        authorized: string;
+    };
 }
 /** Immutable companion provenance. The origin session/leaf/model coordinates
  *  remain canonical in the review row rather than being duplicated into node

package/dist/core/command-plugins/bundle.d.ts

@@ -32,6 +32,13 @@ export interface ValidatedBundle {
         path: string;
         bytes: Uint8Array;
     }>;
+    hooks?: {
+        manifest: Uint8Array;
+        files: ReadonlyArray<{
+            path: string;
+            bytes: Uint8Array;
+        }>;
+    };
 }
 export interface PluginBundleValidation {
     bundle?: ValidatedBundle;

package/dist/core/command-plugins/bundle.js

@@ -38,13 +38,13 @@ function validateMemberName(path, type) {
 }
 function validateMemberShape(path, type) {
     if (type === 'file') {
-        if (path === 'bundle.json' || path === 'commands.json' || (path.startsWith('memory/') && path.endsWith('.md')))
+        if (path === 'bundle.json' || path === 'commands.json' || path === 'hooks.json' || (path.startsWith('memory/') && path.endsWith('.md')) || path.startsWith('hooks/'))
             return undefined;
-        return bundleInvalid('bundle contains an unsupported file member', path, 'bundle.json, commands.json, or memory/**/*.md', 'Remove unsupported members from the archive.', path);
+        return bundleInvalid('bundle contains an unsupported file member', path, 'bundle.json, commands.json, hooks.json, memory/**/*.md, or hooks/**', 'Remove unsupported members from the archive.', path);
     }
-    if (path === 'memory' || path.startsWith('memory/'))
+    if (path === 'memory' || path.startsWith('memory/') || path === 'hooks' || path.startsWith('hooks/'))
         return undefined;
-    return bundleInvalid('bundle contains an unsupported directory member', path, 'memory or a directory below memory/', 'Remove unsupported directory members from the archive.', path);
+    return bundleInvalid('bundle contains an unsupported directory member', path, 'memory or hooks, or a directory below either subtree', 'Remove unsupported directory members from the archive.', path);
 }
 /** A member path as it will exist on disk: directories carry no trailing slash. */
 function materializedPath(member) {
@@ -221,6 +221,14 @@ export async function validatePluginBundle(archive, options) {
             issues: [bundleInvalid('bundle must contain exactly one bundle.json and one commands.json regular file', `bundle.json=${bundle !== undefined}, commands.json=${commands !== undefined}`, 'one regular bundle.json and one regular commands.json member', 'Add the required metadata members to the archive.')],
         };
     }
+    const hookManifest = parsed.members.find((member) => member.path === 'hooks.json' && member.type === 'file');
+    const hookFiles = parsed.members.filter((member) => member.type === 'file' && member.path.startsWith('hooks/'));
+    const carriesHooks = hookManifest !== undefined || parsed.members.some((member) => member.path === 'hooks' || member.path.startsWith('hooks/'));
+    if (carriesHooks && (hookManifest === undefined || !hookFiles.some((member) => member.path === 'hooks/dispatch'))) {
+        return {
+            issues: [bundleInvalid('bundle hook payload must contain both hooks.json and hooks/dispatch regular files', `hooks.json=${hookManifest !== undefined}, hooks/dispatch=${hookFiles.some((member) => member.path === 'hooks/dispatch')}`, 'both hooks.json and hooks/dispatch regular files', 'Add both required hook members or remove the hook payload.')],
+        };
+    }
     const metadata = parseBundleMetadata(bundle.bytes);
     if (metadata.issue !== undefined)
         return { issues: [metadata.issue] };
@@ -241,6 +249,12 @@ export async function validatePluginBundle(archive, options) {
             memory: parsed.members
                 .filter((member) => member.type === 'file' && member.path.startsWith('memory/'))
                 .map((member) => ({ path: member.path, bytes: member.bytes })),
+            ...(hookManifest !== undefined ? {
+                hooks: {
+                    manifest: hookManifest.bytes,
+                    files: hookFiles.map((member) => ({ path: member.path, bytes: member.bytes })),
+                },
+            } : {}),
         },
         issues: [],
     };

package/dist/core/git.d.ts

@@ -11,7 +11,11 @@ export interface GitSyncOptions {
     timeoutMs?: number;
 }
 export declare function gitSync(args: string[], cwd?: string, input?: string, options?: GitSyncOptions): GitResult;
-export declare function gitAsync(args: string[], cwd?: string, input?: string): Promise<GitResult>;
+export interface GitAsyncOptions {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function gitAsync(args: string[], cwd?: string, input?: string, options?: GitAsyncOptions): Promise<GitResult>;
 export declare function clone(url: string, dest: string, opts?: {
     ref?: string;
     depth?: number;

package/dist/core/git.js

@@ -10,22 +10,36 @@ export function gitSync(args, cwd, input, options = {}) {
     const timedOut = res.error?.code === 'ETIMEDOUT';
     return { status, stdout, stderr, ...(completed ? {} : { executionFailed: true }), ...(processError === undefined ? {} : { processError }), ...(timedOut ? { timedOut: true } : {}) };
 }
-export async function gitAsync(args, cwd, input) {
+export async function gitAsync(args, cwd, input, options = {}) {
     return new Promise((resolve) => {
-        const child = spawn('git', args, { cwd });
+        const child = spawn('git', args, { cwd, ...(options.env === undefined ? {} : { env: options.env }) });
         if (input === undefined)
             child.stdin.end();
         else
             child.stdin.end(input);
         let stdout = '';
         let stderr = '';
+        let timedOut = false;
+        let settled = false;
+        const timer = options.timeoutMs === undefined ? undefined : setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, options.timeoutMs);
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            resolve(result);
+        };
         child.stdout.on('data', (d) => (stdout += d.toString()));
         child.stderr.on('data', (d) => (stderr += d.toString()));
         child.on('close', (status) => {
             const code = typeof status === 'number' ? status : 1;
-            resolve({ status: code, stdout, stderr });
+            settle({ status: code, stdout, stderr, ...(timedOut ? { timedOut: true, executionFailed: true } : {}) });
         });
-        child.on('error', (e) => resolve({ status: 1, stdout: '', stderr: String(e) }));
+        child.on('error', (e) => settle({ status: 1, stdout: '', stderr: String(e), executionFailed: true, processError: String(e) }));
     });
 }
 export function clone(url, dest, opts = {}) {

package/dist/core/runtime/spawn.d.ts

@@ -62,6 +62,8 @@ export interface SpawnChildOpts {
     worktree?: boolean;
     /** Local branch the managed worktree is cut from and later landed onto. */
     worktreeBase?: string;
+    /** Invocation-selected repository from which to cut a managed worktree. */
+    worktreeCwd?: string;
     /** Preallocated node id, used when a managed worktree must be named before birth. */
     nodeId?: string;
     /** Hidden ambient "current situation" text — NOT the visible prompt/body.

package/dist/core/runtime/spawn.js

@@ -251,7 +251,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
     let spawnCwd = opts.cwd;
     try {
         if (wantsWorktree) {
-            managedWorktree = createManagedWorktree(opts.cwd, nodeId, opts.worktreeBase);
+            managedWorktree = createManagedWorktree(opts.worktreeCwd ?? opts.cwd, nodeId, opts.worktreeBase);
             spawnCwd = managedWorktree.path;
         }
         // Spine: a managed child reports up to its spawner (has a manager); an

package/dist/core/worktree-sweep.js

@@ -336,7 +336,7 @@ export async function reconcileManagedWorktree(nodeId, guard, now = Date.now())
         return { status: 'skipped', reason: 'already_reconciled' };
     const cwd = existsSync(wt.path) ? wt.path : wt.repo_root;
     if (!existsSync(cwd)) {
-        return finish(nodeId, wt, { status: 'refused', reason: 'repo_unavailable', detail: `neither the managed checkout (${wt.path}) nor its repository root (${wt.repo_root}) is present` }, { base: null, branch: null, checkout: null }, now, guard);
+        return persistComplete(nodeId, wt, guard);
     }
     const commonDir = await commonGitDirAsync(cwd);
     if (commonDir === null) {
@@ -423,9 +423,15 @@ async function reconcilePresentCheckout(nodeId, wt, guard) {
     const list = await gitAsync(['worktree', 'list', '--porcelain'], wt.path);
     if (list.status !== 0)
         return { status: 'failed', reason: 'worktree_list_failed', detail: detailOf(list) };
-    const registeredPath = registeredCheckoutPath(list.stdout, wt.path, wt.branch);
+    // An explicit `close` already proved a branch-moved checkout's identity and
+    // authorized its later disposal for THIS exact branch — never adopted here.
+    // Only the recorded authorization changes which branch this pass expects;
+    // everything else below is re-verified exactly as for an ordinary record.
+    const disposal = wt.disposal;
+    const expectedBranch = disposal?.observed_branch ?? wt.branch;
+    const registeredPath = registeredCheckoutPath(list.stdout, wt.path, expectedBranch);
     if (registeredPath === null) {
-        return { status: 'refused', reason: 'not_registered', detail: `${wt.path} is not registered to refs/heads/${wt.branch}; crtr will not act on a path it cannot prove it owns` };
+        return { status: 'refused', reason: 'not_registered', detail: `${wt.path} is not registered to refs/heads/${expectedBranch}; crtr will not act on a path it cannot prove it owns` };
     }
     const main = mainWorktreePath(list.stdout);
     if (main === null || samePath(main, registeredPath) || !existsSync(main)) {
@@ -439,8 +445,8 @@ async function reconcilePresentCheckout(nodeId, wt, guard) {
     const head = await gitAsync(['rev-parse', '--abbrev-ref', 'HEAD'], wt.path);
     if (head.status !== 0)
         return { status: 'failed', reason: 'branch_check_failed', detail: detailOf(head) };
-    if (head.stdout.trim() !== wt.branch) {
-        return { status: 'refused', reason: 'wrong_branch', detail: `expected ${wt.branch}, found ${head.stdout.trim() === 'HEAD' ? 'detached HEAD' : head.stdout.trim()}` };
+    if (head.stdout.trim() !== expectedBranch) {
+        return { status: 'refused', reason: 'wrong_branch', detail: `expected ${expectedBranch}, found ${head.stdout.trim() === 'HEAD' ? 'detached HEAD' : head.stdout.trim()}` };
     }
     // Uncommitted work blocks removal unconditionally. No containment proof
     // overrides this: those reason about committed content, and nothing here has
@@ -454,6 +460,23 @@ async function reconcilePresentCheckout(nodeId, wt, guard) {
     let branchSha = await revParseRef(wt.path, 'HEAD');
     if (branchSha === null)
         return { status: 'failed', reason: 'head_unreadable', detail: `could not read HEAD in ${wt.path}` };
+    if (disposal !== undefined) {
+        // Re-verify the exact identity `close` authorized before mutating anything.
+        // A mismatch invalidates the authorization instead of adopting whatever is
+        // observed now — only the explicit command that wrote it may refresh it.
+        const commonDir = await commonGitDirAsync(wt.path);
+        if (commonDir !== disposal.common_dir || branchSha !== disposal.observed_sha) {
+            return { status: 'refused', reason: 'disposal_authorization_stale', detail: `${wt.path} changed since \`close\` authorized its disposal; rerun \`crtr node worktree close\` from that node to re-authorize, or ask the user with \`crtr human send\`` };
+        }
+        if (!guard.stillEligible())
+            return NODE_REVIVED;
+        const removed = await gitAsync(['worktree', 'remove', registeredPath], main);
+        if (removed.status !== 0)
+            return { status: 'refused', reason: 'worktree_remove_failed', detail: detailOf(removed) };
+        // `disposal.observed_branch` is not a `crtr/*` branch crouter created — it
+        // is preserved, never deleted, unlike the ordinary path below.
+        return persistComplete(nodeId, wt, guard);
+    }
     let proof = await proveContained(wt.path, wt, branchSha);
     let stash;
     if (proof === null && wt.land_intent !== undefined) {

package/dist/core/worktree.d.ts

@@ -115,17 +115,6 @@ export interface AutoDroppedWorktree {
  * explicit close: removal and branch deletion are deferred until that owner
  * has exited. */
 export declare function autoDropCleanManagedWorktreeLocked(nodeId: string, wt: ManagedWorktree, proof: CleanEmptyProof): AutoDroppedWorktree | null;
-/** `push final`'s escape hatch: a managed worktree that has
- *  nothing to land is auto-dropped instead of blocking on an explicit
- *  `node worktree close` — one the caller may have been told NOT to run
- *  because a manager already landed the same change another way, or
- *  that never had anything to close in the first place (a read-only
- *  review node). Returns null and changes nothing when the worktree is not
- *  PROVABLY empty-and-clean by `proveCleanEmptyManagedWorktree`, OR when a
- *  concurrent mutation invalidates that proof before the record is closed
- *  (see `autoDropCleanManagedWorktreeLocked`); the caller's existing
- *  `open_managed_worktree` guard then still applies unchanged — real
- *  commits, real uncommitted changes, and a lost race all require the
- *  explicit path. */
+export declare function branchIsPushedAtCurrentTip(wt: ManagedWorktree): Promise<boolean>;
 export declare function autoDropCleanManagedWorktree(nodeId: string): AutoDroppedWorktree | null;
 export {};