@parall/agent-core 1.44.0 → 1.46.0

package/dist/session-lifecycle.d.ts

@@ -0,0 +1,198 @@
+/**
+ * SessionLifecycleCoordinator — the single entry point for session status
+ * writes (active / idle / closed).
+ *
+ * SCOPE — this is a **process-local mitigation**, not a distributed fence.
+ * It serializes and orders the lifecycle writes THIS process issues. It does
+ * NOT order across processes, and it cannot fix a write that times out
+ * client-side but lands server-side later, nor an old turn's step retry
+ * landing during a new turn. The structural fix is a server-side turn fence
+ * (design tracked in #1879 — durable step outbox + turn fence); until that
+ * ships, this closes the in-process interleavings that produced the
+ * 2026-07-13 repro.
+ *
+ * The gateway used to fire active and idle PATCHes independently
+ * (fire-and-forget + detached retries). Two independent HTTP requests have
+ * no ordering: turn 1's in-flight idle could land AFTER turn 2's active and
+ * demote a running session — an epoch check on retry TIMERS cannot cancel a
+ * request already on the wire. The coordinator closes that class by being a
+ * serialized desired-state reconciler:
+ *
+ * - Per session it stores only the LATEST desired state plus a monotonic
+ *   generation (bumped by beginTurn and closeSession).
+ * - At most ONE lifecycle write is in flight per session; when it settles
+ *   the loop re-reads the latest desired state and reconciles — so a
+ *   begin(turn N+1), or a closeSession, that arrives while an earlier write
+ *   is in flight simply waits for it to settle and is written AFTER it.
+ * - finishTurn carries the TurnHandle from its beginTurn; a stale handle
+ *   (generation superseded) is ignored outright.
+ * - Retries re-run the reconcile loop against the LATEST desired state —
+ *   they never replay a captured command, so a pending idle retry is
+ *   naturally superseded by a new turn.
+ * - Errors are CLASSIFIED (ports, defaults are conservative): transient →
+ *   bounded backoff; permanent (4xx) → warn + abandon that desired state (a
+ *   later turn retries with a fresh generation); session-stale (the server
+ *   considers the session terminal) → drop the session, never write again.
+ * - beginTurn / closeSession resolve once one write attempt covering their
+ *   generation has SETTLED (success or failure — bounded by the write's own
+ *   timeout, plus at most one in-flight predecessor). The gateway awaits
+ *   beginTurn before persisting the turn's first AgentStep, so a reused idle
+ *   session is reconciled to active before steps arrive and the server's
+ *   presence guard cannot swallow the turn's activity. A failed active write
+ *   warns and lets the step flow continue.
+ * - closeSession's first settle carries a STRUCTURED outcome (`closed` /
+ *   `stale` / `retrying` / `permanent_failure` / `disposed`) plus a
+ *   `terminal` promise that resolves when the close reaches a terminal fate
+ *   — a caller holding cleanup behind the close (ForkSessionFinalizer) can
+ *   keep ownership through `retrying` instead of mistaking "one attempt
+ *   settled" for "close completed".
+ * - Entries are RECLAIMED (no unbounded Map growth on long-lived daemons):
+ *   dropSession removes the entry immediately when idle, or at the end of an
+ *   in-flight write; a `closed` that landed OR failed permanently reclaims
+ *   too — the permanent failure is not hidden by the reclaim, it is reported
+ *   through the close's outcome/terminal before the entry goes away.
+ * - dispose() is absorbing: every later public command is a no-op that never
+ *   re-creates an entry, issues a write, or arms a timer.
+ *
+ * The write port is infrastructure (ParallClient.updateAgentSession);
+ * retries, generations, error classification and the state machine live here.
+ */
+export type SessionStatusPayload = {
+    status: 'active';
+    trigger_message_id?: string;
+} | {
+    status: 'idle';
+} | {
+    status: 'closed';
+};
+export type TurnHandle = {
+    sessionId: string;
+    generation: number;
+};
+/**
+ * Terminal fate of a closeSession: `closed` — the write landed; `stale` —
+ * the server already considers the session terminal (equivalent outcome for
+ * the caller); `permanent_failure` — a 4xx or retry exhaustion; the close
+ * will never be written and the server-side session may be left non-closed;
+ * `disposed` — the coordinator shut down before the close settled.
+ */
+export type SessionCloseOutcome = 'closed' | 'stale' | 'permanent_failure' | 'disposed';
+/** First-settle view: `retrying` means a transient failure settled the first
+ * bounded attempt and background reconciliation continues — await `terminal`
+ * for the eventual fate. */
+export type SessionCloseSettle = SessionCloseOutcome | 'retrying';
+export type SessionCloseResult = {
+    /** Outcome of the first bounded settle (one write attempt covering the close). */
+    outcome: SessionCloseSettle;
+    /**
+     * Resolves when the close reaches a terminal state. Already resolved (to
+     * `outcome`) unless `outcome === 'retrying'`.
+     */
+    terminal: Promise<SessionCloseOutcome>;
+};
+export type SessionLifecycleScheduler = {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(timer: unknown): void;
+};
+export type SessionLifecycleOpts = {
+    write: (sessionId: string, payload: SessionStatusPayload) => Promise<void>;
+    /**
+     * Transient failure worth retrying (timeout / network / 5xx). Anything
+     * else is treated as permanent: warn + abandon (no retry loop against a
+     * 400/401/403/404). Default: nothing is retryable — callers that want
+     * retries must classify.
+     */
+    isRetryable?: (err: unknown) => boolean;
+    /**
+     * The server considers this session terminal (409 SESSION_NOT_LIVE /
+     * INVALID_TRANSITION). The session is dropped — no further lifecycle
+     * writes, ever. Default: never stale.
+     */
+    isSessionStale?: (err: unknown) => boolean;
+    log?: {
+        warn: (msg: string) => void;
+    };
+    /** Test port; default wraps global timers and unrefs them. */
+    scheduler?: SessionLifecycleScheduler;
+    /** Reconcile retry backoff. Default 5s→15s→45s→135s→405s (~10 min). */
+    retryDelaysMs?: number[];
+};
+export declare class SessionLifecycleCoordinator {
+    private readonly opts;
+    private readonly sessions;
+    private readonly scheduler;
+    private readonly retryDelays;
+    private nextGeneration;
+    private disposed;
+    constructor(opts: SessionLifecycleOpts);
+    /** Sessions currently tracked — reclaimed entries are gone (leak probe). */
+    trackedSessions(): number;
+    /**
+     * Declare a new turn. Resolves once one write attempt covering this turn's
+     * generation has settled (bounded: at most one in-flight predecessor plus
+     * one active write, each bounded by the write port's own timeout). Always
+     * resolves — a failed active write is warned and reconciled in the
+     * background, never blocks the caller.
+     */
+    beginTurn(sessionId: string, triggerMessageId?: string): Promise<TurnHandle>;
+    /**
+     * Declare the turn finished. A stale handle (a newer turn — or a close —
+     * has bumped this session's generation) is ignored: finish(turn N) can
+     * never override begin(turn N+1). Reconciliation runs detached.
+     */
+    finishTurn(handle: TurnHandle): void;
+    /**
+     * Terminal transition (fork teardown). Serialized behind any in-flight
+     * write — a `closed` can never race the turn's idle — and reclaimed once
+     * settled. Resolves after one bounded settle with a STRUCTURED outcome:
+     * `closed` / `stale` / `permanent_failure` are terminal; `retrying` means
+     * background reconciliation continues — the caller keeps ownership of the
+     * session until `terminal` resolves. A close is never silently "done":
+     * every fate is observable.
+     */
+    closeSession(sessionId: string): Promise<SessionCloseResult>;
+    /**
+     * Session is dead (stale / superseded) — no further lifecycle writes, and
+     * the entry is reclaimed (immediately when idle; at the end of an in-flight
+     * write otherwise, unless a new turn revives it in the meantime).
+     */
+    dropSession(sessionId: string): void;
+    /** Every tracked session is dead (server closed them all — new_session). */
+    dropAllSessions(): void;
+    /**
+     * One best-effort reconcile pass over unsettled sessions within a hard
+     * deadline (shutdown). Returns the number still unsettled.
+     */
+    flush(deadlineMs: number): Promise<number>;
+    dispose(): void;
+    /**
+     * Get-or-create the entry and take the next generation. A dropped entry is
+     * REUSED (not replaced): its `writing` flag keeps the single-writer chain
+     * intact if a pre-drop write is still on the wire, and the generation stays
+     * monotonic across the drop boundary.
+     */
+    private upsert;
+    private waitFor;
+    private isReconciled;
+    private isAbandoned;
+    /** Nothing more to do for the current desired state (written or given up). */
+    private isSettled;
+    private pump;
+    private writeLoop;
+    private classify;
+    /**
+     * Drop the entry when it can never write again: dropped (and no write on
+     * the wire), a terminal `closed` that landed, or a `closed` that failed
+     * permanently (its fate has been reported via closeSession's outcome — an
+     * entry kept around would be an unowned leak, not a recovery path). Called
+     * after every write settles and from dropSession — this is what keeps the
+     * Map bounded on a long-lived daemon churning fork sessions.
+     */
+    private reclaim;
+    private scheduleRetry;
+    private cancelRetry;
+    private resolveWaiters;
+    /** Resolve closeSession terminal waiters covered by this settle, once. */
+    private settleCloseTerminal;
+}
+//# sourceMappingURL=session-lifecycle.d.ts.map

