crewly 1.8.4 → 1.8.6

package/dist/backend/backend/src/services/orc/orc-delivery-enforcer.service.d.ts

@@ -0,0 +1,142 @@
+/**
+ * OrcDeliveryEnforcerService
+ *
+ * **Why this exists** (2026-05-23 incident, the "affiliate research" case):
+ *
+ * Steve asked the team to research affiliate programs at 12:59 PM. ORC
+ * acknowledged at 1:00 PM with "Atlas + Sage/Kai 派出去了, ETA 30-40min".
+ * Sage finished Phase 1 at 1:15, Kai finished Phase 2 at 1:28 — but
+ * Steve never saw the result. ORC's terminal logs claimed the pipeline
+ * was "closed" and the result "already routed to Steve at Slack thread
+ * ...", but there were zero `/api/slack/send` calls all day. ORC's
+ * internal mental model believed delivery happened; the actual skill
+ * call didn't.
+ *
+ * Root cause: ORC's prompt has a HARD pre-yield gate ("any `[CHAT:slack-…]`
+ * MUST have a `reply-slack` before yielding"). But for a long-running
+ * delegation, the user-visible deliverable comes from the *agent* via
+ * `[DONE]`-style status reports — long AFTER ORC's initial ack. ORC
+ * reads the agent's `[DONE]` as internal team chatter, narrates "pipeline
+ * closed", and yields without delivering to Steve. The prompt rule
+ * doesn't catch this case because the prompt looks for `[CHAT:slack-…]`
+ * (user-originating) not `[DONE]` (agent-originating).
+ *
+ * **What this service does:**
+ *
+ *   1. When a worker agent posts `[DONE]` / `[COMPLETED]` to a
+ *      slack-prefixed conversation (chat.controller's "Agent status
+ *      routed to orchestrator" path), call {@link markPendingDelivery}.
+ *      The service records a pending delivery with `dueBy = now + 3 min`.
+ *
+ *   2. When ORC successfully posts via `/api/slack/send` to the same
+ *      thread, call {@link markDelivered}. Pending delivery cleared.
+ *
+ *   3. A timer scans every 30 s. For any pending delivery whose `dueBy`
+ *      has passed AND ORC hasn't replied, enqueue a `[DELIVER_REQUIRED]`
+ *      system message to ORC via MessageQueueService. ORC's prompt
+ *      treats `[DELIVER_REQUIRED]` exactly like `[CHAT:slack-…]` for
+ *      the pre-yield gate.
+ *
+ *   4. Exponential backoff between reminders for the same thread, to
+ *      avoid spamming ORC if it's genuinely stuck or rate-limited.
+ *      First reminder at 3 min, then 10 min, then 30 min, then stop.
+ *
+ * Fire-and-forget on all writes — a fault in the enforcer MUST NOT
+ * block chat or slack flow.
+ *
+ * @module services/orc/orc-delivery-enforcer.service
+ */
+/**
+ * Identifier for a slack thread — channelId + threadTs (or empty if
+ * not a slack conversation, in which case we skip tracking entirely).
+ */
+export interface SlackThreadKey {
+    channelId: string;
+    threadTs: string;
+}
+export interface PendingDelivery {
+    key: SlackThreadKey;
+    /** The full conversation id, e.g. `slack-D0AC…-1779…`. Stored for the reminder text. */
+    conversationId: string;
+    /** Session name of the agent that posted [DONE]. */
+    agentSender: string;
+    /** First ~200 chars of the agent's [DONE] message — surfaces in the reminder. */
+    deliverableSummary: string;
+    /** When the agent posted (ms). */
+    doneAt: number;
+    /** Number of reminders fired so far (drives REMINDER_CADENCE_MS index). */
+    remindersFired: number;
+    /** Next eligible reminder time (ms). */
+    nextDueAt: number;
+}
+/**
+ * Function the enforcer uses to send a `[DELIVER_REQUIRED]` message to
+ * ORC. Injected at construction time so tests can stub it and so the
+ * service has no hard dep on MessageQueueService.
+ */
+export type DeliveryReminderSink = (params: {
+    conversationId: string;
+    text: string;
+}) => void;
+export interface OrcDeliveryEnforcerOptions {
+    /** Wired from index.ts to enqueue the reminder via MessageQueueService. */
+    reminderSink: DeliveryReminderSink;
+    /** Scan interval. Default 30 s. */
+    tickIntervalMs?: number;
+}
+/**
+ * Singleton scope — there's one ORC, one queue of pending deliveries.
+ */
+export declare class OrcDeliveryEnforcerService {
+    private static instance;
+    private readonly logger;
+    private readonly reminderSink;
+    private readonly tickIntervalMs;
+    private timer;
+    /** key = `${channelId}::${threadTs}` */
+    private readonly pending;
+    constructor(opts: OrcDeliveryEnforcerOptions);
+    static getInstance(): OrcDeliveryEnforcerService | null;
+    static setInstance(next: OrcDeliveryEnforcerService | null): void;
+    /** Start the periodic scan. Idempotent. */
+    start(): void;
+    stop(): void;
+    /**
+     * Call this from `chat.controller` when an agent posts a `[DONE]`-style
+     * status to a slack-prefixed conversation. Safe to call multiple times
+     * for the same thread — the most recent agent message wins (we
+     * surface only the latest deliverable summary in the reminder).
+     */
+    markPendingDelivery(input: {
+        conversationId: string;
+        agentSender: string;
+        text: string;
+    }): void;
+    /**
+     * Call this from `slack.controller` after a successful `/api/slack/send`.
+     * Cleared regardless of which agent originated the underlying deliverable.
+     */
+    markDelivered(input: {
+        channelId: string;
+        threadTs?: string | null;
+    }): void;
+    /** Test affordance — peek at the in-memory ledger. */
+    _peekPending(): PendingDelivery[];
+    /**
+     * Public for tests + the manual-trigger endpoint. Otherwise driven by
+     * the internal timer.
+     */
+    tick(now?: number): {
+        firedFor: string[];
+    };
+    private formatReminder;
+}
+export declare function isAgentDeliveryMarker(text: string): boolean;
+/**
+ * Parse a chat-v2 conversation id of the form `slack-<channelId>-<ts>`
+ * into { channelId, threadTs }. Returns null for non-slack ids. Mirrors
+ * the regex in `request-sla.subscriber` so the enforcer agrees with the
+ * SLA layer on what "the same thread" means.
+ */
+export declare function parseSlackConversationId(conversationId: string): SlackThreadKey | null;
+//# sourceMappingURL=orc-delivery-enforcer.service.d.ts.map

