@adhdev/mesh-shared 1.0.60-rc.44 → 1.0.60-rc.46

package/dist/turn-evidence.d.ts

@@ -42,6 +42,16 @@ export declare const DELIVERY_VIAS: readonly ["local", "p2p"];
 export type DeliveryVia = typeof DELIVERY_VIAS[number];
 export declare const DISPATCH_FAILURE_REASONS: readonly ["worker_absent", "transport_error", "spawn_failed", "rejected_by_worker", "timeout"];
 export type DispatchFailureReason = typeof DISPATCH_FAILURE_REASONS[number];
+/**
+ * Normalize a worker's own refusal code (e.g. `session_busy_with_task`,
+ * `mesh_sender_not_on_roster`, `provider_quota_exhausted`) into the shape
+ * `dispatch_failed.refusalCode` accepts: lowercase ascii + underscore, capped
+ * at 64 chars. Returns undefined for anything that yields no usable token, so
+ * a malformed/foreign code degrades to "no refusalCode" rather than smuggling
+ * arbitrary text through what must stay a closed-enum-like identifier slot
+ * (see the field's doc comment — this evidence replicates cross-machine).
+ */
+export declare function sanitizeRefusalCode(value: unknown): string | undefined;
 export declare const CONSUME_PROFILES: readonly ["default", "native_source"];
 export type ConsumeProfile = typeof CONSUME_PROFILES[number];
 export declare const SESSION_REBOUND_REASONS: readonly ["restart", "live_holder"];
@@ -87,7 +97,7 @@ export type NoProgressObservedStatus = SessionStatus | 'unknown';
  * Reasons a turn hold exists. Holds are attempt-scoped only (C2: delivery-side
  * waits are consumer deferral on the `turn.deliver` cursor, not hold rows).
  */
-export declare const HOLD_REASONS: readonly ["await_delivery", "await_consume", "await_turn", "liveness", "hard_ceiling", "live_pending", "transcript_quiet", "weak_candidate", "suspension_before_consumed", "await_report"];
+export declare const HOLD_REASONS: readonly ["await_delivery", "await_consume", "await_turn", "liveness", "hard_ceiling", "live_pending", "transcript_quiet", "weak_candidate", "suspension_before_consumed", "await_report", "await_end"];
 export type HoldReason = typeof HOLD_REASONS[number];
 export declare const TURN_OUTCOMES: readonly ["completed", "failed", "cancelled"];
 export type TurnOutcome = typeof TURN_OUTCOMES[number];