package/dist/session-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lifecycle.d.ts","sourceRoot":"","sources":["../src/session-lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/session-lifecycle.js

@@ -0,0 +1,446 @@
+/**
+ * SessionLifecycleCoordinator — the single entry point for session status
+ * writes (active / idle / closed).
+ *
+ * SCOPE — this is a **process-local mitigation**, not a distributed fence.
+ * It serializes and orders the lifecycle writes THIS process issues. It does
+ * NOT order across processes, and it cannot fix a write that times out
+ * client-side but lands server-side later, nor an old turn's step retry
+ * landing during a new turn. The structural fix is a server-side turn fence
+ * (design tracked in #1879 — durable step outbox + turn fence); until that
+ * ships, this closes the in-process interleavings that produced the
+ * 2026-07-13 repro.
+ *
+ * The gateway used to fire active and idle PATCHes independently
+ * (fire-and-forget + detached retries). Two independent HTTP requests have
+ * no ordering: turn 1's in-flight idle could land AFTER turn 2's active and
+ * demote a running session — an epoch check on retry TIMERS cannot cancel a
+ * request already on the wire. The coordinator closes that class by being a
+ * serialized desired-state reconciler:
+ *
+ * - Per session it stores only the LATEST desired state plus a monotonic
+ *   generation (bumped by beginTurn and closeSession).
+ * - At most ONE lifecycle write is in flight per session; when it settles
+ *   the loop re-reads the latest desired state and reconciles — so a
+ *   begin(turn N+1), or a closeSession, that arrives while an earlier write
+ *   is in flight simply waits for it to settle and is written AFTER it.
+ * - finishTurn carries the TurnHandle from its beginTurn; a stale handle
+ *   (generation superseded) is ignored outright.
+ * - Retries re-run the reconcile loop against the LATEST desired state —
+ *   they never replay a captured command, so a pending idle retry is
+ *   naturally superseded by a new turn.
+ * - Errors are CLASSIFIED (ports, defaults are conservative): transient →
+ *   bounded backoff; permanent (4xx) → warn + abandon that desired state (a
+ *   later turn retries with a fresh generation); session-stale (the server
+ *   considers the session terminal) → drop the session, never write again.
+ * - beginTurn / closeSession resolve once one write attempt covering their
+ *   generation has SETTLED (success or failure — bounded by the write's own
+ *   timeout, plus at most one in-flight predecessor). The gateway awaits
+ *   beginTurn before persisting the turn's first AgentStep, so a reused idle
+ *   session is reconciled to active before steps arrive and the server's
+ *   presence guard cannot swallow the turn's activity. A failed active write
+ *   warns and lets the step flow continue.
+ * - closeSession's first settle carries a STRUCTURED outcome (`closed` /
+ *   `stale` / `retrying` / `permanent_failure` / `disposed`) plus a
+ *   `terminal` promise that resolves when the close reaches a terminal fate
+ *   — a caller holding cleanup behind the close (ForkSessionFinalizer) can
+ *   keep ownership through `retrying` instead of mistaking "one attempt
+ *   settled" for "close completed".
+ * - Entries are RECLAIMED (no unbounded Map growth on long-lived daemons):
+ *   dropSession removes the entry immediately when idle, or at the end of an
+ *   in-flight write; a `closed` that landed OR failed permanently reclaims
+ *   too — the permanent failure is not hidden by the reclaim, it is reported
+ *   through the close's outcome/terminal before the entry goes away.
+ * - dispose() is absorbing: every later public command is a no-op that never
+ *   re-creates an entry, issues a write, or arms a timer.
+ *
+ * The write port is infrastructure (ParallClient.updateAgentSession);
+ * retries, generations, error classification and the state machine live here.
+ */
+const DEFAULT_RETRY_DELAYS_MS = [5_000, 15_000, 45_000, 135_000, 405_000];
+const defaultScheduler = {
+    setTimeout(fn, ms) {
+        const timer = setTimeout(fn, ms);
+        timer.unref?.();
+        return timer;
+    },
+    clearTimeout(timer) {
+        clearTimeout(timer);
+    },
+};
+export class SessionLifecycleCoordinator {
+    opts;
+    sessions = new Map();
+    scheduler;
+    retryDelays;
+    // Generations are coordinator-global and strictly increasing, so a handle
+    // from before an entry was reclaimed can never match a REBUILT entry for
+    // the same session id (per-entry counters restart at 1 — an ABA hazard
+    // where a stale finish would demote a fresh turn).
+    nextGeneration = 0;
+    disposed = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.scheduler = opts.scheduler ?? defaultScheduler;
+        this.retryDelays = opts.retryDelaysMs?.length ? opts.retryDelaysMs : DEFAULT_RETRY_DELAYS_MS;
+    }
+    /** Sessions currently tracked — reclaimed entries are gone (leak probe). */
+    trackedSessions() {
+        return this.sessions.size;
+    }
+    /**
+     * Declare a new turn. Resolves once one write attempt covering this turn's
+     * generation has settled (bounded: at most one in-flight predecessor plus
+     * one active write, each bounded by the write port's own timeout). Always
+     * resolves — a failed active write is warned and reconciled in the
+     * background, never blocks the caller.
+     */
+    async beginTurn(sessionId, triggerMessageId) {
+        // Dispose is absorbing: never touch the map (an upsert here would
+        // re-create an entry nothing will ever reclaim), never write.
+        // Generation 0 can't match any live entry, so the handle is inert.
+        if (this.disposed)
+            return { sessionId, generation: 0 };
+        const entry = this.upsert(sessionId);
+        entry.desired = 'active';
+        entry.triggerMessageId = triggerMessageId;
+        const generation = entry.generation;
+        const settled = this.waitFor(entry, generation);
+        this.pump(sessionId);
+        await settled;
+        return { sessionId, generation };
+    }
+    /**
+     * Declare the turn finished. A stale handle (a newer turn — or a close —
+     * has bumped this session's generation) is ignored: finish(turn N) can
+     * never override begin(turn N+1). Reconciliation runs detached.
+     */
+    finishTurn(handle) {
+        if (this.disposed)
+            return;
+        const entry = this.sessions.get(handle.sessionId);
+        if (!entry || entry.dropped || entry.generation !== handle.generation)
+            return;
+        if (entry.desired === 'closed')
+            return;
+        entry.desired = 'idle';
+        entry.retryAttempt = 0;
+        this.cancelRetry(entry);
+        this.pump(handle.sessionId);
+    }
+    /**
+     * Terminal transition (fork teardown). Serialized behind any in-flight
+     * write — a `closed` can never race the turn's idle — and reclaimed once
+     * settled. Resolves after one bounded settle with a STRUCTURED outcome:
+     * `closed` / `stale` / `permanent_failure` are terminal; `retrying` means
+     * background reconciliation continues — the caller keeps ownership of the
+     * session until `terminal` resolves. A close is never silently "done":
+     * every fate is observable.
+     */
+    async closeSession(sessionId) {
+        if (this.disposed) {
+            return { outcome: 'disposed', terminal: Promise.resolve('disposed') };
+        }
+        const entry = this.upsert(sessionId);
+        entry.desired = 'closed';
+        entry.triggerMessageId = undefined;
+        const generation = entry.generation;
+        const terminal = new Promise((resolve) => {
+            entry.closeWaiters.push({ generation, resolve });
+        });
+        const settled = this.waitFor(entry, generation);
+        this.pump(sessionId);
+        const settle = await settled;
+        return { outcome: closeSettleFor(settle), terminal };
+    }
+    /**
+     * Session is dead (stale / superseded) — no further lifecycle writes, and
+     * the entry is reclaimed (immediately when idle; at the end of an in-flight
+     * write otherwise, unless a new turn revives it in the meantime).
+     */
+    dropSession(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            return;
+        entry.dropped = true;
+        this.cancelRetry(entry);
+        this.resolveWaiters(entry, Number.POSITIVE_INFINITY, 'dropped');
+        this.reclaim(sessionId, entry);
+    }
+    /** Every tracked session is dead (server closed them all — new_session). */
+    dropAllSessions() {
+        for (const sessionId of [...this.sessions.keys()])
+            this.dropSession(sessionId);
+    }
+    /**
+     * One best-effort reconcile pass over unsettled sessions within a hard
+     * deadline (shutdown). Returns the number still unsettled.
+     */
+    async flush(deadlineMs) {
+        const deadline = Date.now() + deadlineMs;
+        for (const [sessionId, entry] of [...this.sessions.entries()]) {
+            if (this.disposed)
+                break;
+            if (entry.dropped || this.isSettled(entry))
+                continue;
+            this.cancelRetry(entry);
+            entry.retryAttempt = 0;
+            const timeLeft = deadline - Date.now();
+            if (timeLeft <= 0)
+                break;
+            const settled = this.waitFor(entry, entry.generation);
+            this.pump(sessionId);
+            await raceWithDeadline(settled, timeLeft);
+        }
+        let remaining = 0;
+        for (const entry of this.sessions.values()) {
+            if (!entry.dropped && !this.isSettled(entry))
+                remaining += 1;
+        }
+        return remaining;
+    }
+    dispose() {
+        this.disposed = true;
+        for (const entry of this.sessions.values()) {
+            this.cancelRetry(entry);
+            this.resolveWaiters(entry, Number.POSITIVE_INFINITY, 'disposed');
+            this.settleCloseTerminal(entry, 'disposed');
+        }
+        this.sessions.clear();
+    }
+    // --- internals ----------------------------------------------------------
+    /**
+     * Get-or-create the entry and take the next generation. A dropped entry is
+     * REUSED (not replaced): its `writing` flag keeps the single-writer chain
+     * intact if a pre-drop write is still on the wire, and the generation stays
+     * monotonic across the drop boundary.
+     */
+    upsert(sessionId) {
+        let entry = this.sessions.get(sessionId);
+        if (!entry) {
+            entry = {
+                desired: 'active',
+                generation: 0,
+                writing: false,
+                retryAttempt: 0,
+                waiters: [],
+                closeWaiters: [],
+                dropped: false,
+            };
+            this.sessions.set(sessionId, entry);
+        }
+        entry.dropped = false;
+        this.nextGeneration += 1;
+        entry.generation = this.nextGeneration;
+        entry.retryAttempt = 0;
+        this.cancelRetry(entry);
+        return entry;
+    }
+    waitFor(entry, generation) {
+        return new Promise((resolve) => {
+            entry.waiters.push({ generation, resolve });
+        });
+    }
+    isReconciled(entry) {
+        return (entry.written !== undefined &&
+            entry.written.state === entry.desired &&
+            entry.written.generation === entry.generation);
+    }
+    isAbandoned(entry) {
+        return (entry.abandoned !== undefined &&
+            entry.abandoned.state === entry.desired &&
+            entry.abandoned.generation === entry.generation);
+    }
+    /** Nothing more to do for the current desired state (written or given up). */
+    isSettled(entry) {
+        return this.isReconciled(entry) || this.isAbandoned(entry);
+    }
+    pump(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry || entry.writing || entry.dropped || this.disposed)
+            return;
+        if (this.isSettled(entry)) {
+            this.resolveWaiters(entry, entry.generation, this.isReconciled(entry) ? 'ok' : 'permanent');
+            this.reclaim(sessionId, entry);
+            return;
+        }
+        entry.writing = true;
+        void this.writeLoop(sessionId, entry);
+    }
+    async writeLoop(sessionId, entry) {
+        try {
+            while (!entry.dropped && !this.disposed && !this.isSettled(entry)) {
+                const snapshot = {
+                    state: entry.desired,
+                    generation: entry.generation,
+                    trigger: entry.triggerMessageId,
+                };
+                let outcome = 'ok';
+                try {
+                    await this.opts.write(sessionId, payloadFor(snapshot));
+                    entry.written = { state: snapshot.state, generation: snapshot.generation };
+                    entry.retryAttempt = 0;
+                    if (snapshot.state === 'closed') {
+                        this.settleCloseTerminal(entry, 'closed', snapshot.generation);
+                    }
+                }
+                catch (err) {
+                    outcome = this.classify(err);
+                    this.opts.log?.warn(`session ${sessionId} ${snapshot.state} write failed (${outcome}, gen ${snapshot.generation}): ${String(err)}`);
+                }
+                // A settle — success or failure — resolves every waiter this
+                // snapshot covers (the bounded beginTurn / closeSession contract).
+                this.resolveWaiters(entry, snapshot.generation, outcome);
+                if (outcome === 'stale') {
+                    // Terminal server-side: never write to this session again.
+                    entry.dropped = true;
+                    this.cancelRetry(entry);
+                    this.settleCloseTerminal(entry, 'stale');
+                    this.resolveWaiters(entry, Number.POSITIVE_INFINITY, 'stale');
+                    return;
+                }
+                const desiredUnchanged = snapshot.generation === entry.generation && snapshot.state === entry.desired;
+                if (outcome === 'permanent' && desiredUnchanged) {
+                    // No retry loop against a 4xx — a later turn (fresh generation)
+                    // un-abandons this session automatically.
+                    entry.abandoned = { state: snapshot.state, generation: snapshot.generation };
+                    if (snapshot.state === 'closed') {
+                        this.settleCloseTerminal(entry, 'permanent_failure', snapshot.generation);
+                    }
+                    return;
+                }
+                if (outcome === 'retry' && desiredUnchanged && !entry.dropped && !this.disposed) {
+                    // The retry re-enters pump and replays the LATEST desired state,
+                    // never this snapshot.
+                    this.scheduleRetry(sessionId, entry);
+                    return;
+                }
+                // Success, or the desired state advanced while writing: loop and
+                // reconcile the fresh state immediately.
+            }
+        }
+        finally {
+            entry.writing = false;
+            this.reclaim(sessionId, entry);
+        }
+    }
+    classify(err) {
+        if (this.opts.isSessionStale?.(err))
+            return 'stale';
+        if (this.opts.isRetryable?.(err))
+            return 'retry';
+        return 'permanent';
+    }
+    /**
+     * Drop the entry when it can never write again: dropped (and no write on
+     * the wire), a terminal `closed` that landed, or a `closed` that failed
+     * permanently (its fate has been reported via closeSession's outcome — an
+     * entry kept around would be an unowned leak, not a recovery path). Called
+     * after every write settles and from dropSession — this is what keeps the
+     * Map bounded on a long-lived daemon churning fork sessions.
+     */
+    reclaim(sessionId, entry) {
+        if (this.sessions.get(sessionId) !== entry)
+            return;
+        if (entry.writing)
+            return; // the write's finally will re-run this
+        const closedLanded = entry.desired === 'closed' &&
+            entry.written?.state === 'closed' &&
+            entry.written.generation === entry.generation;
+        const closedAbandoned = entry.desired === 'closed' &&
+            entry.abandoned?.state === 'closed' &&
+            entry.abandoned.generation === entry.generation;
+        if (!entry.dropped && !closedLanded && !closedAbandoned)
+            return;
+        this.cancelRetry(entry);
+        this.settleCloseTerminal(entry, closedLanded ? 'closed' : entry.dropped ? 'stale' : 'permanent_failure');
+        this.resolveWaiters(entry, Number.POSITIVE_INFINITY, closedLanded ? 'ok' : entry.dropped ? 'dropped' : 'permanent');
+        this.sessions.delete(sessionId);
+    }
+    scheduleRetry(sessionId, entry) {
+        if (entry.retryTimer !== undefined)
+            return;
+        if (entry.retryAttempt >= this.retryDelays.length) {
+            this.opts.log?.warn(`session ${sessionId} lifecycle reconcile giving up after ${entry.retryAttempt} retries (desired=${entry.desired})`);
+            entry.abandoned = { state: entry.desired, generation: entry.generation };
+            if (entry.desired === 'closed') {
+                this.settleCloseTerminal(entry, 'permanent_failure');
+            }
+            return;
+        }
+        const delay = this.retryDelays[entry.retryAttempt] ?? 5_000;
+        entry.retryAttempt += 1;
+        entry.retryTimer = this.scheduler.setTimeout(() => {
+            entry.retryTimer = undefined;
+            this.pump(sessionId);
+        }, delay);
+    }
+    cancelRetry(entry) {
+        if (entry.retryTimer !== undefined) {
+            this.scheduler.clearTimeout(entry.retryTimer);
+            entry.retryTimer = undefined;
+        }
+    }
+    resolveWaiters(entry, upToGeneration, settle) {
+        if (entry.waiters.length === 0)
+            return;
+        const remaining = [];
+        for (const waiter of entry.waiters) {
+            if (waiter.generation <= upToGeneration)
+                waiter.resolve(settle);
+            else
+                remaining.push(waiter);
+        }
+        entry.waiters = remaining;
+    }
+    /** Resolve closeSession terminal waiters covered by this settle, once. */
+    settleCloseTerminal(entry, outcome, upToGeneration = Number.POSITIVE_INFINITY) {
+        if (entry.closeWaiters.length === 0)
+            return;
+        const remaining = [];
+        for (const waiter of entry.closeWaiters) {
+            if (waiter.generation <= upToGeneration)
+                waiter.resolve(outcome);
+            else
+                remaining.push(waiter);
+        }
+        entry.closeWaiters = remaining;
+    }
+}
+/** Map a first-settle write outcome onto the closeSession vocabulary. */
+function closeSettleFor(settle) {
+    switch (settle) {
+        case 'ok':
+            return 'closed';
+        case 'retry':
+            return 'retrying';
+        case 'stale':
+        case 'dropped':
+            return 'stale';
+        case 'disposed':
+            return 'disposed';
+        default:
+            return 'permanent_failure';
+    }
+}
+function payloadFor(snapshot) {
+    if (snapshot.state === 'active') {
+        return {
+            status: 'active',
+            ...(snapshot.trigger ? { trigger_message_id: snapshot.trigger } : {}),
+        };
+    }
+    return snapshot.state === 'idle' ? { status: 'idle' } : { status: 'closed' };
+}
+async function raceWithDeadline(work, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), Math.max(0, ms));
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/skills/parall-clips.d.ts