package/dist/backend/backend/src/services/orc/orc-delivery-enforcer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orc-delivery-enforcer.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/orc/orc-delivery-enforcer.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAgBH;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,cAAc,CAAC;IACpB,wFAAwF;IACxF,cAAc,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,KAAK,IAAI,CAAC;AAEX,MAAM,WAAW,0BAA0B;IACzC,2EAA2E;IAC3E,YAAY,EAAE,oBAAoB,CAAC;IACnC,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2C;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IACpD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,KAAK,CAA+B;IAC5C,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;gBAElD,IAAI,EAAE,0BAA0B;IAM5C,MAAM,CAAC,WAAW,IAAI,0BAA0B,GAAG,IAAI;IAIvD,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,0BAA0B,GAAG,IAAI,GAAG,IAAI;IAKjE,2CAA2C;IAC3C,KAAK,IAAI,IAAI;IAUb,IAAI,IAAI,IAAI;IAQZ;;;;;OAKG;IACH,mBAAmB,CAAC,KAAK,EAAE;QACzB,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,IAAI;IAyBR;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAY3E,sDAAsD;IACtD,YAAY,IAAI,eAAe,EAAE;IAIjC;;;OAGG;IACH,IAAI,CAAC,GAAG,GAAE,MAAmB,GAAG;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE;IA8CtD,OAAO,CAAC,cAAc;CAevB;AAMD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI3D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,GACrB,cAAc,GAAG,IAAI,CAyBvB"}