@@ -174,10 +184,25 @@ export type TurnEvidenceBody = {
     kind: 'delivery_refused';
     messageId: string;
     reason: SendRefusal;
-} | {
+}
+/**
+ * `refusalCode` (wiring-unification live-gap fix, 2026-09-25): the worker's own
+ * refusal code for an application-level `{success:false}` answer (e.g.
+ * `session_busy_with_task`, `mesh_sender_not_on_roster`,
+ * `mesh_node_bootstrap_pending`, `provider_quota_exhausted`) — optional and
+ * ONLY ever populated for `reason: 'rejected_by_worker'`. Deliberately an `id`
+ * (short enum-like token), never free text: this evidence replicates across
+ * machines over `mesh.<id>.events` (CONTENT-FREE BY CONSTRUCTION above), so a
+ * human-readable detail string must NOT travel here — it stays local (owner
+ * WARN log, MCP tool JSON response). Producers sanitize to `[a-z_]{1,64}`
+ * before emitting so a stray free-text code can never smuggle prose through
+ * this slot.
+ */
+ | {
     kind: 'dispatch_failed';
     workerAbsent: boolean;
     reason: DispatchFailureReason;
+    refusalCode?: string;
 } | {
     kind: 'duplicate_dispatch_refusal';
     holderSessionId: string;
@@ -240,10 +265,16 @@ export type TurnEvidenceBody = {
 } | {
     kind: 'session_error';
     reason: SessionErrorReason;
-} | {
+}
+/**
+ * `summary` is the handoff-topic pointer when the report's text was published;
+ * a report the owner daemon accepted itself carries its text in the evidence
+ * row's local envelope instead (never published), so the pointer is optional.
+ */
+ | {
     kind: 'worker_report';
     outcome: WorkerReportOutcome;
-    summary: SummaryRef;
+    summary?: SummaryRef;
     hasHandoffNotes: boolean;
     branchState?: WorkerBranchState;
     touchedFileCount?: number;
@@ -334,7 +365,7 @@ export declare const isEvidenceSourceId: (value: unknown) => value is "fsm_edge"
 export declare const isTurnEvidenceKind: (value: unknown) => value is "no_progress" | "delivered" | "liveness" | "turn_end" | "transcript_final" | "session_error" | "dispatch_failed" | "dispatch_accepted" | "delivery_refused" | "duplicate_dispatch_refusal" | "session_rebound" | "turn_started" | "suspension" | "suspension_resolved" | "transcript_activity" | "process_exit" | "worker_report" | "worker_progress" | "git_side_effect" | "cancel" | "operator_status" | "coordinator_ack" | "hold_expired";
 export declare const isTurnReason: (value: unknown) => value is "intentional_cleanup" | "operator_cancel" | "task_removed" | "mission_abandoned" | "superseded" | "operator_update" | "refine_terminal" | "validation_terminal" | "hard_ceiling" | "turn_end" | "weak_end_confirmed" | "transcript_final" | "worker_reported" | "finalization_timeout_no_response" | "session_error" | "provider_auth_failed" | "provider_billing_failed" | "reclaim_budget_exhausted" | "hollow_max_retries" | "migration_orphan" | "dispatch_refused_session_exited" | "dispatch_refused_no_target" | "dispatch_refused_unsupported_input" | "dispatch_failed" | "session_exit" | "session_exit_before_turn" | "session_dead" | "hollow_completion" | "assigned_stranded_dispatch_unconfirmed" | "delivered_not_consumed_redrive" | "delivered_no_turn_deadline";
 export declare const isNotifyKind: (value: unknown) => value is "stopped" | "failed" | "no_progress" | "completed" | "cancelled" | "approval" | "choice" | "approval_resolved" | "candidate" | "progress" | "late_completion" | "mesh_event";
-export declare const isHoldReason: (value: unknown) => value is "await_delivery" | "await_consume" | "await_turn" | "liveness" | "hard_ceiling" | "live_pending" | "transcript_quiet" | "weak_candidate" | "suspension_before_consumed" | "await_report";
+export declare const isHoldReason: (value: unknown) => value is "await_delivery" | "await_consume" | "await_turn" | "liveness" | "hard_ceiling" | "live_pending" | "transcript_quiet" | "weak_candidate" | "suspension_before_consumed" | "await_report" | "await_end";
 export declare const isTurnOutcome: (value: unknown) => value is "failed" | "completed" | "cancelled";
 export declare const isCommitStrength: (value: unknown) => value is "operator" | "genuine" | "weak" | "tool_report";
 export declare function isEvidenceIdentifier(value: unknown): value is string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/mesh-shared",
-  "version": "1.0.60-rc.44",
+  "version": "1.0.60-rc.46",
   "description": "ADHDev mesh-shared — pure mesh/git status normalizers shared by daemon-core and web-core",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/turn-evidence.ts

@@ -59,6 +59,22 @@ export type DeliveryVia = typeof DELIVERY_VIAS[number]
 export const DISPATCH_FAILURE_REASONS = ['worker_absent', 'transport_error', 'spawn_failed', 'rejected_by_worker', 'timeout'] as const
 export type DispatchFailureReason = typeof DISPATCH_FAILURE_REASONS[number]
 
+/**
+ * Normalize a worker's own refusal code (e.g. `session_busy_with_task`,
+ * `mesh_sender_not_on_roster`, `provider_quota_exhausted`) into the shape
+ * `dispatch_failed.refusalCode` accepts: lowercase ascii + underscore, capped
+ * at 64 chars. Returns undefined for anything that yields no usable token, so
+ * a malformed/foreign code degrades to "no refusalCode" rather than smuggling
+ * arbitrary text through what must stay a closed-enum-like identifier slot
+ * (see the field's doc comment — this evidence replicates cross-machine).
+ */
+export function sanitizeRefusalCode(value: unknown): string | undefined {
+    if (typeof value !== 'string') return undefined
+    const normalized = value.trim().toLowerCase().replace(/[^a-z_]/g, '_').replace(/_+/g, '_').replace(/^_+|_+$/g, '')
+    if (!normalized) return undefined
+    return normalized.slice(0, 64)
+}
+
 export const CONSUME_PROFILES = ['default', 'native_source'] as const
 export type ConsumeProfile = typeof CONSUME_PROFILES[number]
 
@@ -127,6 +143,12 @@ export const HOLD_REASONS = [
     // only opens this hold (R9r) — a report commits (R17), a new busy edge cancels
     // it as a false idle (R12r), expiry commits weak (R13r).
     'await_report',
+    // A worker report recorded while the session is still generating (R17g):
+    // the report is the verdict, the idle edge is only awaited as corroboration
+    // — a turn_end commits the report (R9t), expiry commits it anyway (R13t) so
+    // a session whose FSM never shows the idle edge again does not wait for
+    // liveness / hard_ceiling.
+    'await_end',
 ] as const
 export type HoldReason = typeof HOLD_REASONS[number]
 
@@ -208,7 +230,20 @@ export type TurnEvidenceBody =
         coordinator?: EvidenceCoordinatorIdentity }
     | { kind: 'delivered'; messageId: string; outcome: DeliveryOutcome; via: DeliveryVia }
     | { kind: 'delivery_refused'; messageId: string; reason: SendRefusal }
-    | { kind: 'dispatch_failed'; workerAbsent: boolean; reason: DispatchFailureReason }
+    /**
+     * `refusalCode` (wiring-unification live-gap fix, 2026-09-25): the worker's own
+     * refusal code for an application-level `{success:false}` answer (e.g.
+     * `session_busy_with_task`, `mesh_sender_not_on_roster`,
+     * `mesh_node_bootstrap_pending`, `provider_quota_exhausted`) — optional and
+     * ONLY ever populated for `reason: 'rejected_by_worker'`. Deliberately an `id`
+     * (short enum-like token), never free text: this evidence replicates across
+     * machines over `mesh.<id>.events` (CONTENT-FREE BY CONSTRUCTION above), so a
+     * human-readable detail string must NOT travel here — it stays local (owner
+     * WARN log, MCP tool JSON response). Producers sanitize to `[a-z_]{1,64}`
+     * before emitting so a stray free-text code can never smuggle prose through
+     * this slot.
+     */
+    | { kind: 'dispatch_failed'; workerAbsent: boolean; reason: DispatchFailureReason; refusalCode?: string }
     | { kind: 'duplicate_dispatch_refusal'; holderSessionId: string; holderAttemptId?: string }
     | { kind: 'session_rebound'; toSessionId: string; reason: SessionReboundReason }
     // ── worker turn lifecycle ──
@@ -232,7 +267,12 @@ export type TurnEvidenceBody =
     | { kind: 'process_exit'; exitCode: number | null; providerFailure?: ProviderFailure }
     | { kind: 'session_error'; reason: SessionErrorReason }
     // ── worker MCP (F2) ──
-    | { kind: 'worker_report'; outcome: WorkerReportOutcome; summary: SummaryRef; hasHandoffNotes: boolean
+    /**
+     * `summary` is the handoff-topic pointer when the report's text was published;
+     * a report the owner daemon accepted itself carries its text in the evidence
+     * row's local envelope instead (never published), so the pointer is optional.
+     */
+    | { kind: 'worker_report'; outcome: WorkerReportOutcome; summary?: SummaryRef; hasHandoffNotes: boolean
         branchState?: WorkerBranchState; touchedFileCount?: number }
     | { kind: 'worker_progress'; note?: SummaryRef }
     // ── coordinator / operator ──
@@ -298,7 +338,7 @@ export const TURN_EVIDENCE_FIELD_SPECS: TurnEvidenceFieldSpecs = {
     },
     delivered: { messageId: id, outcome: en(DELIVERY_OUTCOMES), via: en(DELIVERY_VIAS) },
     delivery_refused: { messageId: id, reason: en(SEND_REFUSAL_REASONS) },
-    dispatch_failed: { workerAbsent: bool, reason: en(DISPATCH_FAILURE_REASONS) },
+    dispatch_failed: { workerAbsent: bool, reason: en(DISPATCH_FAILURE_REASONS), refusalCode: idOpt },
     duplicate_dispatch_refusal: { holderSessionId: id, holderAttemptId: idOpt },
     session_rebound: { toSessionId: id, reason: en(SESSION_REBOUND_REASONS) },
     turn_started: { retro: bool },
@@ -320,7 +360,7 @@ export const TURN_EVIDENCE_FIELD_SPECS: TurnEvidenceFieldSpecs = {
     process_exit: { exitCode: { t: 'int', nullable: true }, providerFailure: enOpt(PROVIDER_FAILURES) },
     session_error: { reason: en(SESSION_ERROR_REASONS) },
     worker_report: {
-        outcome: en(WORKER_REPORT_OUTCOMES), summary: { t: 'summary_ref' }, hasHandoffNotes: bool,
+        outcome: en(WORKER_REPORT_OUTCOMES), summary: { t: 'summary_ref', optional: true }, hasHandoffNotes: bool,
         branchState: enOpt(WORKER_BRANCH_STATES), touchedFileCount: intOpt,
     },
     worker_progress: { note: { t: 'summary_ref', optional: true } },