@@ -1,2 +1,2 @@
-export declare const PARALL_CLIPS_SKILL = "# Parall Clips\n\nClips are packaged capabilities that let agents operate external systems \u2014\nAPIs and websites \u2014 through named commands installed in the org.\n\n## Discover\n\n```bash\nparall clip list            # clips installed in this org\nparall clip info <alias>    # commands, params, version\n```\n\n## Invoke\n\n```bash\nparall clip invoke <alias> <command> [input] [--timeout <ms>]   # timeout default 30s\n# input: JSON string or plain text, per the command's params in `info`\nparall clip invoke github-tools list-repos '{\"org\":\"acme\"}'\n```\n\nResults are JSON on stdout; failures print an error.\n\n## Behavior rules\n\n- An authorization error (clip not bound to you) is a fail-fast: ask the\n  clip's owner or an admin to bind it \u2014 do not retry or work around it.\n- If the executing runtime is offline or the call times out, report that\n  plainly; do not queue, and never fabricate a result for a run that errored.\n- A clip may act through a person's real logged-in account \u2014 outward,\n  irreversible, or spending actions (post, order, delete, pay) get the same\n  caution as any shared-state change: confirm when intent isn't explicit.\n- Reach for `parall clip list` whenever a task needs capabilities beyond\n  built-in tools.\n";
+export declare const PARALL_CLIPS_SKILL = "# Parall Clips\n\nClips are packaged capabilities that let agents operate external systems \u2014\nAPIs and websites \u2014 through named commands installed in the org.\n\n## Discover\n\n```bash\nparall clip list            # clips installed in this org\nparall clip info <alias>    # commands, params, version\n```\n\n## Invoke\n\n```bash\nparall clip invoke <alias> <command> [input] [--timeout <ms>]   # timeout default 30s\n# input: JSON string or plain text, per the command's params in `info`\nparall clip invoke github-tools list-repos '{\"org\":\"acme\"}'\n```\n\nResults are JSON on stdout; failures print an error.\n\n## Behavior rules\n\n- An authorization error (clip not bound to you) is a fail-fast: ask the\n  clip's owner or an admin to bind it \u2014 do not retry or work around it.\n- If the executing runtime is offline or the call times out, report that\n  plainly; do not queue, and never fabricate a result for a run that errored.\n- Hosted browser activation is handled by the CLI: it waits (bounded) while a\n  cold hosted browser starts, so if the invoke still fails, report the error \u2014\n  do not blind-retry in a loop.\n- A clip may act through a person's real logged-in account \u2014 outward,\n  irreversible, or spending actions (post, order, delete, pay) get the same\n  caution as any shared-state change: confirm when intent isn't explicit.\n- Reach for `parall clip list` whenever a task needs capabilities beyond\n  built-in tools.\n";
 //# sourceMappingURL=parall-clips.d.ts.map

package/dist/skills/parall-clips.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parall-clips.d.ts","sourceRoot":"","sources":["../../src/skills/parall-clips.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,gwCAiC9B,CAAC"}
+{"version":3,"file":"parall-clips.d.ts","sourceRoot":"","sources":["../../src/skills/parall-clips.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,q8CAoC9B,CAAC"}

package/dist/skills/parall-clips.js

@@ -26,6 +26,9 @@ Results are JSON on stdout; failures print an error.
   clip's owner or an admin to bind it — do not retry or work around it.
 - If the executing runtime is offline or the call times out, report that
   plainly; do not queue, and never fabricate a result for a run that errored.
+- Hosted browser activation is handled by the CLI: it waits (bounded) while a
+  cold hosted browser starts, so if the invoke still fails, report the error —
+  do not blind-retry in a loop.
 - A clip may act through a person's real logged-in account — outward,
   irreversible, or spending actions (post, order, delete, pay) get the same
   caution as any shared-state change: confirm when intent isn't explicit.