package/dist/backend/backend/src/services/orc/orc-delivery-enforcer.service.js

@@ -0,0 +1,265 @@
+/**
+ * OrcDeliveryEnforcerService
+ *
+ * **Why this exists** (2026-05-23 incident, the "affiliate research" case):
+ *
+ * Steve asked the team to research affiliate programs at 12:59 PM. ORC
+ * acknowledged at 1:00 PM with "Atlas + Sage/Kai 派出去了, ETA 30-40min".
+ * Sage finished Phase 1 at 1:15, Kai finished Phase 2 at 1:28 — but
+ * Steve never saw the result. ORC's terminal logs claimed the pipeline
+ * was "closed" and the result "already routed to Steve at Slack thread
+ * ...", but there were zero `/api/slack/send` calls all day. ORC's
+ * internal mental model believed delivery happened; the actual skill
+ * call didn't.
+ *
+ * Root cause: ORC's prompt has a HARD pre-yield gate ("any `[CHAT:slack-…]`
+ * MUST have a `reply-slack` before yielding"). But for a long-running
+ * delegation, the user-visible deliverable comes from the *agent* via
+ * `[DONE]`-style status reports — long AFTER ORC's initial ack. ORC
+ * reads the agent's `[DONE]` as internal team chatter, narrates "pipeline
+ * closed", and yields without delivering to Steve. The prompt rule
+ * doesn't catch this case because the prompt looks for `[CHAT:slack-…]`
+ * (user-originating) not `[DONE]` (agent-originating).
+ *
+ * **What this service does:**
+ *
+ *   1. When a worker agent posts `[DONE]` / `[COMPLETED]` to a
+ *      slack-prefixed conversation (chat.controller's "Agent status
+ *      routed to orchestrator" path), call {@link markPendingDelivery}.
+ *      The service records a pending delivery with `dueBy = now + 3 min`.
+ *
+ *   2. When ORC successfully posts via `/api/slack/send` to the same
+ *      thread, call {@link markDelivered}. Pending delivery cleared.
+ *
+ *   3. A timer scans every 30 s. For any pending delivery whose `dueBy`
+ *      has passed AND ORC hasn't replied, enqueue a `[DELIVER_REQUIRED]`
+ *      system message to ORC via MessageQueueService. ORC's prompt
+ *      treats `[DELIVER_REQUIRED]` exactly like `[CHAT:slack-…]` for
+ *      the pre-yield gate.
+ *
+ *   4. Exponential backoff between reminders for the same thread, to
+ *      avoid spamming ORC if it's genuinely stuck or rate-limited.
+ *      First reminder at 3 min, then 10 min, then 30 min, then stop.
+ *
+ * Fire-and-forget on all writes — a fault in the enforcer MUST NOT
+ * block chat or slack flow.
+ *
+ * @module services/orc/orc-delivery-enforcer.service
+ */
+import { LoggerService } from '../core/logger.service.js';
+/** Reminder cadence (ms): first reminder at 3 min, then 10 min, then 30 min, then stop. */
+const REMINDER_CADENCE_MS = [
+    3 * 60 * 1000,
+    10 * 60 * 1000,
+    30 * 60 * 1000,
+];
+const DEFAULT_TICK_INTERVAL_MS = 30 * 1000;
+/** Markers in agent output that indicate user-facing delivery is ready. */
+const DELIVERY_MARKERS = ['[DONE]', '[COMPLETED]', '[DELIVERED]'];
+/**
+ * Singleton scope — there's one ORC, one queue of pending deliveries.
+ */
+export class OrcDeliveryEnforcerService {
+    static instance = null;
+    logger;
+    reminderSink;
+    tickIntervalMs;
+    timer = null;
+    /** key = `${channelId}::${threadTs}` */
+    pending = new Map();
+    constructor(opts) {
+        this.logger = LoggerService.getInstance().createComponentLogger('OrcDeliveryEnforcer');
+        this.reminderSink = opts.reminderSink;
+        this.tickIntervalMs = opts.tickIntervalMs ?? DEFAULT_TICK_INTERVAL_MS;
+    }
+    static getInstance() {
+        return this.instance;
+    }
+    static setInstance(next) {
+        if (this.instance && this.instance !== next)
+            this.instance.stop();
+        this.instance = next;
+    }
+    /** Start the periodic scan. Idempotent. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.tick(), this.tickIntervalMs);
+        this.timer.unref?.();
+        this.logger.info('OrcDeliveryEnforcer started', {
+            tickIntervalMs: this.tickIntervalMs,
+            cadenceMinutes: REMINDER_CADENCE_MS.map((n) => Math.round(n / 60000)),
+        });
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            this.logger.info('OrcDeliveryEnforcer stopped');
+        }
+    }
+    /**
+     * Call this from `chat.controller` when an agent posts a `[DONE]`-style
+     * status to a slack-prefixed conversation. Safe to call multiple times
+     * for the same thread — the most recent agent message wins (we
+     * surface only the latest deliverable summary in the reminder).
+     */
+    markPendingDelivery(input) {
+        if (!isAgentDeliveryMarker(input.text))
+            return;
+        const key = parseSlackConversationId(input.conversationId);
+        if (!key)
+            return; // not a slack thread — ignore
+        const k = serializeKey(key);
+        const now = Date.now();
+        const summary = input.text.slice(0, 200);
+        this.pending.set(k, {
+            key,
+            conversationId: input.conversationId,
+            agentSender: input.agentSender,
+            deliverableSummary: summary,
+            doneAt: now,
+            remindersFired: 0,
+            nextDueAt: now + REMINDER_CADENCE_MS[0],
+        });
+        this.logger.info('OrcDeliveryEnforcer pending delivery recorded', {
+            conversationId: input.conversationId,
+            agentSender: input.agentSender,
+            summaryPreview: summary.slice(0, 80),
+            firstReminderInSec: REMINDER_CADENCE_MS[0] / 1000,
+        });
+    }
+    /**
+     * Call this from `slack.controller` after a successful `/api/slack/send`.
+     * Cleared regardless of which agent originated the underlying deliverable.
+     */
+    markDelivered(input) {
+        if (!input.channelId || !input.threadTs)
+            return;
+        const k = serializeKey({ channelId: input.channelId, threadTs: input.threadTs });
+        const had = this.pending.delete(k);
+        if (had) {
+            this.logger.info('OrcDeliveryEnforcer delivery cleared by reply-slack', {
+                channelId: input.channelId,
+                threadTs: input.threadTs,
+            });
+        }
+    }
+    /** Test affordance — peek at the in-memory ledger. */
+    _peekPending() {
+        return [...this.pending.values()];
+    }
+    /**
+     * Public for tests + the manual-trigger endpoint. Otherwise driven by
+     * the internal timer.
+     */
+    tick(now = Date.now()) {
+        const firedFor = [];
+        for (const [k, item] of this.pending) {
+            if (now < item.nextDueAt)
+                continue;
+            if (item.remindersFired >= REMINDER_CADENCE_MS.length) {
+                // Out of reminder budget — drop the entry so we stop spamming.
+                this.pending.delete(k);
+                this.logger.warn('OrcDeliveryEnforcer reminder budget exhausted — giving up', {
+                    conversationId: item.conversationId,
+                    remindersFired: item.remindersFired,
+                });
+                continue;
+            }
+            const text = this.formatReminder(item);
+            try {
+                this.reminderSink({
+                    conversationId: item.conversationId,
+                    text,
+                });
+                firedFor.push(item.conversationId);
+                this.logger.info('OrcDeliveryEnforcer reminder fired', {
+                    conversationId: item.conversationId,
+                    agentSender: item.agentSender,
+                    reminderIndex: item.remindersFired,
+                    minutesSinceDone: Math.round((now - item.doneAt) / 60000),
+                });
+            }
+            catch (err) {
+                this.logger.warn('OrcDeliveryEnforcer reminderSink threw (swallowed)', {
+                    error: err.message,
+                    conversationId: item.conversationId,
+                });
+            }
+            item.remindersFired += 1;
+            const nextOffset = REMINDER_CADENCE_MS[item.remindersFired];
+            if (nextOffset === undefined) {
+                // Final reminder fired — drop the entry now so we don't keep
+                // re-evaluating it on every tick.
+                this.pending.delete(k);
+            }
+            else {
+                item.nextDueAt = now + nextOffset;
+            }
+        }
+        return { firedFor };
+    }
+    formatReminder(item) {
+        const minutes = Math.round((Date.now() - item.doneAt) / 60000);
+        return [
+            `[DELIVER_REQUIRED] Steve is waiting on a deliverable in Slack thread ${item.conversationId}.`,
+            ``,
+            `Agent \`${item.agentSender}\` posted [DONE] ${minutes} min ago with this content (preview):`,
+            `> ${item.deliverableSummary.slice(0, 200)}${item.deliverableSummary.length > 200 ? '…' : ''}`,
+            ``,
+            `Action required: call reply-slack now with the deliverable. Treat this`,
+            `the same as a [CHAT:slack-...] message — do NOT yield the turn until`,
+            `the reply lands on the thread. If the agent's output isn't the final`,
+            `deliverable yet (e.g. it's "Phase 1 done" out of 2), send Steve a status`,
+            `update via reply-slack saying so + revised ETA, then continue waiting.`,
+        ].join('\n');
+    }
+}
+// =============================================================================
+// Helpers (exported for testing)
+// =============================================================================
+export function isAgentDeliveryMarker(text) {
+    if (!text)
+        return false;
+    const upper = text.toUpperCase();
+    return DELIVERY_MARKERS.some((m) => upper.includes(m));
+}
+/**
+ * Parse a chat-v2 conversation id of the form `slack-<channelId>-<ts>`
+ * into { channelId, threadTs }. Returns null for non-slack ids. Mirrors
+ * the regex in `request-sla.subscriber` so the enforcer agrees with the
+ * SLA layer on what "the same thread" means.
+ */
+export function parseSlackConversationId(conversationId) {
+    if (!conversationId || !conversationId.startsWith('slack-'))
+        return null;
+    // Strip any per-message suffix (`-msg-<ts>`) so we key on thread root.
+    const stripped = conversationId.replace(/-msg-\d+\.\d+$/, '');
+    const rest = stripped.slice('slack-'.length);
+    const lastDash = rest.lastIndexOf('-');
+    if (lastDash < 1)
+        return null;
+    const channelId = rest.slice(0, lastDash);
+    let threadTs = rest.slice(lastDash + 1);
+    // Some producers serialize ts as `1779555555-588569` (dash) or
+    // `1779555555.588569` (dot). Normalize to dotted form to match
+    // Slack-API ts shape.
+    if (/^\d+$/.test(threadTs)) {
+        // No fractional segment in URL form — try one more split.
+        const beforeRest = rest.slice(0, lastDash);
+        const prevDash = beforeRest.lastIndexOf('-');
+        if (prevDash > 0) {
+            const candidate = `${beforeRest.slice(prevDash + 1)}.${threadTs}`;
+            if (/^\d+\.\d+$/.test(candidate)) {
+                return { channelId: beforeRest.slice(0, prevDash), threadTs: candidate };
+            }
+        }
+    }
+    // If threadTs already contains a dot (dotted form), keep as-is.
+    return { channelId, threadTs };
+}
+function serializeKey(k) {
+    return `${k.channelId}::${k.threadTs}`;
+}
+//# sourceMappingURL=orc-delivery-enforcer.service.js.map

