@cotal-ai/connector-jcode 0.48.2 → 0.50.0

package/dist/queue-fallback.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Serving policy for automatic deliveries a busy Jcode session has not accepted yet (#1233).
+ *
+ * Every path that hands a queued peer message to the live session is EDGE-TRIGGERED: a new
+ * `incoming` while the session is busy, or an idle transition at the end of a turn. When the
+ * mid-turn handoff (`soft_interrupt`) rejects — the measured case is the SDK's 30s request timeout
+ * — the catch logs and returns, and both edges can then be absent indefinitely: no further message
+ * arrives, and the session never reports idle. The queue is served by nothing, the seat stays
+ * healthy and productive, and its automatic depth is static while the oldest age grows. Measured
+ * live at 27 queued for 13.8 hours on a seat that answered a DM in under a minute.
+ *
+ * The repair is a LEVEL-TRIGGERED serving loop: while automatic work is owed, something re-attempts
+ * delivery on its own schedule rather than waiting for an edge that may never come. This module is
+ * the decision that loop makes, extracted so it can be graded directly — every accepting branch AND
+ * its refusal — rather than only through a live seat, exactly as `retry-policy.ts` was for #790.
+ *
+ * TWO DELIVERY PATHS, and the second is the point. `steer` is the existing mid-turn handoff, which
+ * needs a `soft_interrupt` reply. `queue-turn` needs no such reply: the Harness accepts an ordinary
+ * message while the agent is busy, acknowledges it with `message_accepted`, and runs it as a turn
+ * when the current one ends. So a soft interrupt that never answers can no longer strand the queue,
+ * because the fallback does not ask it anything.
+ *
+ * IT NEVER DROPS. No branch here discards a delivery: losing a peer's message is worse than
+ * delivering it late, so the only bound is pacing. The one refusal that persists is the turn-level
+ * give-up (#790), which leaves the batch UN-ACKED and therefore redeliverable rather than acking
+ * work the seat never saw — and which the reported connection state now refuses to call `ready`.
+ */
+/**
+ * Whether a REFUSED queued turn must force a connection boundary before the batch is re-delivered.
+ *
+ * BOTH OBVIOUS ANSWERS ARE WRONG AND EACH WAS MEASURED BY A REVIEWER, so the discriminator is
+ * neither flag but whether the thing blocking attribution CAN CLEAR ON ITS OWN.
+ *
+ * Trigger only on `!acknowledged` and a run-debt duplicate survives: a run whose acceptance window
+ * lapsed owes debt until that TURN ends, while the fallback's own sends are genuinely acknowledged,
+ * so the batch is refused, stays owed, and is re-delivered into a healthy Harness that accepts and
+ * RUNS each copy. Measured at 4 executions from 4 send frames.
+ *
+ * Trigger on every refusal and a live run becomes silent starvation: inside the refusal arm
+ * `!acknowledged || !attributable` is TAUTOLOGICALLY TRUE, so that spelling is `= true` with extra
+ * steps. It suppresses every write until the bridge is replaced, and with a turn held open for
+ * minutes the batch cannot reach the seat at all. Measured at 0 executions from 0 send frames.
+ *
+ * So the question is what owes the debt. A RUN settles its own promise when the turn ends, which
+ * genuinely proves the Harness is finished with that request, so attribution returns WITHOUT a
+ * boundary and waiting is correct: the batch is late by one turn, not lost. A LAPSED SEND settles
+ * nothing, because the SDK resolved it on its own accept timeout while the request stayed live at
+ * the Harness; no amount of waiting restores attribution, so only replacing the connection can.
+ *
+ * `unsettledRunDispatches` is therefore the self-clearing kind and must NOT force a boundary. But
+ * waiting alone is not enough either, because that is precisely the state sol measured duplicating:
+ * a send issued while a run is open CAN NEVER BE ATTRIBUTED, so it is refused every time and the
+ * loop re-sends it forever, and each refused copy was still ACCEPTED AND RUN by the Harness. The
+ * answer is to not issue it at all. See {@link attributionBlockedByOpenRun}: the batch is deferred,
+ * no frame is written, and the send happens once after the turn ends, when it can be attributed.
+ */
+export declare function refusalNeedsBoundary(sendLapsed: boolean): boolean;
+/**
+ * Whether a queued-turn send must be DEFERRED because no acknowledgement it receives could be
+ * attributed to it.
+ *
+ * This is the half that stops the duplicate at its source rather than cleaning up after it. While a
+ * run's acceptance window has lapsed, `message_accepted` carries only a session id, so an event
+ * arriving now may belong to that run. A send issued into that window is therefore refused on
+ * arrival no matter how healthy it was, stays owed, and is re-sent on the next tick, while the
+ * Harness accepts and EXECUTES every copy: 4 executions from 4 send frames.
+ *
+ * Not writing is what prevents it, and it costs only latency: the run's own promise settles when the
+ * turn ends, which genuinely proves the Harness is done with that request, so the very next tick can
+ * send once and attribute the answer. Late by one turn, delivered exactly once, and no connection
+ * replacement is involved, so a live turn can never suppress the queue for its whole duration or end
+ * in the seat shutting down once recovery is spent.
+ *
+ * THE DEFERRAL MUST BE BOUNDED OR IT IS THE ORIGINAL BUG AGAIN, which a reviewer put precisely: run
+ * debt clears only when `run()` settles, and a turn that missed its acceptance AND never completes
+ * settles nothing, so an unbounded deferral starves the queue exactly as the un-fallen-back stall
+ * did. Nothing in the protocol bounds a turn's duration, so waiting on one is waiting on an edge
+ * that may never come, which is the defect this whole tier exists to remove.
+ *
+ * So the deferral expires. Past {@link DEFERRAL_MAX_MS} the run is treated as unsettleable rather
+ * than merely slow, which is the LAPSED-SEND case, and it takes that case's answer: force the
+ * connection boundary, which ends the ambiguity at the root because a replaced bridge cannot deliver
+ * an event for a request made on the old one. The bound is generous enough that an ordinary long
+ * turn defers and delivers late rather than reconnecting, and finite so a wedged one cannot defer
+ * forever. Delivery is late, bounded, and exactly once in every branch.
+ *
+ * NOT GRADED BY A LIVE CELL, AND SAYING SO RATHER THAN IMPLYING OTHERWISE. A mutation severing the
+ * call site SURVIVED the loss suite: that suite's A is a swallowed SEND, not an open unacknowledged
+ * RUN, so the deferral is never consulted there. I then built the run-debt cell (the fixture knob
+ * `FAKE_JCODE_RUN_WITHOUT_ACCEPT_ON_CONTENT` exists for it) and it PASSED WITH THE DEFERRAL SEVERED,
+ * because `nextFallbackAction` takes `drive` on an idle seat and only reaches `queue-turn` on the
+ * busy branch after a soft interrupt has failed, so my probe measured a path the defect cannot
+ * touch. I deleted the mutation instead of keeping one whose SURVIVED verdict I could not turn into
+ * a red, and left the knob so the next attempt starts further along. The behaviour here is covered
+ * by the policy cells and by a reviewer's live reproduction, NOT by a mutation-graded live cell.
+ */
+export declare function attributionBlockedByOpenRun(unsettledRunDispatches: number, blockedForMs?: number): boolean;
+/**
+ * How long a send may be deferred for an open run before that run is treated as unsettleable.
+ *
+ * Five minutes is longer than any acceptance round trip and longer than the ordinary long turns this
+ * connector serves, so a healthy slow turn is never mistaken for a wedged one, while a genuinely
+ * hung run cannot hold the queue past it. It is deliberately much larger than the 60s fallback
+ * ceiling: the pacing loop re-attempts throughout, and only the write is withheld.
+ */
+export declare const DEFERRAL_MAX_MS: number;
+/**
+ * Whether a deferral has outlived its bound, so the open run must be treated as unsettleable and the
+ * connection boundary forced. The exact complement of the deferral's second condition, kept as its
+ * own name so the call site reads as the decision it is rather than as a comparison.
+ */
+export declare function deferralExhausted(unsettledRunDispatches: number, blockedForMs: number): boolean;
+/**
+ * What an EXHAUSTED deferral should do, which is a three-way decision and not a two-way one.
+ *
+ * Both obvious answers were measured harmful by reviewers, one of them after I had already written
+ * it. Forcing the boundary when the one-shot recovery is spent does not replace anything: it calls
+ * `shutdown(1)` and the seat exits, so a starvation report is answered by killing the seat. And
+ * continuing to WRITE is the same defect as doing nothing: the send is refused as unattributable,
+ * the batch stays owed, and the loop re-sends once a minute while the Harness accepts and RUNS each
+ * copy, bounded only by how long the run stays open, which is to say not bounded.
+ *
+ * So the third outcome is the #790 give-up's: STOP ATTEMPTING, leave the batch owed and un-acked. No
+ * frame is written so the instruction cannot execute again, nothing is acked so the durable copy
+ * redelivers elsewhere, and the reported connection state stops calling the seat `ready`. Terminal
+ * for the SEAT's queued-turn tier, never for the MESSAGE.
+ */
+export type ExhaustedDeferralAction = "replace-bridge" | "stop-attempting";
+export declare function exhaustedDeferralAction(bridgeRecoveryAvailable: boolean): ExhaustedDeferralAction;
+/** First delay after work is owed. Short, because most stalls clear on the next attempt. */
+export declare const FALLBACK_INITIAL_MS = 1000;
+/** Ceiling on the delay. One attempt a minute against a session that is not accepting. */
+export declare const FALLBACK_MAX_MS = 60000;
+/**
+ * What the serving loop should do on this tick.
+ *
+ * - `drive` — run an ordinary turn carrying the queued batch. Only when the session is not busy.
+ * - `steer` — attempt the mid-turn handoff into the live session.
+ * - `queue-turn` — the fallback: hand the batch to the Harness as an ordinary message, which it
+ *   accepts while busy and runs as its own turn. Needs no `soft_interrupt` reply.
+ * - `wait` — nothing can be attempted right now; stay armed and look again later.
+ * - `stop` — this host is shutting down; disarm.
+ */
+export type FallbackAction = "drive" | "steer" | "queue-turn" | "wait" | "stop";
+export interface FallbackState {
+    /** The host is shutting down. */
+    stopping: boolean;
+    /** The queued-turn tier has terminalized: an unsettleable run with no bridge recovery left. The
+     *  batch stays owed and un-acked, but nothing here will attempt it again, so the loop disarms
+     *  rather than re-deriving the same terminal decision once a minute forever. */
+    queuedTurnTierStopped: boolean;
+    /** A bridge replacement owns the session; it redrives the durable batch itself. */
+    reconnecting: boolean;
+    /** Startup has finished its readiness proof and post-join notice. */
+    initialized: boolean;
+    /** A live Harness client and session id are both held. */
+    hasSession: boolean;
+    /** `driving || turnActive`: a turn owns the provider. */
+    sessionBusy: boolean;
+    /** A `soft_interrupt` is already in flight; a second would race its own ledger. */
+    steering: boolean;
+    /** A `soft_interrupt` has failed since the last accepted handoff — the #1233 trigger. */
+    softInterruptFailed: boolean;
+    /** Automatic deliveries the live session has NOT accepted yet. */
+    unserved: number;
+    /** The host's own drive predicate: a kickoff, a pending wake, or a queued wake. */
+    driveWork: boolean;
+    /** Consecutive failed turns, for the #790 give-up bound. */
+    consecutiveFailures: number;
+    /** The #790 bound itself, passed in so this module owns no copy of it. */
+    giveUpAfter: number;
+}
+export interface FallbackDecision {
+    action: FallbackAction;
+    /** Why, so a refusal is attributable rather than an unexplained `wait`. */
+    reason: "stopping" | "not-initialized" | "no-session" | "reconnecting" | "turn-work" | "gave-up" | "mid-turn-handoff" | "soft-interrupt-timed-out" | "steer-in-flight" | "nothing-owed";
+}
+/**
+ * The next action for the serving loop.
+ *
+ * ORDER IS MEANING. Shutdown outranks everything (a retry into a child being torn down is the
+ * hazard, not the queue). An unfinished startup and a bridge replacement both already own a redrive
+ * of the same durable batch, so attempting one here would race theirs. Only then does the queue's
+ * own state decide: an idle session takes the whole batch as its own turn, a busy one gets the
+ * mid-turn handoff — or, once that handoff has failed, the fallback that does not depend on it.
+ */
+export declare function nextFallbackAction(s: FallbackState): FallbackDecision;
+/** The next delay, doubling from `current` and clamped at the ceiling. */
+export declare function nextFallbackDelay(current: number): number;
+/**
+ * Whether the loop must stay armed.
+ *
+ * Deliberately NOT the same question as {@link nextFallbackAction}. A tick that can do nothing right
+ * now (startup, a bridge replacement, the #790 bound) still owes the queue, and disarming on a
+ * temporary refusal is precisely how an edge-triggered server strands a message. Only shutdown, an
+ * empty ledger, and TERMINALIZATION end the loop.
+ *
+ * The third one is a reviewer's catch. Once the queued-turn tier has stopped attempting, every later
+ * tick re-derives the same terminal decision, writes nothing and re-arms, so the timer runs once a
+ * minute forever against a tier that will never act again. Nothing is lost by that, but a terminal
+ * state that keeps a timer alive is not terminal, it is a quiet loop, and this connector's whole
+ * argument is that invisible background activity is what let #1233 hide. Disarming here is safe
+ * because the flag is cleared only by a bridge replacement, which re-arms the loop itself.
+ */
+export declare function fallbackStillOwed(s: FallbackState): boolean;
+//# sourceMappingURL=queue-fallback.d.ts.map

package/dist/queue-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-fallback.d.ts","sourceRoot":"","sources":["../src/queue-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,OAAO,GAAG,OAAO,CAEjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,2BAA2B,CAAC,sBAAsB,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,OAAO,CAGrG;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,QAAsB,CAAC;AAsBnD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,sBAAsB,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAE/F;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAE3E,wBAAgB,uBAAuB,CAAC,uBAAuB,EAAE,OAAO,GAAG,uBAAuB,CAEjG;AAED,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AACzC,0FAA0F;AAC1F,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB;;oFAEgF;IAChF,qBAAqB,EAAE,OAAO,CAAC;IAC/B,mFAAmF;IACnF,YAAY,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,WAAW,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAC;IACpB,yDAAyD;IACzD,WAAW,EAAE,OAAO,CAAC;IACrB,mFAAmF;IACnF,QAAQ,EAAE,OAAO,CAAC;IAClB,yFAAyF;IACzF,mBAAmB,EAAE,OAAO,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,2EAA2E;IAC3E,MAAM,EACF,UAAU,GACV,iBAAiB,GACjB,YAAY,GACZ,cAAc,GACd,WAAW,GACX,SAAS,GACT,kBAAkB,GAClB,0BAA0B,GAC1B,iBAAiB,GACjB,cAAc,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,aAAa,GAAG,gBAAgB,CAmBrE;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAI3D"}

package/dist/route-identity.d.ts

@@ -1,12 +1,11 @@
 /**
  * Say which provider is actually carrying a seat's model.
  *
- * The connector already refuses to join under a model label it did not receive, and that guarantee
- * stopped at the model. A seat could be truthfully labelled with the model an operator asked for
- * while its traffic was carried by a component nobody named: one seat was requested as a given
- * model, logged every line under a different provider's name, and died inside a third component's
- * plugin. Nothing in the roster, the spawn confirmation, or the manager's exit line named the route,
- * so establishing it meant reading the seat's private log by hand (#785).
+ * A seat can be pinned to the model an operator asked for while its traffic is carried by a component
+ * nobody named: one seat was requested as a given model, logged every line under a different
+ * provider's name, and died inside a third component's plugin. Nothing in the roster, the spawn
+ * confirmation, or the manager's exit line named the route, so establishing it meant reading the
+ * seat's private log by hand (#785).
  *
  * `RuntimeInfo` carries `provider` and `routes` in the same response the model check already reads,
  * so this is a reporting gap, not a discovery problem.
@@ -25,13 +24,15 @@ export interface RuntimeIdentity {
     providers?: string[];
     routes?: RouteInfo[];
 }
+/** The route serving `model`. RuntimeInfo's active provider disambiguates duplicate model ids. */
+export declare function activeModelRoute(runtime: RuntimeIdentity | undefined, model: string): RouteInfo | undefined;
 /**
  * One line naming the effective route for `model`.
  *
- * The route matching the requested model wins, because `runtime.provider` is the session default and
- * can differ from the provider actually serving this model. When neither is known the line says so
- * explicitly rather than guessing or going quiet: an unknown route is itself worth reporting, since
- * silence is what made this expensive to diagnose.
+ * The requested pin selects the model whose route is described. RuntimeInfo.model can lag behind a
+ * successful setModel, while RuntimeInfo.provider identifies the active route among duplicate model
+ * ids. When no matching route is known, the provider remains useful diagnostic context. When neither
+ * is known the line says so explicitly rather than guessing or going quiet.
  */
 export declare function describeRoute(runtime: RuntimeIdentity | undefined, model: string): string;
 /**

package/dist/route-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-identity.d.ts","sourceRoot":"","sources":["../src/route-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,uFAAuF;AACvF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOzF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAIrG"}
+{"version":3,"file":"route-identity.d.ts","sourceRoot":"","sources":["../src/route-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,uFAAuF;AACvF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;CACtB;AAED,kGAAkG;AAClG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAG3G;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOzF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAIrG"}

package/dist/startup-diagnostics.d.ts

@@ -1,9 +1,16 @@
-export type JcodeConnectorFailureCode = "model_prefix_rejected" | "model_refused" | "model_mismatch" | "private_state" | "readiness_timeout";
+export type JcodeConnectorFailureCode = "model_prefix_rejected" | "model_refused" | "model_mismatch" | "private_state" | "readiness_timeout" | "sessions_enumeration_failed";
 /** A bounded connector-owned startup refusal. Only its allow-listed code is rendered publicly. */
 export declare class JcodeConnectorError extends Error {
     readonly code: JcodeConnectorFailureCode;
     constructor(code: JcodeConnectorFailureCode, message: string, options?: ErrorOptions);
 }
+/** Listing stored sessions killed the harness. Cause and path are connector-owned, not child stderr. */
+export declare class JcodeSessionsEnumerationFailure extends Error {
+    readonly sessionsPath: string;
+    readonly causeText: string;
+    readonly code: "sessions_enumeration_failed";
+    constructor(sessionsPath: string, causeText: string);
+}
 /** Start the per-seat connector diagnostic log before any private Jcode process is launched. */
 export declare function installJcodeDiagnosticLog(home: string): string;
 /** Write one connector-owned diagnostic to the terminal and the seat's private connector log. */
@@ -23,21 +30,31 @@ export declare class JcodeReadinessProviderRefusal extends Error {
 export declare class JcodeEffortRefusal extends Error {
     readonly requestedTier: string;
     readonly effectiveModel: string;
+    readonly provider: string;
+    readonly apiMethod: string | undefined;
     readonly acceptedLadder: readonly string[];
     readonly providerCode = "invalid_request";
-    constructor(requestedTier: string, effectiveModel: string, acceptedLadder: readonly string[]);
+    constructor(requestedTier: string, effectiveModel: string, provider: string, apiMethod: string | undefined, acceptedLadder: readonly string[]);
+}
+/** A verified model route whose provider/profile has no reasoning-effort surface. */
+export declare class JcodeEffortUnsupported extends Error {
+    readonly requestedTier: string;
+    readonly effectiveModel: string;
+    readonly provider: string;
+    readonly apiMethod: string | undefined;
+    constructor(requestedTier: string, effectiveModel: string, provider: string, apiMethod: string | undefined);
 }
 /** Compose a bounded effort-refusal diagnostic. `invalid_request` is intentionally fixed: Jcode
  * rejected this API operation, while provider-supplied codes and text are untrusted. */
-export declare function jcodeEffortRefusal(error: unknown, requestedTier: string, effectiveModel: string): JcodeEffortRefusal;
-/**
- * The model an effort-refusal diagnostic may name.
- *
- * Prefer the operator pin. RuntimeInfo can still report the session default after `setModel`
- * (measured: a CLI spawn that died on a variant-tier refusal recorded deepseek-v4-pro despite
- * `--model grok-4.6`). Fall back to RuntimeInfo only when no pin was requested.
- */
-export declare function effortRefusalModel(requested: string | undefined, runtime: string | undefined): string;
+export interface JcodeEffortIdentity {
+    model: string;
+    provider: string;
+    apiMethod?: string;
+}
+/** Classify the two stable invalid-request outcomes without rendering downstream text. HarnessError
+ * prefixes its message with the stable code, so the anchored `invalid_request:` predicate below is
+ * also the code gate; a second `error.code` check would be redundant. */
+export declare function jcodeEffortRefusal(error: unknown, requestedTier: string, identity: JcodeEffortIdentity): JcodeEffortRefusal | JcodeEffortUnsupported;
 /**
  * Classify only the Jcode SDK's invalid-request response and only when both fields are safely
  * extractable. Everything else retains the existing scrubbed startup diagnostic.

package/dist/startup-diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"startup-diagnostics.d.ts","sourceRoot":"","sources":["../src/startup-diagnostics.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,yBAAyB,GACjC,uBAAuB,GACvB,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,mBAAmB,CAAC;AAExB,kGAAkG;AAClG,qBAAa,mBAAoB,SAAQ,KAAK;IAChC,QAAQ,CAAC,IAAI,EAAE,yBAAyB;gBAA/B,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAG9F;AAID,gGAAgG;AAChG,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoB9D;AAED,iGAAiG;AACjG,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG1D;AAED;;mGAEmG;AACnG,qBAAa,6BAA8B,SAAQ,KAAK;IAEpD,QAAQ,CAAC,YAAY,EAAE,MAAM;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,kBAAkB;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAFb,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,OAAO,GAAG,kBAAkB,EACvC,KAAK,EAAE,MAAM;CAIzB;AAED;;4CAE4C;AAC5C,qBAAa,kBAAmB,SAAQ,KAAK;IAIzC,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE;IAL5C,QAAQ,CAAC,YAAY,qBAAqB;gBAG/B,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,SAAS,MAAM,EAAE;CAI7C;AAsDD;wFACwF;AACxF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,kBAAkB,CAEpH;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAErG;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,6BAA6B,GAAG,SAAS,CAM1G"}
+{"version":3,"file":"startup-diagnostics.d.ts","sourceRoot":"","sources":["../src/startup-diagnostics.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,yBAAyB,GACjC,uBAAuB,GACvB,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,mBAAmB,GACnB,6BAA6B,CAAC;AAElC,kGAAkG;AAClG,qBAAa,mBAAoB,SAAQ,KAAK;IAChC,QAAQ,CAAC,IAAI,EAAE,yBAAyB;gBAA/B,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAG9F;AAED,wGAAwG;AACxG,qBAAa,+BAAgC,SAAQ,KAAK;IAItD,QAAQ,CAAC,YAAY,EAAE,MAAM;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM;IAJ5B,QAAQ,CAAC,IAAI,EAAG,6BAA6B,CAAU;gBAG5C,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM;CAI7B;AAID,gGAAgG;AAChG,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoB9D;AAED,iGAAiG;AACjG,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG1D;AAED;;mGAEmG;AACnG,qBAAa,6BAA8B,SAAQ,KAAK;IAEpD,QAAQ,CAAC,YAAY,EAAE,MAAM;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,kBAAkB;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAFb,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,OAAO,GAAG,kBAAkB,EACvC,KAAK,EAAE,MAAM;CAIzB;AAED;;4CAE4C;AAC5C,qBAAa,kBAAmB,SAAQ,KAAK;IAIzC,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS;IACtC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE;IAP5C,QAAQ,CAAC,YAAY,qBAAqB;gBAG/B,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,cAAc,EAAE,SAAS,MAAM,EAAE;CAI7C;AAED,qFAAqF;AACrF,qBAAa,sBAAuB,SAAQ,KAAK;IAE7C,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS;gBAH7B,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS;CAIzC;AAsDD;wFACwF;AACxF,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;yEAEyE;AACzE,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,mBAAmB,GAC5B,kBAAkB,GAAG,sBAAsB,CAc7C;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,6BAA6B,GAAG,SAAS,CAM1G"}

package/dist/stored-sessions.d.ts

@@ -0,0 +1,41 @@
+export declare function storedSessionsPath(jcodeHome: string): string;
+export type StoredSessionsInspection = {
+    kind: "absent";
+    path: string;
+} | {
+    kind: "empty-directory";
+    path: string;
+} | {
+    kind: "populated";
+    path: string;
+    entries: number;
+} | {
+    kind: "not-a-directory";
+    path: string;
+} | {
+    kind: "unreadable";
+    path: string;
+    code: string;
+};
+/**
+ * A local read of the seat's own `sessions/` directory. This runs on the startup path of every
+ * managed seat, so it must never throw: a home the connector cannot read is a question for the
+ * harness, not a reason to kill a seat that would otherwise start. Both reads here can fail on a
+ * home whose permissions were perturbed from outside (operator chmod, restored backup, container
+ * UID remap): `lstat` when the home itself is unreadable, `readdir` when only `sessions/` is.
+ * Anything but a real empty directory falls through to the ordinary listing attempt.
+ */
+export declare function inspectStoredSessions(jcodeHome: string): StoredSessionsInspection;
+/** True only for a real empty directory. A missing directory is a first launch, not this defect. */
+export declare function isEmptyStoredSessionsDirectory(inspection: StoredSessionsInspection): boolean;
+export declare function classifyStoredSessionPanic(stderr: string): string | undefined;
+/**
+ * Operator-facing cause: allow-listed phrases only, never arbitrary child bytes.
+ *
+ * The fallback is deliberately non-committal. Naming a specific cause for text we do not
+ * recognise sends the operator to the wrong place: an out-of-memory spawn failure rendered as
+ * "harness connection closed" points at sockets. An unrecognised cause is reported as such.
+ */
+export declare const UNRECOGNISED_STORED_SESSION_CAUSE = "unrecognised harness failure";
+export declare function boundStoredSessionCause(text: string): string;
+//# sourceMappingURL=stored-sessions.d.ts.map

package/dist/stored-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored-sessions.d.ts","sourceRoot":"","sources":["../src/stored-sessions.ts"],"names":[],"mappings":"AAYA,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,wBAAwB,CAajF;AAED,oGAAoG;AACpG,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,wBAAwB,GAAG,OAAO,CAE5F;AAaD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,iCAAiC,CAAC;AAEhF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK5D"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cotal-ai/connector-jcode",
   "description": "Cotal connector for Jcode: a host-mode mesh peer driven through Jcode's Harness API bridge.",
-  "version": "0.48.2",
+  "version": "0.50.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -29,9 +29,9 @@
     "esbuild": "^0.28.0",
     "tsx": "^4.22.4",
     "zod": "^4.4.3",
-    "@cotal-ai/core": "0.48.2",
-    "@cotal-ai/smoke-kit": "0.0.0",
-    "@cotal-ai/connector-core": "0.48.2"
+    "@cotal-ai/connector-core": "0.50.0",
+    "@cotal-ai/core": "0.50.0",
+    "@cotal-ai/smoke-kit": "0.0.0"
   },
   "files": [
     "dist"