@adhdev/daemon-core 0.9.82-rc.428 → 0.9.82-rc.429

package/dist/repo-mesh-types.d.ts

@@ -72,6 +72,26 @@ export interface RepoMeshNode {
 export type RepoMeshNodeHealth = 'online' | 'offline' | 'degraded' | 'dirty' | 'wrong_branch' | 'unknown';
 export type RepoMeshSessionCleanupMode = 'preserve' | 'stop' | 'delete_stopped' | 'stop_and_delete';
 export type RepoMeshSpawnedSessionVisibility = 'visible' | 'hidden';
+/**
+ * What to do with the worker sessions a MAGI fan-out auto-launched, once the
+ * review's responses have been collected (terminal). MAGI dispatches each replica
+ * to an independent (node × provider); for a pinned target with no idle session
+ * the queue AUTO-LAUNCHES a fresh worker session. Those auto-launched sessions
+ * stay idle-LIVE after their turn (the CLI process is still running — `completed`
+ * means the task finished, not that the runtime exited), so repeated reviews leave
+ * a trail of idle live worker sessions cluttering the session list.
+ *
+ * 'stop_and_delete' (the default) force-stops AND deletes ONLY the sessions this
+ * fan-out auto-launched (verified by the per-session autoLaunchedForQueueTaskId
+ * marker — see cleanupMeshSessions). It is the only mode that covers the idle-LIVE
+ * case: delete_stopped skips live runtimes by contract, so it would no-op on the
+ * exact sessions we want gone. Reused idle sessions (no marker), the coordinator
+ * session, and any other node's sessions are NEVER touched.
+ *
+ * 'preserve' disables auto-cleanup entirely (leave every auto-launched worker
+ * session as-is for later inspection).
+ */
+export type RepoMeshMagiSessionCleanupMode = 'preserve' | 'stop_and_delete';
 /**
  * Mesh-wide tie-break strategy for distributing untargeted queue work across
  * eligible nodes. This ONLY governs the final tie-break stage of the scheduler
@@ -220,6 +240,17 @@ export interface RepoMeshPolicy {
      * runtimes are never stopped/deleted unless the mesh owner opts in.
      */
     sessionCleanupOnNodeRemove?: RepoMeshSessionCleanupMode;
+    /**
+     * What to do with the worker sessions a MAGI fan-out auto-launched, once the
+     * review responses are collected (terminal). Defaults to 'stop_and_delete' so
+     * repeated mesh_magi_review calls don't accumulate idle-LIVE worker sessions.
+     * Only sessions THIS fan-out auto-launched are affected (marker-verified);
+     * reused/coordinator/other-node sessions are never touched. Set 'preserve' to
+     * leave auto-launched worker sessions for later inspection. A per-call
+     * auto_cleanup override on mesh_magi_review / mesh_magi_collect beats this.
+     * Accepts a boolean for convenience (true → stop_and_delete, false → preserve).
+     */
+    magiSessionCleanup?: RepoMeshMagiSessionCleanupMode | boolean;
     /**
      * Daemon-initiated fast-forward for idle clean nodes that are only behind
      * their tracked upstream. Defaults to enabled.
@@ -308,6 +339,36 @@ export interface RepoMeshNodePolicy {
     initSubmodulesOnClone?: boolean;
 }
 export declare const DEFAULT_MESH_POLICY: RepoMeshPolicy;
+/**
+ * Resolve a magiSessionCleanup policy value (string mode, boolean shorthand,
+ * or unset) to a canonical mode. Unset → the default ('stop_and_delete', ON).
+ * boolean true → 'stop_and_delete', false → 'preserve'. Any unrecognized string
+ * falls back to the default so a typo can't silently disable auto-cleanup.
+ */
+export declare function resolveMagiSessionCleanupMode(value: RepoMeshMagiSessionCleanupMode | boolean | undefined | null): RepoMeshMagiSessionCleanupMode;
+export type MagiCleanupGateReason = 'auto_launch_marker_match' | 'auto_launch_marker_skip_coordinator_session' | 'auto_launch_marker_absent_session_not_auto_launched' | 'auto_launch_marker_mismatch';
+/**
+ * Pure decision for the MAGI auto-cleanup marker gate. A session is eligible for
+ * MAGI auto-cleanup ONLY when its session-host record was auto-launched FOR the
+ * exact replica task the caller expects. This is the safety core: MAGI passes
+ * explicit session_ids (which bypass the self-coordinator / shared-daemon guards),
+ * so this marker check is the sole thing preventing a reused-idle, coordinator, or
+ * re-assigned session from being stopped/deleted.
+ *
+ *  - coordinator session (meta.meshCoordinatorFor === meshId)          → skip
+ *  - no expected task id supplied for this session id                  → skip
+ *  - record carries no autoLaunchedForQueueTaskId marker (reused idle) → skip
+ *  - marker present but points at a DIFFERENT task (re-assignment)     → skip
+ *  - marker present and equals the expected task id                    → ALLOW
+ */
+export declare function magiAutoLaunchedSessionCleanupDecision(args: {
+    recordMarker: string | undefined | null;
+    expectedTaskId: string | undefined | null;
+    isCoordinatorSession: boolean;
+}): {
+    allow: boolean;
+    reason: MagiCleanupGateReason;
+};
 /** Min/max bounds for the global write-task parallel cap. */
 export declare const MESH_MAX_PARALLEL_TASKS_MIN = 1;
 export declare const MESH_MAX_PARALLEL_TASKS_MAX = 8;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.428",
+  "version": "0.9.82-rc.429",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.428",
+    "@adhdev/mesh-shared": "0.9.82-rc.429",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/commands/cli-manager.ts

@@ -718,12 +718,21 @@ export class DaemonCliManager {
         // by now, so updateMeta reaches the session-host store). Best-effort; guarded.
         const launchMeshNodeId = typeof settings?.meshNodeId === 'string' ? settings.meshNodeId.trim() : '';
         const launchMeshNodeFor = typeof settings?.meshNodeFor === 'string' ? settings.meshNodeFor.trim() : '';
-        if (launchMeshNodeId || launchMeshNodeFor) {
+        // Auto-launch attribution: the queue stamps the task id it auto-launched this
+        // worker FOR (autoLaunchedForQueueTaskId). Mirror it onto the record meta so a
+        // later cleanup (e.g. MAGI post-review auto-cleanup) can verify a session was
+        // auto-launched for a SPECIFIC replica task before stopping/deleting it — a reused
+        // idle session never carries this marker, so it is preserved.
+        const launchAutoLaunchedForQueueTaskId = typeof settings?.autoLaunchedForQueueTaskId === 'string'
+            ? settings.autoLaunchedForQueueTaskId.trim()
+            : '';
+        if (launchMeshNodeId || launchMeshNodeFor || launchAutoLaunchedForQueueTaskId) {
             try {
                 cliInstance.getAdapter().updateRuntimeMeta?.({
                     ...(launchMeshNodeId ? { meshNodeId: launchMeshNodeId } : {}),
                     ...(launchMeshNodeFor ? { meshNodeFor: launchMeshNodeFor } : {}),
                     ...(settings?.launchedByCoordinator === true ? { launchedByCoordinator: true } : {}),
+                    ...(launchAutoLaunchedForQueueTaskId ? { autoLaunchedForQueueTaskId: launchAutoLaunchedForQueueTaskId } : {}),
                 });
             } catch { /* best-effort — record-meta stamp is cleanup hygiene, not on the dispatch path */ }
         }

package/src/commands/med-family/mesh-crud.ts

@@ -396,6 +396,15 @@ export const meshCrudHandlers: Record<string, MedFamilyHandler> = {
             const sessionIds = Array.isArray(args?.sessionIds)
                 ? args.sessionIds.map((id: any) => typeof id === 'string' ? id.trim() : '').filter(Boolean)
                 : undefined;
+            // MAGI post-review auto-cleanup routes through this same command with
+            // source:'magi_session_cleanup' and a per-session autoLaunchedForQueueTaskId
+            // map, which gates cleanup to sessions THIS fan-out actually auto-launched.
+            const source = args?.source === 'magi_session_cleanup' ? 'magi_session_cleanup' : 'mesh_cleanup_sessions';
+            const requireAutoLaunchedForTaskIds = (args?.requireAutoLaunchedForTaskIds
+                && typeof args.requireAutoLaunchedForTaskIds === 'object'
+                && !Array.isArray(args.requireAutoLaunchedForTaskIds))
+                ? args.requireAutoLaunchedForTaskIds as Record<string, string>
+                : undefined;
             const result = await ctx.cleanupMeshSessions({
                 meshId,
                 nodeId,
@@ -403,7 +412,8 @@ export const meshCrudHandlers: Record<string, MedFamilyHandler> = {
                 mode,
                 sessionIds,
                 dryRun: args?.dryRun === true,
-                source: 'mesh_cleanup_sessions',
+                source,
+                requireAutoLaunchedForTaskIds,
             });
             return result;
         } catch (e: any) {

package/src/commands/med-family/types.ts

@@ -84,7 +84,8 @@ export interface MedFamilyContext {
         mode: RepoMeshSessionCleanupMode;
         sessionIds?: string[];
         dryRun?: boolean;
-        source?: 'mesh_cleanup_sessions' | 'mesh_remove_node';
+        source?: 'mesh_cleanup_sessions' | 'mesh_remove_node' | 'magi_session_cleanup';
+        requireAutoLaunchedForTaskIds?: Record<string, string>;
     }) => Promise<{ success: boolean; [key: string]: unknown }>;
 
     /** Bound `DaemonCommandRouter.cleanupLocalWorktreeNode`. */

package/src/commands/router.ts

@@ -35,7 +35,7 @@ import { analyzeMeshRefineNodeChangeArea, orderMeshRefineBatchNodes } from '../m
 import type { WorktreeBootstrapState } from '../mesh/worktree-bootstrap-config.js';
 import { getMeshQueueRevision } from '../mesh/mesh-work-queue.js';
 import type { RepoMeshSessionCleanupMode } from '../repo-mesh-types.js';
-import { DEFAULT_MESH_POLICY } from '../repo-mesh-types.js';
+import { DEFAULT_MESH_POLICY, magiAutoLaunchedSessionCleanupDecision } from '../repo-mesh-types.js';
 import { resolve as pathResolve } from 'path';
 import * as fs from 'fs';
 import { execFileSync } from 'node:child_process';
@@ -1409,7 +1409,7 @@ export class DaemonCommandRouter {
         node: any;
         sessionId: string;
         mode: RepoMeshSessionCleanupMode;
-        source: 'mesh_cleanup_sessions' | 'mesh_remove_node';
+        source: 'mesh_cleanup_sessions' | 'mesh_remove_node' | 'magi_session_cleanup';
         action: 'stop_session' | 'delete_session_force';
     }): Promise<void> {
         try {
@@ -1440,7 +1440,17 @@ export class DaemonCommandRouter {
         mode: RepoMeshSessionCleanupMode;
         sessionIds?: string[];
         dryRun?: boolean;
-        source?: 'mesh_cleanup_sessions' | 'mesh_remove_node';
+        source?: 'mesh_cleanup_sessions' | 'mesh_remove_node' | 'magi_session_cleanup';
+        /**
+         * MAGI auto-cleanup safety gate: a map of sessionId → the queue task id that
+         * session must have been AUTO-LAUNCHED for (record meta autoLaunchedForQueueTaskId).
+         * When set, a matched explicit session is only acted on if its record carries that
+         * exact marker. A reused idle session (no marker), the coordinator session, a
+         * re-assigned session, or any session whose marker points at a DIFFERENT task is
+         * skipped (reason 'auto_launch_marker_mismatch') — so MAGI never kills a session it
+         * didn't itself spawn for this fan-out. Only consulted alongside explicit sessionIds.
+         */
+        requireAutoLaunchedForTaskIds?: Record<string, string>;
     }): Promise<{ success: boolean; [key: string]: unknown }> {
         if (args.mode === 'preserve') {
             return { success: true, mode: 'preserve', matchedCount: 0, stoppedSessionIds: [], deletedSessionIds: [], skippedSessionIds: [] };
@@ -1459,6 +1469,7 @@ export class DaemonCommandRouter {
         const skippedLiveSessionIds: string[] = [];
         const skippedCoordinatorSessionIds: string[] = [];
         const skippedLiveSessionReasons: Array<{ sessionId: string; reason: string }> = [];
+        const skippedMarkerMismatchSessionIds: string[] = [];
         const actedLiveDelegateSessionIds: string[] = [];
         const deleteUnsupportedSessionIds: string[] = [];
         const recordsRemainSessionIds: string[] = [];
@@ -1511,6 +1522,28 @@ export class DaemonCommandRouter {
                 skippedCoordinatorSessionIds.push(sessionId);
                 continue;
             }
+            // MAGI auto-cleanup marker gate. When the caller supplied a per-session
+            // expected autoLaunchedForQueueTaskId, the session must (a) carry the marker
+            // on its record meta AND (b) have it equal the expected replica task id.
+            // This is the safety core for MAGI: explicit session_ids bypass the
+            // self-coordinator / shared-daemon guards (hasExplicitSessionIds=true), so the
+            // ONLY thing protecting a reused-idle / coordinator / re-assigned session here
+            // is this marker check. Always-skip the coordinator session even when its id is
+            // passed explicitly (it never carries an autoLaunchedForQueueTaskId marker, so
+            // the mismatch branch already covers it, but be explicit for clarity).
+            if (args.requireAutoLaunchedForTaskIds) {
+                const decision = magiAutoLaunchedSessionCleanupDecision({
+                    recordMarker: readStringValue(record?.meta?.autoLaunchedForQueueTaskId),
+                    expectedTaskId: args.requireAutoLaunchedForTaskIds[sessionId],
+                    isCoordinatorSession: coordinatorSession,
+                });
+                if (!decision.allow) {
+                    skippedSessionIds.push(sessionId);
+                    skippedMarkerMismatchSessionIds.push(sessionId);
+                    skippedLiveSessionReasons.push({ sessionId, reason: decision.reason });
+                    continue;
+                }
+            }
             // Only the conservative shared-daemon guard for live sessions that are NOT a delegate
             // explicitly bound to this node. Delegate-bound live sessions fall through and are
             // stopped/deleted by the mode handlers below (which already record an intentional stop).
@@ -1622,6 +1655,7 @@ export class DaemonCommandRouter {
             skippedSessionIds,
             skippedLiveSessionIds,
             skippedCoordinatorSessionIds,
+            ...(skippedMarkerMismatchSessionIds.length ? { skippedMarkerMismatchSessionIds } : {}),
             ...(actedLiveDelegateSessionIds.length ? { actedLiveDelegateSessionIds } : {}),
             ...(skippedLiveSessionReasons.length ? { skippedLiveSessionReasons } : {}),
             ...(deleteUnsupported ? {

package/src/config/mesh-config.ts

@@ -22,7 +22,7 @@ import type {
     RepoMeshHostMetadata,
     RepoMeshDaemonRole,
 } from '../repo-mesh-types.js';
-import type { MagiPanel, MagiPanelMember } from '@adhdev/mesh-shared';
+import type { MagiPanel, MagiPanelMember, MagiPanelDefaultKind } from '@adhdev/mesh-shared';
 import { mergeAndNormalizePolicy } from '../repo-mesh-types.js';
 import { createDefaultMeshHostMetadata } from '../mesh/mesh-host-ownership.js';
 
@@ -597,6 +597,30 @@ function normalizeReplicaCount(value: unknown): number | undefined {
     return n >= 1 ? n : undefined;
 }
 
+/**
+ * Normalize a panel `defaultKind` (the non-binding default output kind). Returns
+ * undefined (drop, don't throw) for any absent / unknown value so a stray field
+ * never blocks a panel write. 'freeform' is explicitly DROPPED with a warning: a
+ * panel is a cross-verification tool and freeform contributes no structured claims
+ * (claims:[]), so defaulting to it would silently zero out the very thing the panel
+ * exists for. Only the evidence-bearing kinds (claim_audit / rca / design) survive.
+ */
+function normalizeMagiPanelDefaultKind(raw: unknown): MagiPanelDefaultKind | undefined {
+    if (raw == null) return undefined;
+    const s = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+    if (s === 'claim_audit' || s === 'rca' || s === 'design') return s;
+    if (s === 'freeform') {
+        // eslint-disable-next-line no-console
+        console.warn(
+            "[magi] panel defaultKind='freeform' rejected — freeform contributes no structured claims to cross-verification; dropping (use claim_audit / rca / design, or omit).",
+        );
+        return undefined;
+    }
+    // Any other value (typo / unsupported kind): drop silently — the panel still
+    // resolves to the claim_audit fallback at review time.
+    return undefined;
+}
+
 /**
  * Validate + normalize a panel config before persisting. Mirrors the node-config
  * normalization style (mesh-config addNode/updateNode): trims strings, drops
@@ -639,10 +663,12 @@ export function normalizeMagiPanel(config: unknown): MagiPanel {
         ? raw.description.trim().slice(0, 200)
         : undefined;
     const defaultN = normalizeReplicaCount(raw.defaultN);
+    const defaultKind = normalizeMagiPanelDefaultKind(raw.defaultKind);
     return {
         ...(description ? { description } : {}),
         members,
         ...(defaultN !== undefined ? { defaultN } : {}),
+        ...(defaultKind !== undefined ? { defaultKind } : {}),
         // dedupExempt is always meaningful for a MAGI panel (intentional same-prompt
         // fan-out). Persist it true unless the caller explicitly disables it.
         dedupExempt: raw.dedupExempt === false ? false : true,

package/src/index.ts

@@ -110,6 +110,7 @@ export type {
   RepoMeshNode,
   RepoMeshNodeHealth,
   RepoMeshPolicy,
+  RepoMeshMagiSessionCleanupMode,
   RepoMeshNodePolicy,
   RepoMeshRelatedRepo,
   RepoMeshNodeCapabilities,
@@ -142,6 +143,8 @@ export type {
 export {
   DEFAULT_MESH_POLICY,
   resolveDelegatedWorkerAutoApprove,
+  resolveMagiSessionCleanupMode,
+  magiAutoLaunchedSessionCleanupDecision,
   MESH_SCHEDULING_STRATEGIES,
   DEFAULT_MESH_SCHEDULING_STRATEGY,
   normalizeMeshSchedulingStrategy,
@@ -199,7 +202,7 @@ export type { CreateMeshOptions, UpdateMeshOptions, AddNodeOptions } from './con
 // leaf so the mcp-server — which depends only on @adhdev/daemon-core — can consume
 // them without taking a direct @adhdev/mesh-shared dependency).
 export type {
-  MagiPanel, MagiPanelMember, MagiPanelMap, MagiMode,
+  MagiPanel, MagiPanelMember, MagiPanelMap, MagiMode, MagiTaskKind, MagiPanelDefaultKind,
   MagiClaim, MagiClaimStance, MagiAgentResponse,
   MagiResponseSource, MagiReplicaGitRef, MagiGitSkew, MagiSynthesizedResponse,
   MagiClusterCategory, MagiClusterMember, MagiClaimCluster, MagiSynthesis,

package/src/repo-mesh-types.ts

@@ -92,6 +92,27 @@ export type RepoMeshNodeHealth =
 export type RepoMeshSessionCleanupMode = 'preserve' | 'stop' | 'delete_stopped' | 'stop_and_delete';
 export type RepoMeshSpawnedSessionVisibility = 'visible' | 'hidden';
 
+/**
+ * What to do with the worker sessions a MAGI fan-out auto-launched, once the
+ * review's responses have been collected (terminal). MAGI dispatches each replica
+ * to an independent (node × provider); for a pinned target with no idle session
+ * the queue AUTO-LAUNCHES a fresh worker session. Those auto-launched sessions
+ * stay idle-LIVE after their turn (the CLI process is still running — `completed`
+ * means the task finished, not that the runtime exited), so repeated reviews leave
+ * a trail of idle live worker sessions cluttering the session list.
+ *
+ * 'stop_and_delete' (the default) force-stops AND deletes ONLY the sessions this
+ * fan-out auto-launched (verified by the per-session autoLaunchedForQueueTaskId
+ * marker — see cleanupMeshSessions). It is the only mode that covers the idle-LIVE
+ * case: delete_stopped skips live runtimes by contract, so it would no-op on the
+ * exact sessions we want gone. Reused idle sessions (no marker), the coordinator
+ * session, and any other node's sessions are NEVER touched.
+ *
+ * 'preserve' disables auto-cleanup entirely (leave every auto-launched worker
+ * session as-is for later inspection).
+ */
+export type RepoMeshMagiSessionCleanupMode = 'preserve' | 'stop_and_delete';
+
 /**
  * Mesh-wide tie-break strategy for distributing untargeted queue work across
  * eligible nodes. This ONLY governs the final tie-break stage of the scheduler
@@ -309,6 +330,17 @@ export interface RepoMeshPolicy {
      * runtimes are never stopped/deleted unless the mesh owner opts in.
      */
     sessionCleanupOnNodeRemove?: RepoMeshSessionCleanupMode;
+    /**
+     * What to do with the worker sessions a MAGI fan-out auto-launched, once the
+     * review responses are collected (terminal). Defaults to 'stop_and_delete' so
+     * repeated mesh_magi_review calls don't accumulate idle-LIVE worker sessions.
+     * Only sessions THIS fan-out auto-launched are affected (marker-verified);
+     * reused/coordinator/other-node sessions are never touched. Set 'preserve' to
+     * leave auto-launched worker sessions for later inspection. A per-call
+     * auto_cleanup override on mesh_magi_review / mesh_magi_collect beats this.
+     * Accepts a boolean for convenience (true → stop_and_delete, false → preserve).
+     */
+    magiSessionCleanup?: RepoMeshMagiSessionCleanupMode | boolean;
     /**
      * Daemon-initiated fast-forward for idle clean nodes that are only behind
      * their tracked upstream. Defaults to enabled.
@@ -414,6 +446,11 @@ export const DEFAULT_MESH_POLICY: RepoMeshPolicy = {
     spawnedSessionVisibility: 'hidden',
     delegatedWorkerAutoApprove: true,
     sessionCleanupOnNodeRemove: 'preserve',
+    // MAGI auto-launches a worker session per pinned replica target with no idle
+    // session; those stay idle-LIVE after their turn. Default ON (stop_and_delete)
+    // so repeated reviews don't pile up idle worker sessions. Only marker-verified
+    // auto-launched sessions are cleaned — see RepoMeshMagiSessionCleanupMode.
+    magiSessionCleanup: 'stop_and_delete',
     autoFastForward: { enabled: true },
     maxTaskRetries: 1,
 };
@@ -430,6 +467,56 @@ export const DEFAULT_MESH_POLICY: RepoMeshPolicy = {
 const SESSION_CLEANUP_MODES = new Set<RepoMeshSessionCleanupMode>([
     'preserve', 'stop', 'delete_stopped', 'stop_and_delete',
 ]);
+
+/**
+ * Resolve a magiSessionCleanup policy value (string mode, boolean shorthand,
+ * or unset) to a canonical mode. Unset → the default ('stop_and_delete', ON).
+ * boolean true → 'stop_and_delete', false → 'preserve'. Any unrecognized string
+ * falls back to the default so a typo can't silently disable auto-cleanup.
+ */
+export function resolveMagiSessionCleanupMode(
+    value: RepoMeshMagiSessionCleanupMode | boolean | undefined | null,
+): RepoMeshMagiSessionCleanupMode {
+    if (value === undefined || value === null) return DEFAULT_MESH_POLICY.magiSessionCleanup as RepoMeshMagiSessionCleanupMode;
+    if (typeof value === 'boolean') return value ? 'stop_and_delete' : 'preserve';
+    return value === 'preserve' || value === 'stop_and_delete'
+        ? value
+        : (DEFAULT_MESH_POLICY.magiSessionCleanup as RepoMeshMagiSessionCleanupMode);
+}
+
+export type MagiCleanupGateReason =
+    | 'auto_launch_marker_match'
+    | 'auto_launch_marker_skip_coordinator_session'
+    | 'auto_launch_marker_absent_session_not_auto_launched'
+    | 'auto_launch_marker_mismatch';
+
+/**
+ * Pure decision for the MAGI auto-cleanup marker gate. A session is eligible for
+ * MAGI auto-cleanup ONLY when its session-host record was auto-launched FOR the
+ * exact replica task the caller expects. This is the safety core: MAGI passes
+ * explicit session_ids (which bypass the self-coordinator / shared-daemon guards),
+ * so this marker check is the sole thing preventing a reused-idle, coordinator, or
+ * re-assigned session from being stopped/deleted.
+ *
+ *  - coordinator session (meta.meshCoordinatorFor === meshId)          → skip
+ *  - no expected task id supplied for this session id                  → skip
+ *  - record carries no autoLaunchedForQueueTaskId marker (reused idle) → skip
+ *  - marker present but points at a DIFFERENT task (re-assignment)     → skip
+ *  - marker present and equals the expected task id                    → ALLOW
+ */
+export function magiAutoLaunchedSessionCleanupDecision(args: {
+    recordMarker: string | undefined | null;
+    expectedTaskId: string | undefined | null;
+    isCoordinatorSession: boolean;
+}): { allow: boolean; reason: MagiCleanupGateReason } {
+    const marker = typeof args.recordMarker === 'string' ? args.recordMarker.trim() : '';
+    const expected = typeof args.expectedTaskId === 'string' ? args.expectedTaskId.trim() : '';
+    if (args.isCoordinatorSession) return { allow: false, reason: 'auto_launch_marker_skip_coordinator_session' };
+    if (!expected) return { allow: false, reason: 'auto_launch_marker_mismatch' };
+    if (!marker) return { allow: false, reason: 'auto_launch_marker_absent_session_not_auto_launched' };
+    if (marker !== expected) return { allow: false, reason: 'auto_launch_marker_mismatch' };
+    return { allow: true, reason: 'auto_launch_marker_match' };
+}
 const SPAWNED_SESSION_VISIBILITY_MODES = new Set<RepoMeshSpawnedSessionVisibility>([
     'visible', 'hidden',
 ]);
@@ -526,6 +613,8 @@ export function mergeAndNormalizePolicy(
     if (!SESSION_CLEANUP_MODES.has(policy.sessionCleanupOnNodeRemove as RepoMeshSessionCleanupMode)) {
         policy.sessionCleanupOnNodeRemove = 'preserve';
     }
+    // Canonicalize magiSessionCleanup (accepts boolean shorthand / unset → default ON).
+    policy.magiSessionCleanup = resolveMagiSessionCleanupMode(policy.magiSessionCleanup);
     if (!SPAWNED_SESSION_VISIBILITY_MODES.has(policy.spawnedSessionVisibility as RepoMeshSpawnedSessionVisibility)) {
         policy.spawnedSessionVisibility = DEFAULT_MESH_POLICY.spawnedSessionVisibility;
     }