@north-light/crouter 0.3.258 → 0.3.260

package/dist/core/help.d.ts

@@ -198,6 +198,11 @@ export interface BranchHelp {
     /** Parent-level listing assembled by defineBranch from the actual child defs.
      *  renderBranch reads this; never author it by hand. */
     listing?: ListingChild[];
+    /** A rejected repository fragment is visible only on its owning extensible branch. */
+    extensionIssue?: {
+        fragment: string;
+        message: string;
+    };
 }
 /** Viewer-only hint about how a leaf's result should preview in the attach
  *  viewer's chat — never part of `-h` output and never reaches agent-facing

package/dist/core/help.js

@@ -161,6 +161,9 @@ export function renderBranch(h) {
             lines.push('');
         lines.push(`<subcommand name="${c.name}" description="${attr(c.description)}" whenToUse="${attr(c.whenToUse)}"${subs}/>`);
     }
+    if (h.extensionIssue !== undefined) {
+        lines.push(`<extension-issue fragment="${attr(h.extensionIssue.fragment)}">This repository's contributed commands were rejected: ${h.extensionIssue.message}. Run \`crtr sys doctor\` for the full report.</extension-issue>`);
+    }
     lines.push('</command>');
     return lines.join('\n');
 }

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

@@ -57,6 +57,18 @@ export interface ReviveResult {
     outcome: ReviveOutcome;
 }
 export type ReviveOutcome = 'launched' | 'already-live' | 'frozen';
+export type AttachReviveDecision = {
+    parked: true;
+} | {
+    parked: false;
+    result: ReviveResult;
+};
+interface ReviveOptions {
+    resume: boolean;
+    capacity: ReviveCapacityPolicy;
+    wakeReason?: ReviveWakeReason;
+    recovery?: boolean;
+}
 /** What a caller wants when the broker cap is full. `freeze` suits a caller
  *  whose reason to run survives waiting (durable mail, a cron sink, a recovery
  *  respawn): the row is marked frozen and the tick relaunches it when a slot
@@ -75,9 +87,10 @@ export type ReviveCapacityPolicy = 'freeze' | 'refuse';
  *  Throws if the node does not exist. All other failures propagate as-is —
  *  callers (daemon, command) decide how to handle.
  */
-export declare function reviveNode(nodeId: string, opts: {
-    resume: boolean;
-    capacity: ReviveCapacityPolicy;
-    wakeReason?: ReviveWakeReason;
-    recovery?: boolean;
-}): ReviveResult;
+export declare function reviveNode(nodeId: string, opts: ReviveOptions): ReviveResult;
+/** The attach-specific entry to the revive boundary. A focus viewer may decline
+ * to wake an exact parked resident while preserving the ordinary activating
+ * attach default. The fleet check and parked decision are synchronous with the
+ * launch below, so an already-running broker wins before dormancy is observed. */
+export declare function decideAttachRevive(nodeId: string, opts: ReviveOptions, wakeParked: boolean): AttachReviveDecision;
+export {};

package/dist/core/runtime/revive.js

