@north-light/crouter 0.3.217 → 0.3.219

package/dist/api/client.d.ts

@@ -78,6 +78,8 @@ export declare class CrtrClient {
      *  settled result. */
     restartDaemon(): Promise<DaemonRestartDTO>;
     createNode(req: CreateNodeRequest): Promise<NodeDetailDTO>;
+    /** List canvas nodes with composable row filters. `include: 'activity'` adds
+     * latest/canonical reports and pending-human counts in the same response. */
     listNodes(q?: ListNodesQuery): Promise<NodeSummaryDTO[]>;
     getNode(id: string): Promise<NodeDetailDTO>;
     listBashJobs(id: string): Promise<BashJobStatusDTO[]>;
@@ -197,8 +199,9 @@ export declare class CrtrClient {
     listHumanInbox(): Promise<InboxListDTO>;
     /** Read one page ticket by its opaque ticket id (pending, resolved, or canceled). */
     getHumanInboxPage(ticketId: InboxTicketIdDTO): Promise<InboxPageDTO>;
-    /** All page tickets raised by one node, oldest first (pending, resolved, or canceled). */
-    getInboxHistory(nodeId: string): Promise<InboxPageHistoryDTO>;
+    /** All page tickets, oldest first (pending, resolved, or canceled) —
+     *  home-wide, or narrowed to one raising node when `nodeId` is given. */
+    getInboxHistory(nodeId?: string): Promise<InboxPageHistoryDTO>;
     /** Submit responses for a page ticket. Single-assignment server-side: a competing
      *  resolution races to `ticket_already_resolved`. */
     respondHumanInboxPage(ticketId: InboxTicketIdDTO, request: RespondInboxPageRequest): Promise<PageTicketResultDTO>;

package/dist/api/client.js

@@ -92,6 +92,8 @@ export class CrtrClient {
     createNode(req) {
         return this.request('POST', routes.nodes(), req);
     }
+    /** List canvas nodes with composable row filters. `include: 'activity'` adds
+     * latest/canonical reports and pending-human counts in the same response. */
     listNodes(q) {
         return this.request('GET', withQuery(routes.nodes(), q));
     }
@@ -386,8 +388,12 @@ export class CrtrClient {
     getHumanInboxPage(ticketId) {
         return this.request('GET', routes.humanInboxTicket(this.ticketId(ticketId)));
     }
-    /** All page tickets raised by one node, oldest first (pending, resolved, or canceled). */
+    /** All page tickets, oldest first (pending, resolved, or canceled) —
+     *  home-wide, or narrowed to one raising node when `nodeId` is given. */
     getInboxHistory(nodeId) {
+        if (nodeId === undefined) {
+            return this.request('GET', routes.humanInbox() + '/history');
+        }
         if (typeof nodeId !== 'string' || nodeId === '') {
             throw new TypeError(`invalid node id: ${JSON.stringify(nodeId)}`);
         }

package/dist/api/dto/canvas.d.ts

@@ -147,6 +147,10 @@ export interface SnapshotNodeDTO {
     lifecycle?: string;
     status: NodeStatusDTO;
     cwd: string;
+    /** The profile this node runs under; null for a historical no-profile row.
+     *  Carried here because it is the only field that says WHOSE work a node is —
+     *  a snapshot consumer grouping nodes by agent has nothing else to key on. */
+    profile_id: string | null;
     parent: NodeIdDTO | null;
     created: IsoTime;
     host_kind: string;
@@ -161,6 +165,11 @@ export interface SnapshotNodeDTO {
      *  as a loose object to keep this DTO free of a `core` type import. */
     hanging: Record<string, unknown> | null;
     viewed: boolean;
+    /** Basename of the node's final report, or null when it never pushed one.
+     *  Presence — not `status === 'done'` — is what distinguishes finished work
+     *  from clean parking. */
+    final_report: string | null;
+    finalized_at: IsoTime | null;
 }
 /** `GET /v1/canvas/snapshot` result — the machine-readable browser canvas
  *  roster (`crtr canvas snapshot`). Distinct from the per-node `NodeSnapshotDTO`

package/dist/api/dto/nodes.d.ts

@@ -1,4 +1,5 @@
 import type { Cursor, ExitIntentDTO, IsoTime, LifecycleDTO, ModeDTO, NodeIdDTO, NodeStatusDTO } from './common.js';
+import type { ReportDTO } from './reports.js';
 /** `GET /v1/nodes/{id}/subject` — the node-config subject substrate gate
  *  predicates evaluate against. Mirrors `NodeConfigSubject`; this narrow
  *  endpoint exists so a CLI process (the `memory read` leaf) can gate-check
@@ -79,8 +80,19 @@ export interface NodeSummaryDTO {
     window: string | null;
     tmux_session: string | null;
     pane: string | null;
+    /** Basename of the canonical final report, or null when this node has not finalized. */
     final_report: string | null;
     finalized_at: IsoTime | null;
+    /** Present only when requested with `include=activity`. */
+    activity?: NodeActivityDTO;
+}
+/** Optional per-node activity payload for a list response. Reports are the
+ * stored push entries, newest first; `final_report` follows the row's canonical
+ * final-report basename rather than merely selecting the newest final-tier file. */
+export interface NodeActivityDTO {
+    latest_report: ReportDTO | null;
+    final_report: ReportDTO | null;
+    pending_human_count: number;
 }
 /** The spine + subscription edges of a node (absorbs `managers`/`paths` reads). */
 export interface NodeEdgesDTO {
@@ -166,15 +178,29 @@ export interface NodeDetailDTO extends NodeSummaryDTO {
     roadmap_path?: string;
     goal_path?: string;
 }
-/** `GET /v1/nodes` query filters. */
+/** `GET /v1/nodes` optional payloads. */
+export type NodeListInclude = 'activity';
+/** `GET /v1/nodes` query filters. Filters compose; `parent` selects direct
+ * children while `under` selects a whole subtree. */
 export interface ListNodesQuery {
     status?: NodeStatusDTO;
+    lifecycle?: LifecycleDTO;
     kind?: string;
     mode?: ModeDTO;
+    /** Exact profile id. */
+    profile_id?: string;
+    /** Profile-id prefix, for callers that own a namespaced profile family. */
+    profile_prefix?: string;
+    /** Restrict to direct children of this node. Mutually exclusive with `top_level`. */
+    parent?: NodeIdDTO;
+    /** Restrict to nodes without a parent. */
+    top_level?: boolean;
     /** Restrict to the subtree under this node. */
     under?: NodeIdDTO;
     /** Only nodes with a dangling/hanging manager edge. */
     hanging?: boolean;
+    /** Opt into richer per-node payloads that require filesystem reads. */
+    include?: NodeListInclude;
 }
 /** `GET /v1/nodes/{id}/snapshot` — the node's reconstructed broker snapshot
  *  (`readNodeSnapshot`): the message log, aggregate stats, and current engine

package/dist/builtin-memory/04-base-worker.md

@@ -4,6 +4,8 @@ when-and-why-to-read: When a node runs in base mode, this preference should be r
 gate: {mode: base}
 rationale: >-
   A base security reviewer handed its entire assignment to another base security reviewer, which repeated the move through a 35-node chain in under five minutes. The universal prompt had said to delegate any self-contained work while no base-mode layer told sub-kinds to work hands-on; exact sub-kind gating also meant plan/reviewers/security did not inherit plan/00-base.
+
+  The scout section exists because the kernel's "understand before you delegate" line is orchestrator-gated, so base workers had no counterweight to mapping unfamiliar code in their own window: they spent a strong-model context on read-only exploration and yielded before the real work. Explore defaults to a light tier, which is the mechanism the section leans on.
 surfaces:
   - on: boot
     at: content
@@ -13,4 +15,8 @@ surfaces:
 
 Own the task you were given and complete it yourself in this window. Your scarce resource is task completion, not preserving your context for steering.
 
-Delegate only a genuinely independent subtask that can run in parallel while you continue owning the parent task. Each child gets a bounded outcome distinct from your whole assignment; passing the same task to another base node creates recursion instead of progress. When the goal will not fit one window but is still yours to build, `crtr node yield` and continue hands-on in a fresh window. Become an orchestrator only when enough independent work can run in parallel that coordinating and integrating children should replace hands-on execution as your primary job; use `crtr node yield --promote` to refresh too, or `crtr node promote` to switch without refreshing.
+Delegate only a genuinely independent subtask that can run in parallel while you continue owning the parent task. Each child gets a bounded outcome distinct from your whole assignment; passing the same task to another base node creates recursion instead of progress.
+
+One delegation fits that rule before the work even starts: when the task sits in code you cannot yet map — you don't know which files it touches or which constraints hold — spawn an `explore` scout to chart it. A current-state map is a bounded outcome distinct from your assignment, and explore runs on a light model tier, so the `file:line` map it wakes you with spends the scout's cheap window instead of the context you need for the work itself. Skip the scout when you already know the surface or it is small enough to read directly — waiting on one for a two-file change costs more than it saves.
+
+When the goal will not fit one window but is still yours to build, `crtr node yield` and continue hands-on in a fresh window. Become an orchestrator only when enough independent work can run in parallel that coordinating and integrating children should replace hands-on execution as your primary job; use `crtr node yield --promote` to refresh too, or `crtr node promote` to switch without refreshing.

package/dist/builtin-memory/internal/plugins.md

@@ -69,6 +69,73 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 | `bin` | optional | Bare-callable executables the plugin ships, as `{"<bare-name>": "<plugin-relative path>"}`. Each becomes callable by bare name from any node's bash — no `crtr` command, no protocol. See [Bare binaries on the node PATH](#bare-binaries-on-the-node-path). |
 | `requires` | optional | Advisory external executables the plugin needs, as `{"<bare-name>": "one-line install hint"}`. crouter never installs them or disables the plugin when absent: install warns and Doctor reports the hint. See [External executable requirements](#external-executable-requirements). |
 | `kinds` | optional | Kind-registry contributions, keyed by full kind string — the same rule a scope `config.json` `kinds` block follows: each entry is any subset of `KindConfig` fields (`whenToUse`, `model`, `orchestratorModel`, `tools`, `extensions`, `availableTo`). It field-merges over a kind a lower layer already defines — `whenToUse` included, so overriding just the spawn guidance never strips the kind's model tier — and defines a new kind when none does (then `whenToUse` is required). See [Plugin kinds](#plugin-kinds). |
+| `memory_extensions` | optional | Typed plugin-owned metadata declarations for memory document frontmatter. The manifest name owns the namespace; see [Plugin-owned memory metadata](#plugin-owned-memory-metadata). |
+
+## Plugin-owned memory metadata
+
+A plugin can declare typed metadata that crouter validates and carries without teaching the core memory schema what the metadata means. This keeps routing, loading, listings, and agent delivery governed only by core frontmatter while a plugin's own product surfaces interpret its fields.
+
+Declare fields in the optional `memory_extensions` manifest addendum. The manifest's exact `name`, not a configurable declaration value or installation path, is always the namespace:
+
+```json
+{
+  "name": "northlight",
+  "memory_extensions": {
+    "visibility": {
+      "type": "boolean",
+      "default": true,
+      "write_help": "Control whether this memory appears in Northlight's human memory surfaces.",
+      "edit_help": "Change whether this memory appears in Northlight's human memory surfaces."
+    }
+  }
+}
+```
+
+Each addendum is a nonempty object keyed by lowercase kebab-case local field names. A declaration has no keys beyond these:
+
+| Key | Required | Contract |
+|---|---|---|
+| `type` | yes | `boolean`, `string`, `number`, or `enum`. |
+| `values` | enum only | A nonempty, unique list of nonempty strings. It is invalid for every other type. |
+| `default` | no | A value matching `type`; an enum default must be one of `values`. |
+| `write_help` | yes | Nonblank single-line text generated into the field catalog on `crtr memory write -h`. |
+| `edit_help` | yes | Nonblank single-line text generated into the field catalog on `crtr memory edit -h`. |
+
+The generated catalogs show each installed field's full path, type (or enum alternatives), and default when declared. They are the maintained authoring surface; the addendum is their sole help source. Read those leaves for the set, change, and unset mechanics.
+
+Document values live directly in frontmatter under `extensions.<plugin-name>.<field>` — never beneath a `properties` layer:
+
+```yaml
+extensions:
+  northlight:
+    visibility: false
+```
+
+`extensions` and each namespace must be mappings. Values may only be strings, booleans, or finite numbers; a declared field then must satisfy its own type, and an enum must be one of its declared strings. A plugin can declare only fields in its own manifest-name namespace. Two plugins can use the same local field name because their namespaces remain distinct.
+
+A default is interpretation, not persistence: an absent declared field resolves to its default only in the effective metadata projection and is never written back into frontmatter. `crtr memory read --frontmatter` exposes exactly the explicit raw mapping. Structured `crtr --json memory read` and `crtr --json memory list` expose only effective, valid metadata in `extensions`, overlaying explicit values on enabled declarations' defaults. Ordinary read and list rendering deliberately omit the metadata, and crouter never injects it into a memory body or agent-facing memory render.
+
+Crouter maintains separate declaration views for validation and interpretation. Validation and generated authoring help use the closest installed declaration even when its plugin is disabled, so an existing value remains type-checked and can be changed or removed. Effective structured metadata uses only the winning enabled declaration. Therefore disabling a plugin leaves its raw frontmatter in place but omits that namespace and its defaults from effective output; it has no crouter behavior of its own. If the owner is removed or cannot resolve, the namespace is raw-only and inert, lint reports it as unresolved, and unrelated core-frontmatter edits preserve it. Re-enabling or reinstalling the owner restores explicit values and defaults to effective interpretation without rewriting the document.
+
+Archive plugins declare the identical addendum in `bundle.json` beside `bundleVersion`:
+
+```json
+{
+  "bundleVersion": 1,
+  "memory_extensions": {
+    "visibility": {
+      "type": "boolean",
+      "default": true,
+      "write_help": "Control whether this memory appears in a human-facing view.",
+      "edit_help": "Change whether this memory appears in a human-facing view."
+    }
+  }
+}
+```
+
+The archive validator applies the same closed declaration contract and copies the accepted block into the synthesized installed `plugin.json`; archive and source plugins therefore present one installed declaration model.
+
+`crtr memory lint` validates extension mappings and reports malformed mappings, unresolved namespaces, undeclared fields, non-scalar values, wrong types, and invalid enum values at their field paths. Installation and every update validate the candidate declaration plus every candidate `memory/**/*.md` document against the shared core-frontmatter and extension contracts before activation. The candidate's own declaration governs its package while it is checked, including when it changes or removes a declaration present in the installed version. Candidates are staged outside active plugin paths and replace the active package only after validation; a failed source, archive, or marketplace candidate never becomes reachable through an active plugin path, and the previous package and recorded version remain active.
 
 ## Plugin kinds
 

package/dist/builtin-memory/memory-read-orientation.md

@@ -0,0 +1,13 @@
+---
+kind: knowledge
+when-and-why-to-read: When an agent reads its first memory document, this knowledge should be read because the inspection and revision affordances stay visible without taxing every later read.
+rationale: The generic follow-up appeared after every memory read even though transcript-scoped delivery can teach it once; Silas asked to move it into a one-time built-in memory on 2026-08-17.
+unlisted: true
+lint-ignore: broad-memory-read
+surfaces:
+  - on: memory-read
+    match: "**"
+    at: content
+---
+
+`crtr memory read --frontmatter <name>` includes YAML frontmatter. Revise a document with `crtr memory edit` (recorded, with a rationale), or browse the inventory with `crtr memory list`.

package/dist/clients/attach/chrome/bash-jobs.js

@@ -4,7 +4,7 @@
 // activeBackgroundBashJobs' job, in core/bash-jobs.ts). Enter on that row opens
 // the Inspector's `jobs` section, which owns the drill-in rendering.
 import { bashJobCommandLine, formatBashElapsed } from '../../../core/bash-jobs.js';
-/** The job's real command line (past its injected env preamble), capped to `cap` columns. A
+/** The job's command line, capped to `cap` columns. A
  *  shell one-liner is cut on a word boundary when there is one near the cap, so
  *  the cell ends on a readable token instead of mid-`$((`. */
 function cmdCell(command, cap) {