package/dist/backend/backend/src/services/orc/orc-delivery-enforcer.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orc-delivery-enforcer.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/orc/orc-delivery-enforcer.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/session/pty/pty-session.d.ts

@@ -6,7 +6,35 @@
  *
  * @module pty-session
  */
+import * as pty from 'node-pty';
 import type { ISession, SessionOptions } from '../session-backend.interface.js';
+export declare function _setPtySpawnImplForTesting(impl: typeof pty.spawn): () => void;
+/**
+ * Wraps `pty.spawn` with retry-on-transient + actionable error.
+ *
+ * On the 4th and final failure, throws `PtySpawnExhaustedError` with a
+ * human-readable message + machine-readable diagnostics. Callers should
+ * surface the .message to the user (e.g. ORC → Slack).
+ */
+declare class PtySpawnExhaustedError extends Error {
+    readonly diagnostics: {
+        attempts: number;
+        lastError: string;
+        userProcessCount: number | null;
+        maxProcPerUid: number | null;
+        command: string;
+        platform: string;
+    };
+    constructor(message: string, diagnostics: {
+        attempts: number;
+        lastError: string;
+        userProcessCount: number | null;
+        maxProcPerUid: number | null;
+        command: string;
+        platform: string;
+    });
+}
+export { PtySpawnExhaustedError };
 /**
  * PTY Session implementation using node-pty.
  *

package/dist/backend/backend/src/services/session/pty/pty-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pty-session.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/session/pty/pty-session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAQhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,UAAW,YAAW,QAAQ;aA+CzB,IAAI,EAAE,MAAM;aACZ,GAAG,EAAE,MAAM;IA/C5B;;OAEG;IACH,OAAO,CAAC,UAAU,CAAW;IAE7B;;OAEG;IACH,OAAO,CAAC,aAAa,CAA0C;IAE/D;;OAEG;IACH,OAAO,CAAC,aAAa,CAA0C;IAE/D;;OAEG;IACH,OAAO,CAAC,MAAM,CAAS;IAEvB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAkB;IAEhC;;;;;;;;;;;;;;;;;;;OAmBG;gBAEc,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EAC3B,OAAO,EAAE,cAAc;IAmDxB;;OAEG;IACH,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAepD;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAepD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAqBxC;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAa3B;;;;;;;;;;;;;OAaG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAyChC;;;;OAIG;IACH,QAAQ,IAAI,OAAO;IAInB;;;;;;;;OAQG;IACH,mBAAmB,IAAI,OAAO;IAgB9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyC1B;;;;;OAKG;IACH,OAAO,CAAC,WAAW;CASnB"}
+{"version":3,"file":"pty-session.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/session/pty/pty-session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAahF,wBAAgB,0BAA0B,CACzC,IAAI,EAAE,OAAO,GAAG,CAAC,KAAK,GACpB,MAAM,IAAI,CAMZ;AAsED;;;;;;GAMG;AACH,cAAM,sBAAuB,SAAQ,KAAK;aAGxB,WAAW,EAAE;QAC5B,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;KACjB;gBARD,OAAO,EAAE,MAAM,EACC,WAAW,EAAE;QAC5B,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;KACjB;CAKF;AA6DD,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,UAAW,YAAW,QAAQ;aA+CzB,IAAI,EAAE,MAAM;aACZ,GAAG,EAAE,MAAM;IA/C5B;;OAEG;IACH,OAAO,CAAC,UAAU,CAAW;IAE7B;;OAEG;IACH,OAAO,CAAC,aAAa,CAA0C;IAE/D;;OAEG;IACH,OAAO,CAAC,aAAa,CAA0C;IAE/D;;OAEG;IACH,OAAO,CAAC,MAAM,CAAS;IAEvB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAkB;IAEhC;;;;;;;;;;;;;;;;;;;OAmBG;gBAEc,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EAC3B,OAAO,EAAE,cAAc;IAqExB;;OAEG;IACH,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAepD;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAepD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAqBxC;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAa3B;;;;;;;;;;;;;OAaG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAyChC;;;;OAIG;IACH,QAAQ,IAAI,OAAO;IAInB;;;;;;;;OAQG;IACH,mBAAmB,IAAI,OAAO;IAgB9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyC1B;;;;;OAKG;IACH,OAAO,CAAC,WAAW;CASnB"}

package/dist/backend/backend/src/services/session/pty/pty-session.js

@@ -11,6 +11,152 @@ import { execSync } from 'child_process';
 import { DEFAULT_TERMINAL_COLS, DEFAULT_TERMINAL_ROWS, } from '../session-backend.interface.js';
 import { PTY_CONSTANTS } from '../../../constants.js';
 import { LoggerService } from '../../core/logger.service.js';
+/**
+ * Test affordance: lets `pty-session.test.ts` swap in a stub instead of
+ * calling the real `pty.spawn`. Production code path is identical.
+ */
+let ptySpawnImpl = pty.spawn;
+export function _setPtySpawnImplForTesting(impl) {
+    const previous = ptySpawnImpl;
+    ptySpawnImpl = impl;
+    return () => {
+        ptySpawnImpl = previous;
+    };
+}
+/**
+ * Retry policy for transient `pty.spawn` failures. The native node-pty
+ * binding throws a generic `Error("posix_spawnp failed.")` with no errno
+ * detail — on macOS this is usually EAGAIN (process table briefly
+ * saturated by Chrome helpers / VS Code extensions / build spawns) and
+ * retrying after a short pause succeeds. We give up after the 4th
+ * attempt and throw a richer diagnostic.
+ *
+ * Sync sleep uses `Atomics.wait` on an ephemeral SharedArrayBuffer —
+ * blocks the thread without spawning a `sleep(1)` subprocess (which
+ * would compound the very problem we're working around).
+ */
+const PTY_SPAWN_RETRY_BACKOFFS_MS = [0, 150, 400, 1000];
+const PTY_TRANSIENT_ERROR_MARKERS = [
+    'posix_spawnp',
+    'EAGAIN',
+    'ENOMEM',
+    'EMFILE',
+    'ENFILE',
+];
+function isTransientSpawnError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return PTY_TRANSIENT_ERROR_MARKERS.some((m) => msg.includes(m));
+}
+function syncSleepMs(ms) {
+    if (ms <= 0)
+        return;
+    const buf = new SharedArrayBuffer(4);
+    const view = new Int32Array(buf);
+    // Wait returns 'timed-out' after `ms` regardless of view[0] (which
+    // nobody writes to). This is the modern synchronous sleep pattern
+    // recommended for situations where a busy-wait would burn CPU.
+    Atomics.wait(view, 0, 0, ms);
+}
+/**
+ * Read current user process count cheaply. Used in the spawn-failure
+ * diagnostic to tell the user if they're near macOS `kern.maxprocperuid`.
+ */
+function readUserProcessCount() {
+    try {
+        const out = execSync('ps -u "$(id -un)" 2>/dev/null | wc -l', {
+            encoding: 'utf8',
+            timeout: 800,
+        });
+        const n = parseInt(out.trim(), 10);
+        return Number.isFinite(n) ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read kern.maxprocperuid. macOS-specific; returns null on non-Darwin. */
+function readMaxProcPerUid() {
+    if (process.platform !== 'darwin')
+        return null;
+    try {
+        const out = execSync('sysctl -n kern.maxprocperuid', {
+            encoding: 'utf8',
+            timeout: 500,
+        });
+        const n = parseInt(out.trim(), 10);
+        return Number.isFinite(n) ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Wraps `pty.spawn` with retry-on-transient + actionable error.
+ *
+ * On the 4th and final failure, throws `PtySpawnExhaustedError` with a
+ * human-readable message + machine-readable diagnostics. Callers should
+ * surface the .message to the user (e.g. ORC → Slack).
+ */
+class PtySpawnExhaustedError extends Error {
+    diagnostics;
+    constructor(message, diagnostics) {
+        super(message);
+        this.diagnostics = diagnostics;
+        this.name = 'PtySpawnExhaustedError';
+    }
+}
+function spawnPtyWithRetry(command, args, options, logger) {
+    let lastError = null;
+    for (let attempt = 0; attempt < PTY_SPAWN_RETRY_BACKOFFS_MS.length; attempt++) {
+        const backoffMs = PTY_SPAWN_RETRY_BACKOFFS_MS[attempt];
+        if (backoffMs > 0) {
+            logger.warn('PTY spawn retry — sleeping then retrying', {
+                attempt,
+                backoffMs,
+                command,
+            });
+            syncSleepMs(backoffMs);
+        }
+        try {
+            return ptySpawnImpl(command, args, options);
+        }
+        catch (err) {
+            lastError = err;
+            if (!isTransientSpawnError(err)) {
+                // Non-transient (e.g. ENOENT — command not found): fail fast.
+                throw err;
+            }
+            // Else loop — backoff already happened next iter.
+        }
+    }
+    // Exhausted retries — build an actionable message.
+    const userProcessCount = readUserProcessCount();
+    const maxProcPerUid = readMaxProcPerUid();
+    const errMsg = lastError instanceof Error ? lastError.message : String(lastError);
+    let humanHint = '';
+    if (userProcessCount !== null &&
+        maxProcPerUid !== null &&
+        userProcessCount > maxProcPerUid * 0.75) {
+        humanHint = ` Your user process count is ${userProcessCount} / ${maxProcPerUid} (>75% of limit). Close some Chrome tabs / VS Code windows / other agent sessions and retry.`;
+    }
+    else if (process.platform === 'darwin') {
+        humanHint =
+            ' Likely a transient kernel-level process-table spike (Chrome / VS Code / build tools spawning many helpers). Wait ~30 s and the next attempt should succeed; the OSS will auto-retry on the next user trigger.';
+    }
+    else {
+        humanHint = ' Transient spawn failure — retry shortly.';
+    }
+    const message = `PTY spawn failed after ${PTY_SPAWN_RETRY_BACKOFFS_MS.length} attempts (${errMsg}).${humanHint}`;
+    throw new PtySpawnExhaustedError(message, {
+        attempts: PTY_SPAWN_RETRY_BACKOFFS_MS.length,
+        lastError: errMsg,
+        userProcessCount,
+        maxProcPerUid,
+        command,
+        platform: process.platform,
+    });
+}
+export { PtySpawnExhaustedError };
 /**
  * PTY Session implementation using node-pty.
  *
@@ -97,14 +243,18 @@ export class PtySession {
             TERM: 'xterm-256color',
         };
         try {
-            // Spawn the PTY process
-            this.ptyProcess = pty.spawn(options.command, options.args ?? [], {
+            // Spawn the PTY process — wrapped in retry-with-backoff so that
+            // transient `posix_spawnp failed` errors (typical on macOS when
+            // Chrome / VS Code briefly saturate the process table) don't
+            // turn into user-visible spawn failures. See spawnPtyWithRetry
+            // for the policy + sync sleep pattern.
+            this.ptyProcess = spawnPtyWithRetry(options.command, options.args ?? [], {
                 name: 'xterm-256color',
                 cols: options.cols ?? DEFAULT_TERMINAL_COLS,
                 rows: options.rows ?? DEFAULT_TERMINAL_ROWS,
                 cwd: options.cwd,
                 env: sessionEnv,
-            });
+            }, this.logger);
             this.logger.info('PTY process spawned successfully', {
                 name,
                 pid: this.ptyProcess.pid,
@@ -112,11 +262,19 @@ export class PtySession {
             });
         }
         catch (spawnError) {
+            // `PtySpawnExhaustedError` carries the actionable hint already
+            // in its .message; other errors (e.g. ENOENT — command not
+            // found) propagate as-is. Either way we log richer context.
+            const errMsg = spawnError instanceof Error ? spawnError.message : String(spawnError);
+            const diagnostics = spawnError instanceof PtySpawnExhaustedError
+                ? spawnError.diagnostics
+                : undefined;
             this.logger.error('Failed to spawn PTY process', {
                 name,
                 command: options.command,
                 cwd: options.cwd,
-                error: spawnError instanceof Error ? spawnError.message : String(spawnError),
+                error: errMsg,
+                diagnostics,
                 stack: spawnError instanceof Error ? spawnError.stack : undefined,
             });
             throw spawnError;