@adhdev/mesh-shared 1.0.60-rc.40 → 1.0.60-rc.42

package/dist/turn-evidence.d.ts

@@ -87,7 +87,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"];
+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 type HoldReason = typeof HOLD_REASONS[number];
 export declare const TURN_OUTCOMES: readonly ["completed", "failed", "cancelled"];
 export type TurnOutcome = typeof TURN_OUTCOMES[number];
@@ -207,6 +207,13 @@ export type TurnEvidenceBody = {
     releasedByHardCap?: boolean;
     nativeOutcome?: NativeTurnOutcome;
     live?: LiveTurnPending;
+    /**
+     * Stamped (true only) by the WORKER's daemon when the session holds a live
+     * worker-MCP session bind, i.e. the worker can call report_completion. The
+     * owner then treats a genuine end as a report-awaiting candidate (R9r), not
+     * a commit. Absent = no reporting surface = today's genuine-end commit.
+     */
+    reportExpected?: boolean;
 } | {
     kind: 'transcript_final';
     selfAttributing: boolean;
@@ -327,7 +334,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";
+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 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/dist/types.d.ts

@@ -136,4 +136,15 @@ export interface RepoMeshSessionStatus {
     startedAt?: string | null;
     lastActivityAt?: string | null;
     isCached?: boolean;
+    /**
+     * Worker MCP delivery outcome for this session's launch (present only for a
+     * mesh-delegated launch). `reason` is a short enum code, never free text —
+     * see `WORKER_MCP_DELIVERY_REASONS` (daemon-core's `mesh/worker-mcp-isolation.ts`,
+     * the source of the vocabulary this field's values are drawn from; not
+     * re-exported here so mesh-shared stays a dependency-free leaf).
+     */
+    workerMcp?: {
+        delivered: boolean;
+        reason?: string;
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/mesh-shared",
-  "version": "1.0.60-rc.40",
+  "version": "1.0.60-rc.42",
   "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

@@ -122,6 +122,11 @@ export type NoProgressObservedStatus = SessionStatus | 'unknown'
 export const HOLD_REASONS = [
     'await_delivery', 'await_consume', 'await_turn', 'liveness', 'hard_ceiling',
     'live_pending', 'transcript_quiet', 'weak_candidate', 'suspension_before_consumed',
+    // A genuine FSM end of a mesh turn whose worker holds a live worker-MCP bind:
+    // the structured report is the primary evidence (design §F2), so the idle edge
+    // 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',
 ] as const
 export type HoldReason = typeof HOLD_REASONS[number]
 
@@ -211,7 +216,14 @@ export type TurnEvidenceBody =
     | { kind: 'suspension'; modal: SuspensionModal; modalKey?: string }
     | { kind: 'suspension_resolved'; resolution: SuspensionResolution; via: SuspensionResolutionVia }
     | { kind: 'turn_end'; strength: TurnEndStrength; afterFinalizationTimeout?: boolean; hollow?: boolean; summary?: SummaryRef
-        blockReason?: TurnEndBlockReason; releasedByHardCap?: boolean; nativeOutcome?: NativeTurnOutcome; live?: LiveTurnPending }
+        blockReason?: TurnEndBlockReason; releasedByHardCap?: boolean; nativeOutcome?: NativeTurnOutcome; live?: LiveTurnPending
+        /**
+         * Stamped (true only) by the WORKER's daemon when the session holds a live
+         * worker-MCP session bind, i.e. the worker can call report_completion. The
+         * owner then treats a genuine end as a report-awaiting candidate (R9r), not
+         * a commit. Absent = no reporting surface = today's genuine-end commit.
+         */
+        reportExpected?: boolean }
     | { kind: 'transcript_final'; selfAttributing: boolean; nativeRead: boolean; nativeMarker?: NativeTurnMarkerRef
         live: LiveTurnPending; summary?: SummaryRef; messageAt?: number }
     | { kind: 'transcript_activity'; newestActivityAt: number }
@@ -296,6 +308,7 @@ export const TURN_EVIDENCE_FIELD_SPECS: TurnEvidenceFieldSpecs = {
         strength: en(TURN_END_STRENGTHS), afterFinalizationTimeout: boolOpt, hollow: boolOpt,
         summary: { t: 'summary_ref', optional: true }, blockReason: enOpt(TURN_END_BLOCK_REASONS),
         releasedByHardCap: boolOpt, nativeOutcome: enOpt(NATIVE_TURN_OUTCOMES), live: { t: 'live', optional: true },
+        reportExpected: boolOpt,
     },
     transcript_final: {
         selfAttributing: bool, nativeRead: bool, nativeMarker: { t: 'native_marker', optional: true },

package/src/types.ts

@@ -153,4 +153,12 @@ export interface RepoMeshSessionStatus {
     startedAt?: string | null
     lastActivityAt?: string | null
     isCached?: boolean
+    /**
+     * Worker MCP delivery outcome for this session's launch (present only for a
+     * mesh-delegated launch). `reason` is a short enum code, never free text —
+     * see `WORKER_MCP_DELIVERY_REASONS` (daemon-core's `mesh/worker-mcp-isolation.ts`,
+     * the source of the vocabulary this field's values are drawn from; not
+     * re-exported here so mesh-shared stays a dependency-free leaf).
+     */
+    workerMcp?: { delivered: boolean; reason?: string }
 }

package/src/worker-protocol.ts

@@ -31,6 +31,7 @@
  */
 
 import { renderMissionBriefBlock, type MissionBrief } from './mission-brief'
+import { isMeshTaskDifficulty } from './brain-routing'
 
 export const WORKER_TOOLS = [
     'report_completion',
@@ -78,7 +79,23 @@ export function renderWorkerProtocolFooter(input: WorkerProtocolFooterInput = {}
     const scope: string[] = []
     if (input.taskId) scope.push(`task ${input.taskId}`)
     if (input.taskMode) scope.push(`mode ${input.taskMode}`)
-    if (input.difficulty) scope.push(`difficulty ${input.difficulty}`)
+    // MCP-usage-audit item 2: validate against the canonical difficulty set
+    // (this package's own brain-routing vocabulary — never duplicated here)
+    // rather than rendering an internal caller's typo or stale value verbatim.
+    // The MCP tool-schema enum already blocks a bad value AT THE TOOLS; this
+    // covers internal callers that can still construct a task with one.
+    if (input.difficulty) {
+        if (isMeshTaskDifficulty(input.difficulty)) {
+            scope.push(`difficulty ${input.difficulty}`)
+        } else {
+            // eslint-disable-next-line no-console -- mesh-shared is a dependency-free
+            // leaf with no logger abstraction; this is the one place that matters.
+            console.warn(
+                `[worker-protocol] task ${input.taskId ?? '(unknown)'}: dropping invalid difficulty '${input.difficulty}' `
+                    + `from the worker footer (expected one of easy, medium, difficult, freeform)`,
+            )
+        }
+    }
     if (input.readonly) scope.push('read-only')
     if (scope.length) lines.push(`You are a delegated worker (${scope.join(', ')}).`)
     else lines.push('You are a delegated worker.')
@@ -89,10 +106,15 @@ export function renderWorkerProtocolFooter(input: WorkerProtocolFooterInput = {}
         'For work that runs longer than a few minutes, call `progress_update` at natural checkpoints so the '
             + 'coordinator can see you are alive without polling.',
         '`peer_context_pull` shows what sibling tasks in this mission have reported; `git_status` / `git_diff` / '
-            + '`git_log` inspect your own workspace (pass its absolute path as `workspace`).',
+            + '`git_log` inspect your own workspace — all three REQUIRE the absolute path to it as `workspace`.',
         'You have no coordinator tools (no `mesh_*`) by design: do not enqueue, dispatch, or restart anything. '
             + 'If you need a decision from the coordinator, finish with `report_completion` and outcome `blocked`, '
             + 'listing what you need in `blockers`.',
+        'On a code-changing task, `report_completion` with outcome `completed` requires `touched_files` — send '
+            + '`[]` if you changed nothing, omitting the field is what gets refused. `blocked`/`failed` never need it, '
+            + 'and a read-only task should omit it or send `[]`.',
+        'If `report_completion` is refused, the response carries `validationErrors` (or a `hint`) naming exactly '
+            + 'what to fix — correct that field and call it again; a refusal records nothing.',
     )
     if (input.enclosedHandoffNotes && input.enclosedHandoffNotes > 0) {
         lines.push(