@@ -140,6 +140,19 @@ export function hasFreshGroundState(nodeId) {
  *  callers (daemon, command) decide how to handle.
  */
 export function reviveNode(nodeId, opts) {
+    const decision = decideRevive(nodeId, opts, true);
+    if (decision.parked)
+        throw new Error(`reviveNode: internal parked decision for activating revive ${nodeId}`);
+    return decision.result;
+}
+/** The attach-specific entry to the revive boundary. A focus viewer may decline
+ * to wake an exact parked resident while preserving the ordinary activating
+ * attach default. The fleet check and parked decision are synchronous with the
+ * launch below, so an already-running broker wins before dormancy is observed. */
+export function decideAttachRevive(nodeId, opts, wakeParked) {
+    return decideRevive(nodeId, opts, wakeParked);
+}
+function decideRevive(nodeId, opts, wakeParked) {
     let meta = getNode(nodeId);
     if (meta === null) {
         throw new Error(`reviveNode: unknown node ${nodeId}`);
@@ -170,12 +183,21 @@ export function reviveNode(nodeId, opts) {
         // so this is a no-op for a row that is already active.
         transition(nodeId, meta.intent === 'refresh' ? 'refresh-launch' : 'revive');
         return {
-            window: null,
-            session: meta.tmux_session ?? null,
-            resumed: false,
-            outcome: 'already-live',
+            parked: false,
+            result: {
+                window: null,
+                session: meta.tmux_session ?? null,
+                resumed: false,
+                outcome: 'already-live',
+            },
         };
     }
+    // Focus may establish a viewport without establishing an engine. This exact
+    // row has no final latch and no fleet owner; returning before reservation is
+    // what keeps lifecycle, cycle count, pid, inbox cursor, and session untouched.
+    if (!wakeParked && meta.lifecycle === 'resident' && isParked(meta)) {
+        return { parked: true };
+    }
     // The cap, consulted BEFORE any mutation below: a node that cannot get a
     // broker must not have its cycle counter bumped, its session identity
     // cleared, or its bearings drained on the way to being turned away.
@@ -203,14 +225,17 @@ export function reviveNode(nodeId, opts) {
             });
         }
         return {
-            window: null,
-            session: meta.tmux_session ?? null,
-            resumed: false,
-            outcome: 'frozen',
+            parked: false,
+            result: {
+                window: null,
+                session: meta.tmux_session ?? null,
+                resumed: false,
+                outcome: 'frozen',
+            },
         };
     }
     try {
-        return launchRevive(nodeId, meta, opts);
+        return { parked: false, result: launchRevive(nodeId, meta, opts) };
     }
     finally {
         // The slot is either consumed by the fleet registration inside `launch`

package/dist/daemon/api/handlers/attach.js

@@ -6,53 +6,57 @@
 //
 // `{id}` is the target node being attached to.
 import { getNode } from '../../../core/canvas/canvas.js';
-import { reviveNode } from '../../../core/runtime/revive.js';
+import { decideAttachRevive } from '../../../core/runtime/revive.js';
 import { viewSocketPath } from '../../../core/canvas/paths.js';
 import { waitForBrokerViewSocket } from '../../../core/runtime/placement-tmux.js';
 import { notFound, usage } from '../../../core/errors.js';
-/** Validate + narrow the attach-ensure body (both fields optional, default true). */
+/** Validate + narrow the attach-ensure body (all fields optional, default true). */
 function parseAttachBody(body) {
     if (body === undefined || body === null)
-        return { resume: true, revive: true };
+        return { resume: true, revive: true, wakeParked: true };
     if (typeof body !== 'object') {
-        throw usage('attach body must be a JSON object { resume?, revive? }');
+        throw usage('attach body must be a JSON object { resume?, revive?, wakeParked? }');
     }
     const resume = body.resume;
     const revive = body.revive;
+    const wakeParked = body.wakeParked;
     if (resume !== undefined && typeof resume !== 'boolean')
         throw usage('resume must be a boolean');
     if (revive !== undefined && typeof revive !== 'boolean')
         throw usage('revive must be a boolean');
-    return { resume: resume ?? true, revive: revive ?? true };
+    if (wakeParked !== undefined && typeof wakeParked !== 'boolean')
+        throw usage('wakeParked must be a boolean');
+    return { resume: resume ?? true, revive: revive ?? true, wakeParked: wakeParked ?? true };
 }
 async function handleAttach(ctx) {
     const id = ctx.params['id'];
     if (getNode(id) === null)
         throw notFound(`unknown node: ${id}`, { received: id });
-    const { resume, revive } = parseAttachBody(ctx.body);
+    const { resume, revive, wakeParked } = parseAttachBody(ctx.body);
     let revived = false;
     let resumed = false;
+    let parked = false;
     if (revive) {
-        // reviveNode is the ONLY sanctioned broker launcher; a double-revive of a
-        // live node is an idempotent no-op (no `launch` handle) — `revived` reflects
-        // whether a fresh engine actually started.
-        // An attach has a viewer waiting on a socket that only a live broker
-        // publishes, so there is nothing to wait for it with: refuse at the cap and
-        // let the caller see why, rather than freezing and returning a `revived`
-        // that never becomes true.
-        const result = reviveNode(id, { resume, capacity: 'refuse' });
-        revived = result.launch !== undefined;
-        resumed = result.resumed;
-        // If we launched, let the broker publish its view socket so the local
-        // viewer's immediate connect finds it (bounded wait; best-effort).
-        if (revived)
-            await waitForBrokerViewSocket(id);
+        // This decision and reviveNode's fleet guard share one synchronous launch
+        // boundary. Focus may stop at an exact parked resident; ordinary/direct
+        // attach keeps wakeParked=true and preserves attach-implies-revive.
+        const decision = decideAttachRevive(id, { resume, capacity: 'refuse' }, wakeParked);
+        parked = decision.parked;
+        if (!decision.parked) {
+            revived = decision.result.launch !== undefined;
+            resumed = decision.result.resumed;
+            // If we launched, let the broker publish its view socket so the local
+            // viewer's immediate connect finds it (bounded wait; best-effort).
+            if (revived)
+                await waitForBrokerViewSocket(id);
+        }
     }
     const body = {
         node_id: id,
         socket_path: viewSocketPath(id),
         revived,
         resumed,
+        parked,
     };
     return { status: 200, body };
 }

package/dist/daemon/api/handlers/nodes.js

@@ -366,8 +366,15 @@ async function handleSnapshot(ctx) {
         node_id: id,
         snapshot: {
             messages: read.snapshot.messages,
+            ...(read.snapshot.messageIds === undefined ? {} : { messageIds: read.snapshot.messageIds }),
             stats: read.snapshot.stats,
             state: read.snapshot.state,
+            display: read.snapshot.display,
+            ...(read.snapshot.queued === undefined ? {} : { queued: read.snapshot.queued }),
+            ...(read.snapshot.toolGroupSummaries === undefined
+                ? {}
+                : { toolGroupSummaries: read.snapshot.toolGroupSummaries }),
+            ...(read.snapshot.workingActivity === undefined ? {} : { workingActivity: read.snapshot.workingActivity }),
         },
         commands: read.commands.map((c) => ({ name: c.name, description: c.description, source: c.source })),
         captured_at: nowIso(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.258",
+  "version": "0.3.260",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.258",
+  "version": "0.3.260",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.258",
+      "version": "0.3.260",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {