@cruxy/cli 0.24.0 → 0.26.0

package/dist/render/types.d.ts

@@ -39,8 +39,22 @@ export interface RenderCapabilities {
     /** Unicode glyphs are safe (U.1) — false under `TERM=dumb` / `CRUXY_ASCII`;
      * independent of `color`. Drives the theme's glyph table, not its stylers. */
     unicode: boolean;
-    /** Terminal columns; 80 when unknown (non-TTY). */
+    /**
+     * Terminal columns (U.12) — the ONE width source every surface reads; 80 when
+     * unknown (non-TTY / no `columns`). Honors `COLUMNS` when set. Mutated in
+     * place on resize (see {@link onResize}), so a surface reading it after a
+     * SIGWINCH sees the new width without re-probing anything.
+     */
     width: number;
+    /**
+     * Subscribe to width changes (U.12): the SIGWINCH push signal for the live
+     * region / transient frames to reflow at the new width. The listener fires
+     * with the new width AFTER {@link width} has been updated; the returned
+     * function unsubscribes. Absent when the stream cannot resize (non-TTY / no
+     * `columns`) — those surfaces just read the static {@link width}. Committed
+     * output is never re-rendered from here; only live surfaces subscribe.
+     */
+    onResize?(listener: (width: number) => void): () => void;
 }
 /** Accumulated token usage the loop already tracks (U.4) — never fabricated. */
 export interface TokenUsage {

package/dist/subagent/orchestrator.d.ts

@@ -6,6 +6,7 @@ import type { Router } from "../routing/index.js";
 import type { ApproveAction, ToolContext, ToolRegistry } from "../tools/index.js";
 import type { SandboxService } from "../sandbox/index.js";
 import { Workspace } from "../workspace/index.js";
+import { Semaphore } from "./semaphore.js";
 import type { SubagentResult, SubagentSpec } from "./types.js";
 /**
  * Everything a spawn needs from the surrounding session, injected by the
@@ -60,6 +61,14 @@ export interface SubagentOrchestratorDeps {
      * same shared checkpoint gate, those writes join the run's one set (⚖︎JC-δ).
      */
     checkpointsActive?: boolean;
+    /**
+     * The ONE shared execution semaphore (C.28). When set, parallel fan-out draws
+     * permits from THIS instance — the same one background jobs use — so the
+     * `subagent.maxConcurrency` cap bounds subagents AND jobs COMBINED, never one
+     * cap each. Omitted → the orchestrator constructs its own (C.33 behaviour,
+     * used by tests that exercise the orchestrator in isolation).
+     */
+    executionSemaphore?: Semaphore;
 }
 /**
  * Spawns subagents (C.14): the existing agent loop re-driven over isolated

package/dist/subagent/orchestrator.js

@@ -32,7 +32,12 @@ export class SubagentOrchestrator {
     sem;
     constructor(deps) {
         this.deps = deps;
-        this.sem = new Semaphore(deps.config.subagent.maxConcurrency);
+        // Share the session's ONE execution semaphore when injected (C.28) so
+        // subagents and background jobs contend for the same permits; fall back to a
+        // private one at the same cap when running the orchestrator in isolation.
+        this.sem =
+            deps.executionSemaphore ??
+                new Semaphore(deps.config.subagent.maxConcurrency);
     }
     /** Live/queued fan-out slots (inspection/tests): proves the global cap holds. */
     get concurrency() {

package/dist/subagent/semaphore.d.ts

@@ -1,27 +1,56 @@
 /**
- * A counting semaphore (C.33): bounds how many subagent runs execute at once.
+ * A counting semaphore (C.33): bounds how many agent runs execute at once.
  * FIFO — waiters are served in arrival order, so a fan-out's results stay
  * dispatch-order-fair — and the permit is handed directly from a releaser to
  * the next waiter, so the live count never transiently exceeds the cap.
  *
- * Used as the ONE shared bound on parallel fan-out. Parallel dispatch happens at
- * depth 0 only (the `spawn_subagents` tool is never granted to a child), and a
- * permit is held for a child's whole lifetime — including any *sequential*
- * nested spawn beneath it, which is deliberately un-permitted. Because no permit
- * holder ever blocks trying to acquire a second permit, the semaphore cannot be
- * part of a wait cycle: it is deadlock-free by construction (see the C.33 design
- * doc's deadlock argument).
+ * Used as the ONE shared bound on all concurrent execution: parallel subagent
+ * fan-out (C.33) AND background jobs (C.28) draw permits from the SAME instance,
+ * so `subagent.maxConcurrency` caps their COMBINED live count — never one cap
+ * per subsystem. Parallel dispatch happens at depth 0 only (the `spawn_subagents`
+ * tool is never granted to a child), and a permit is held for a child's whole
+ * lifetime — including any *sequential* nested spawn beneath it, which is
+ * deliberately un-permitted. Because no permit holder ever blocks trying to
+ * acquire a second permit, the semaphore cannot be part of a wait cycle: it is
+ * deadlock-free by construction (see the C.33 design doc's deadlock argument).
+ *
+ * C.28 adds a PRIORITY lane to {@link acquire}. A background job that pauses to
+ * await a human approval RELEASES its permit (JC-D: a job blocked on a human is
+ * not using compute, and holding the slot would deadlock the cap if N jobs all
+ * paused). When the human approves, the job re-acquires with `priority: true` so
+ * it jumps ahead of newly-dispatched work — a resumed job never starves behind a
+ * fresh fan-out that filled the queue while it waited. Normal (non-priority)
+ * waiters keep strict FIFO among themselves, so C.33's dispatch-order fairness is
+ * unchanged for everything that does not pause.
  */
+export interface AcquireOptions {
+    /**
+     * Serve this waiter ahead of all non-priority waiters (still FIFO among
+     * priority waiters). Used by a resumed background job re-acquiring its slot
+     * after an approval, so it is not starved by work dispatched while it paused.
+     */
+    priority?: boolean;
+}
 export declare class Semaphore {
     private permits;
-    private readonly queue;
+    /** Waiters that take the next permit ahead of {@link normal} (FIFO within). */
+    private readonly priority;
+    /** Ordinary waiters, served strictly FIFO after any priority waiters. */
+    private readonly normal;
     constructor(permits: number);
     /** Run `fn` while holding one permit; the permit is released even if it throws. */
     run<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Take one permit, waiting if none is free. Resolves immediately when a permit
+     * is available; otherwise enqueues onto the priority or normal lane and resolves
+     * when {@link release} hands it a permit. Callers that acquire directly (a
+     * paused/resumed job) MUST call {@link release} exactly once per acquire.
+     */
+    acquire(opts?: AcquireOptions): Promise<void>;
+    /** Return one permit — handed straight to the next waiter (priority first). */
+    release(): void;
     /** Permits currently available (inspection/tests). */
     get available(): number;
     /** Callers currently blocked waiting for a permit (inspection/tests). */
     get waiting(): number;
-    private acquire;
-    private release;
 }

package/dist/subagent/semaphore.js

@@ -1,20 +1,9 @@
-/**
- * A counting semaphore (C.33): bounds how many subagent runs execute at once.
- * FIFO — waiters are served in arrival order, so a fan-out's results stay
- * dispatch-order-fair — and the permit is handed directly from a releaser to
- * the next waiter, so the live count never transiently exceeds the cap.
- *
- * Used as the ONE shared bound on parallel fan-out. Parallel dispatch happens at
- * depth 0 only (the `spawn_subagents` tool is never granted to a child), and a
- * permit is held for a child's whole lifetime — including any *sequential*
- * nested spawn beneath it, which is deliberately un-permitted. Because no permit
- * holder ever blocks trying to acquire a second permit, the semaphore cannot be
- * part of a wait cycle: it is deadlock-free by construction (see the C.33 design
- * doc's deadlock argument).
- */
 export class Semaphore {
     permits;
-    queue = [];
+    /** Waiters that take the next permit ahead of {@link normal} (FIFO within). */
+    priority = [];
+    /** Ordinary waiters, served strictly FIFO after any priority waiters. */
+    normal = [];
     constructor(permits) {
         // A non-positive cap would wedge every run; clamp to at least 1.
         this.permits = Math.max(1, Math.floor(permits));
@@ -29,23 +18,23 @@ export class Semaphore {
             this.release();
         }
     }
-    /** Permits currently available (inspection/tests). */
-    get available() {
-        return this.permits;
-    }
-    /** Callers currently blocked waiting for a permit (inspection/tests). */
-    get waiting() {
-        return this.queue.length;
-    }
-    acquire() {
+    /**
+     * Take one permit, waiting if none is free. Resolves immediately when a permit
+     * is available; otherwise enqueues onto the priority or normal lane and resolves
+     * when {@link release} hands it a permit. Callers that acquire directly (a
+     * paused/resumed job) MUST call {@link release} exactly once per acquire.
+     */
+    acquire(opts = {}) {
         if (this.permits > 0) {
             this.permits--;
             return Promise.resolve();
         }
-        return new Promise((resolve) => this.queue.push(resolve));
+        const lane = opts.priority ? this.priority : this.normal;
+        return new Promise((resolve) => lane.push(resolve));
     }
+    /** Return one permit — handed straight to the next waiter (priority first). */
     release() {
-        const next = this.queue.shift();
+        const next = this.priority.shift() ?? this.normal.shift();
         // Hand the permit straight to the next waiter (never bump the count above
         // the cap); only when nobody waits does the count grow back.
         if (next)
@@ -53,4 +42,12 @@ export class Semaphore {
         else
             this.permits++;
     }
+    /** Permits currently available (inspection/tests). */
+    get available() {
+        return this.permits;
+    }
+    /** Callers currently blocked waiting for a permit (inspection/tests). */
+    get waiting() {
+        return this.priority.length + this.normal.length;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {