oysterun 1.6.0-beta.2 → 1.6.0-beta.21

package/host-service/session-loop-definitions.mjs

@@ -1,8 +1,11 @@
 import { createHash, randomUUID } from "crypto";
 import {
   chmodSync,
+  closeSync,
   existsSync,
+  fsyncSync,
   mkdirSync,
+  openSync,
   readFileSync,
   realpathSync,
   renameSync,
@@ -32,6 +35,8 @@ export const SESSION_LOOP_LIFECYCLE_FILENAME =
 export const SESSION_LOOP_RECONCILIATION_ERROR_CODE =
   "session_loop_lifecycle_reconciliation_failed";
 export const SESSION_LOOP_DEFINITION_REVISION_ALGORITHM = "sha256";
+export const SESSION_LOOP_DEFINITION_UNAVAILABLE_GRACE_MS = 10_000;
+export const SESSION_LOOP_INCIDENT_HISTORY_LIMIT = 16;
 
 const LOOP_DEFINITION_ROOT_KEYS = new Set(["version", "loops"]);
 const LOOP_DEFINITION_ALLOWED_KEYS = new Set([
@@ -81,6 +86,15 @@ const LOOP_LIFECYCLE_STATE_ALLOWED_KEYS = new Set([
   "dispatch_count",
   "skip_count",
   "last_dispatched_message_id",
+  "definition_snapshot",
+  "definition_generation",
+  "availability_state",
+  "unavailable_since",
+  "unavailable_observations",
+  "candidate_definition",
+  "candidate_revision",
+  "incidents",
+  "migration_receipt",
   "updated_at",
   "evidence",
 ]);
@@ -104,6 +118,18 @@ const LOOP_PENDING_OCCURRENCE_ALLOWED_KEYS = new Set([
 ]);
 const ACTIVE_AGENT_FOLDER_MUTATIONS = new Set();
 
+const LOOP_INCIDENT_ALLOWED_KEYS = new Set([
+  "id",
+  "generation",
+  "reason",
+  "definition_revision",
+  "candidate_revision",
+  "created_at",
+  "resolved_at",
+  "recovery_options",
+  "notification_key",
+]);
+
 const INTERVAL_UNITS_MS = Object.freeze({
   s: 1000,
   m: 60 * 1000,
@@ -213,6 +239,60 @@ function normalizeNullableString(value, fieldName) {
   return value.trim() || null;
 }
 
+function normalizeOptionalNonNegativeInteger(value, fieldName, fallback = 0) {
+  if (value === undefined || value === null) return fallback;
+  return normalizeNonNegativeInteger(value, fieldName);
+}
+
+function safeDefinitionCommandSummary(commandText) {
+  const normalized = String(commandText || "").replace(/\s+/g, " ").trim();
+  if (!normalized) return "[command unavailable]";
+  return `[redacted command sha256:${hashText(normalized).slice(0, 16)}]`;
+}
+
+function snapshotDefinition(definition) {
+  return normalizeLoopDefinition(
+    {
+      ...definition,
+      command_text: safeDefinitionCommandSummary(definition.command_text),
+    },
+    { existing: definition }
+  );
+}
+
+function normalizeDefinitionSnapshot(value, fieldName) {
+  if (value === null || value === undefined) return null;
+  try {
+    return snapshotDefinition(value);
+  } catch (err) {
+    throw new Error(`${fieldName} is invalid: ${err.message}`);
+  }
+}
+
+function normalizeLoopIncident(value) {
+  if (!isObjectRecord(value)) throw new Error("Loop incident must be an object");
+  assertAllowedObjectKeys(value, LOOP_INCIDENT_ALLOWED_KEYS, "Loop incident");
+  const recoveryOptions = Array.isArray(value.recovery_options)
+    ? value.recovery_options.map((entry) =>
+        normalizeRequiredString(entry, "loop incident recovery option")
+      )
+    : [];
+  return {
+    id: normalizeRequiredString(value.id, "loop incident id"),
+    generation: normalizeNonNegativeInteger(value.generation, "loop incident generation"),
+    reason: normalizeRequiredString(value.reason, "loop incident reason"),
+    definition_revision: normalizeDefinitionRevision(value.definition_revision),
+    candidate_revision: normalizeDefinitionRevision(value.candidate_revision),
+    created_at: normalizeOptionalIsoTimestamp(value.created_at, "loop incident created_at"),
+    resolved_at: normalizeOptionalIsoTimestamp(value.resolved_at, "loop incident resolved_at"),
+    recovery_options: recoveryOptions,
+    notification_key: normalizeRequiredString(
+      value.notification_key,
+      "loop incident notification_key"
+    ),
+  };
+}
+
 export function normalizeSessionLoopCommandText(value) {
   return normalizeRequiredString(value, "loop command text").replace(/\s+/g, " ");
 }
@@ -661,6 +741,7 @@ function normalizeLifecycleState(value) {
     "active",
     "disabled",
     "suspended",
+    "provisional",
     "expired",
     "cancelled",
   ].includes(status)) {
@@ -701,6 +782,38 @@ function normalizeLifecycleState(value) {
       value.last_dispatched_message_id,
       "loop last_dispatched_message_id"
     ),
+    definition_snapshot: normalizeDefinitionSnapshot(
+      value.definition_snapshot,
+      "loop definition_snapshot"
+    ),
+    definition_generation: normalizeOptionalNonNegativeInteger(
+      value.definition_generation,
+      "loop definition_generation"
+    ),
+    availability_state: normalizeRequiredString(
+      value.availability_state || "available",
+      "loop availability_state"
+    ),
+    unavailable_since: normalizeOptionalIsoTimestamp(
+      value.unavailable_since,
+      "loop unavailable_since"
+    ),
+    unavailable_observations: normalizeOptionalNonNegativeInteger(
+      value.unavailable_observations,
+      "loop unavailable_observations"
+    ),
+    candidate_definition: normalizeDefinitionSnapshot(
+      value.candidate_definition,
+      "loop candidate_definition"
+    ),
+    candidate_revision: normalizeDefinitionRevision(value.candidate_revision),
+    incidents: Array.isArray(value.incidents)
+      ? value.incidents.map(normalizeLoopIncident).slice(-SESSION_LOOP_INCIDENT_HISTORY_LIMIT)
+      : [],
+    migration_receipt: normalizeNullableString(
+      value.migration_receipt,
+      "loop migration_receipt"
+    ),
     updated_at: normalizeOptionalIsoTimestamp(value.updated_at, "loop updated_at"),
     evidence,
   };
@@ -849,8 +962,20 @@ export class SessionLoopLifecycleStore {
     writeFileSync(temporaryPath, serializeLifecyclePayload(normalized), {
       mode: 0o600,
     });
+    const temporaryFd = openSync(temporaryPath, "r");
+    try {
+      fsyncSync(temporaryFd);
+    } finally {
+      closeSync(temporaryFd);
+    }
     chmodSync(temporaryPath, 0o600);
     renameSync(temporaryPath, this.lifecyclePath);
+    const directoryFd = openSync(this.configDir, "r");
+    try {
+      fsyncSync(directoryFd);
+    } finally {
+      closeSync(directoryFd);
+    }
     chmodSync(this.lifecyclePath, 0o600);
     return this.read();
   }
@@ -898,6 +1023,15 @@ function createRuntimeState(
     dispatch_count: 0,
     skip_count: 0,
     last_dispatched_message_id: null,
+    definition_snapshot: snapshotDefinition(definition),
+    definition_generation: 0,
+    availability_state: "available",
+    unavailable_since: null,
+    unavailable_observations: 0,
+    candidate_definition: null,
+    candidate_revision: null,
+    incidents: [],
+    migration_receipt: null,
     updated_at: timestamp,
     evidence: [
       {
@@ -918,12 +1052,22 @@ export class SessionLoopDefinitionService {
     lifecycleStore = new SessionLoopLifecycleStore(),
     clock = () => new Date(),
     recheckMs = 5000,
+    unavailableGraceMs = SESSION_LOOP_DEFINITION_UNAVAILABLE_GRACE_MS,
   } = {}) {
     this.store = store;
     this.lifecycleStore = lifecycleStore;
     this.clock = clock;
     this.recheckMs = recheckMs;
+    if (
+      !Number.isInteger(unavailableGraceMs) ||
+      unavailableGraceMs < 5_000 ||
+      unavailableGraceMs > 30_000
+    ) {
+      throw new Error("Loop definition unavailable grace must be 5000..30000ms");
+    }
+    this.unavailableGraceMs = unavailableGraceMs;
     this.sessions = new Map();
+    this.folderSnapshots = new Map();
   }
 
   createReconciliationError(
@@ -986,6 +1130,21 @@ export class SessionLoopDefinitionService {
     }
   }
 
+  readDefinitionsForReconciliation(agentFolder) {
+    try {
+      return this.store.readDefinitions(agentFolder);
+    } catch (err) {
+      const paths = this.store.resolveLoopsPath(agentFolder);
+      return {
+        ...paths,
+        version: SESSION_LOOP_DEFINITIONS_VERSION,
+        loops: [],
+        file_exists: existsSync(paths.loopsPath),
+        read_error: err?.message || String(err),
+      };
+    }
+  }
+
   appendTerminalEvidence(session, entry) {
     session.terminal_evidence = [
       ...(session.terminal_evidence || []),
@@ -1019,32 +1178,156 @@ export class SessionLoopDefinitionService {
     });
   }
 
-  resetStateForDefinitionRevision({ state, definition, reason, timestamp }) {
+  adoptDefinitionRevision({ state, definition, generation, timestamp }) {
     const occurrenceId = state.pending_occurrence?.occurrence_id || null;
     if (occurrenceId) {
       this.appendEvidence(state, "cancelled", {
         occurrenceId,
-        reason: `${reason}_pending_cancelled`,
+        reason: "definition_updated_pending_cancelled",
         recordedAt: timestamp,
       });
     }
     state.definition_revision = definitionRevision(definition);
-    state.enabled = false;
-    state.status = "disabled";
-    state.cadence_anchor_at = null;
-    state.next_run_at = null;
+    state.definition_snapshot = snapshotDefinition(definition);
+    state.definition_generation = generation;
+    state.availability_state = "available";
+    state.unavailable_since = null;
+    state.unavailable_observations = 0;
+    state.candidate_definition = null;
+    state.candidate_revision = null;
     state.pending_occurrence = null;
-    state.suspension_reason = reason;
     state.last_error = null;
-    this.appendEvidence(state, "disabled", {
-      occurrenceId,
-      reason,
+    state.status = state.enabled ? "active" : "disabled";
+    state.suspension_reason = state.enabled ? null : "owner_disabled";
+    state.cadence_anchor_at = state.enabled ? definition.start_at || timestamp : null;
+    state.next_run_at = state.enabled
+      ? Date.parse(definition.start_at || "") > Date.parse(timestamp)
+        ? definition.start_at
+        : computeFirstCadenceBoundaryAfter({
+            anchorAt: state.cadence_anchor_at,
+            intervalMs: definition.interval_ms,
+            after: timestamp,
+          })
+      : null;
+    // Historical review incidents are evidence, never ongoing execution authority.
+    for (const incident of state.incidents || []) {
+      if (!incident.resolved_at) incident.resolved_at = timestamp;
+    }
+    this.appendEvidence(state, state.enabled ? "session-resumed" : "disabled", {
+      reason: "definition_updated_intent_preserved_fresh_cadence",
       recordedAt: timestamp,
     });
-    return state;
   }
 
-  reconcileLifecycleSession({ session, storage }) {
+  definitionSetSignature(storage) {
+    return hashText(
+      JSON.stringify(
+        {
+          file_exists: storage.file_exists === true,
+          read_error: storage.read_error ? hashText(storage.read_error) : null,
+          definitions: storage.loops
+            .map((definition) => [definition.id, definitionRevision(definition)])
+            .sort((left, right) => left[0].localeCompare(right[0])),
+        }
+      )
+    );
+  }
+
+  nextFolderGeneration(storage, lifecycle) {
+    const signature = this.definitionSetSignature(storage);
+    const current = this.folderSnapshots.get(storage.agentFolder);
+    if (current?.signature === signature) return current.generation;
+    const durableGeneration = lifecycle.sessions
+      .filter((session) => session.agent_folder === storage.agentFolder)
+      .flatMap((session) => session.loops)
+      .reduce((maximum, state) => Math.max(maximum, state.definition_generation || 0), 0);
+    const generation = Math.max(current?.generation || 0, durableGeneration) + 1;
+    this.folderSnapshots.set(storage.agentFolder, { signature, generation });
+    return generation;
+  }
+
+  currentIncident(state) {
+    return [...(state.incidents || [])].reverse().find((incident) => !incident.resolved_at) || null;
+  }
+
+  resolveCurrentIncident(state, timestamp) {
+    const incident = this.currentIncident(state);
+    if (incident) incident.resolved_at = timestamp;
+    return incident;
+  }
+
+  createIncident({ session, state, reason, generation, candidateRevision = null, timestamp }) {
+    const unresolvedEquivalent = (state.incidents || []).find(
+      (incident) =>
+        !incident.resolved_at &&
+        incident.reason === reason &&
+        incident.definition_revision === state.definition_revision &&
+        incident.candidate_revision === candidateRevision
+    );
+    if (unresolvedEquivalent) {
+      return { incident: unresolvedEquivalent, created: false };
+    }
+    const notificationKey = hashText(
+      [generation, session.agent_folder, session.host_session_id, state.id, reason,
+        candidateRevision || state.definition_revision || "none"].join(":")
+    );
+    const existing = (state.incidents || []).find(
+      (incident) => incident.notification_key === notificationKey
+    );
+    if (existing) return { incident: existing, created: false };
+    const incident = normalizeLoopIncident({
+      id: `loop_incident_${notificationKey.slice(0, 24)}`,
+      generation,
+      reason,
+      definition_revision: state.definition_revision,
+      candidate_revision: candidateRevision,
+      created_at: timestamp,
+      resolved_at: null,
+      recovery_options:
+        reason === "legacy_reconciliation_intent_loss"
+            ? ["restore_previous_enabled_state", "keep_disabled", "open_loop"]
+            : ["restore", "keep_disabled", "open_loop"],
+      notification_key: notificationKey,
+    });
+    state.incidents = [...(state.incidents || []), incident].slice(
+      -SESSION_LOOP_INCIDENT_HISTORY_LIMIT
+    );
+    return { incident, created: true };
+  }
+
+  classifyLegacyIntentLoss({ session, state, timestamp, generation }) {
+    if (state.migration_receipt) return null;
+    const discovered = state.evidence?.some(
+      (entry) => entry.reason === "shared_agent_folder_definition_discovered_default_off"
+    );
+    const removed = session.terminal_evidence?.some(
+      (entry) =>
+        entry.loop_id === state.id &&
+        entry.reason === "shared_agent_folder_definition_removed"
+    );
+    if (!discovered || !removed) return null;
+    state.migration_receipt = `p254:${hashText(
+      `${session.host_session_id}:${state.id}:legacy_reconciliation_intent_loss`
+    ).slice(0, 24)}`;
+    state.status = "suspended";
+    state.availability_state = "available";
+    state.suspension_reason = "legacy_reconciliation_intent_loss";
+    const created = this.createIncident({
+      session,
+      state,
+      reason: "legacy_reconciliation_intent_loss",
+      generation,
+      timestamp,
+    });
+    return created.created ? created.incident : null;
+  }
+
+  reconcileLifecycleSession({
+    session,
+    storage,
+    generation,
+    explicitDeletedLoopId = null,
+  }) {
     let storedCanonicalFolder = session.agent_folder;
     if (storedCanonicalFolder !== storage.agentFolder) {
       try {
@@ -1060,6 +1343,7 @@ export class SessionLoopDefinitionService {
     const timestamp = nowIso(this.clock);
     const statesById = new Map(session.loops.map((state) => [state.id, state]));
     const nextStates = [];
+    const createdIncidents = [];
     let mutated = false;
     if (session.agent_folder !== storage.agentFolder) {
       session.agent_folder = storage.agentFolder;
@@ -1074,17 +1358,81 @@ export class SessionLoopDefinitionService {
           timestamp,
           reason: "shared_agent_folder_definition_discovered_default_off",
         });
+        state.definition_generation = generation;
         mutated = true;
-      } else if (state.definition_revision !== revision) {
-        const reason = state.definition_revision
-          ? "shared_agent_folder_definition_changed_default_off"
-          : "definition_revision_migrated_default_off";
-        this.resetStateForDefinitionRevision({
-          state,
-          definition,
-          reason,
-          timestamp,
-        });
+      } else if (state.definition_revision !== revision ||
+        state.availability_state === "changed_review" ||
+        state.suspension_reason === "definition_changed_requires_review") {
+        if (!state.definition_revision) {
+          state.definition_revision = revision;
+          state.definition_snapshot = snapshotDefinition(definition);
+          state.definition_generation = generation;
+          state.availability_state = "available";
+          state.suspension_reason = state.enabled ? null : state.suspension_reason;
+        } else {
+          this.adoptDefinitionRevision({ state, definition, generation, timestamp });
+        }
+        mutated = true;
+      } else {
+        const wasUnavailable = state.availability_state !== "available";
+        const generationChanged = state.definition_generation !== generation;
+        const snapshotMissing = !state.definition_snapshot;
+        state.definition_snapshot = snapshotDefinition(definition);
+        state.definition_generation = Math.max(state.definition_generation || 0, generation);
+        state.availability_state = "available";
+        state.unavailable_since = null;
+        state.unavailable_observations = 0;
+        state.candidate_definition = null;
+        state.candidate_revision = null;
+        state.last_error = null;
+        if (generationChanged || snapshotMissing) mutated = true;
+        if (wasUnavailable && state.enabled === true) {
+          const now = nowIso(this.clock);
+          state.status = "active";
+          state.suspension_reason = null;
+          state.cadence_anchor_at = now;
+          state.next_run_at = computeFirstCadenceBoundaryAfter({
+            anchorAt: now,
+            intervalMs: definition.interval_ms,
+            after: now,
+          });
+          state.pending_occurrence = null;
+          this.resolveCurrentIncident(state, timestamp);
+          this.appendEvidence(state, "session-resumed", {
+            reason: "definition_returned_same_revision_fresh_cadence",
+            recordedAt: timestamp,
+          });
+          mutated = true;
+        } else if (
+          state.enabled !== true &&
+          state.status !== "expired" &&
+          state.status !== "cancelled" &&
+          state.evidence.some((entry) =>
+            ["owner_kept_disabled", "owner_disabled"].includes(entry.reason)
+          ) &&
+          (state.status !== "disabled" || state.suspension_reason !== "owner_disabled")
+        ) {
+          state.status = "disabled";
+          state.suspension_reason = "owner_disabled";
+          state.cadence_anchor_at = null;
+          state.next_run_at = null;
+          state.pending_occurrence = null;
+          this.resolveCurrentIncident(state, timestamp);
+          this.appendEvidence(state, "disabled", {
+            reason: "owner_disabled_state_reconciled",
+            recordedAt: timestamp,
+          });
+          mutated = true;
+        }
+      }
+      const migratedIncident = this.classifyLegacyIntentLoss({
+        session,
+        state,
+        timestamp,
+        generation,
+      });
+      if (migratedIncident) {
+        createdIncidents.push(migratedIncident);
         mutated = true;
       }
       nextStates.push(state);
@@ -1092,13 +1440,73 @@ export class SessionLoopDefinitionService {
     }
 
     for (const staleState of statesById.values()) {
+      if (explicitDeletedLoopId === staleState.id) {
+        const occurrenceId = staleState.pending_occurrence?.occurrence_id || null;
+        this.appendEvidence(staleState, "cancelled", {
+          occurrenceId,
+          reason: "deleted_by_owner",
+          recordedAt: timestamp,
+        });
+        this.appendTerminalEvidence(session, staleState.evidence.at(-1));
+        mutated = true;
+        continue;
+      }
       const occurrenceId = staleState.pending_occurrence?.occurrence_id || null;
-      this.appendEvidence(staleState, "cancelled", {
-        occurrenceId,
-        reason: "shared_agent_folder_definition_removed",
-        recordedAt: timestamp,
-      });
-      this.appendTerminalEvidence(session, staleState.evidence.at(-1));
+      const firstUnavailable = !staleState.unavailable_since;
+      staleState.unavailable_since ||= timestamp;
+      staleState.unavailable_observations =
+        (staleState.unavailable_observations || 0) + 1;
+      staleState.availability_state = "provisional";
+      staleState.definition_generation = generation;
+      staleState.status = "provisional";
+      staleState.suspension_reason = "checking_definition_availability";
+      staleState.last_error = storage.read_error || null;
+      staleState.next_run_at = null;
+      if (occurrenceId) {
+        this.appendEvidence(staleState, "cancelled", {
+          occurrenceId,
+          reason: "provisional_definition_unavailable_pending_cancelled",
+          recordedAt: timestamp,
+        });
+        staleState.pending_occurrence = null;
+      }
+      const elapsed = Date.parse(timestamp) - Date.parse(staleState.unavailable_since);
+      if (staleState.enabled !== true) {
+        staleState.status = "disabled";
+        staleState.suspension_reason = "owner_disabled";
+        staleState.availability_state =
+          staleState.unavailable_observations >= 2 && elapsed >= this.unavailableGraceMs
+            ? "unavailable"
+            : "provisional";
+        this.resolveCurrentIncident(staleState, timestamp);
+        nextStates.push(staleState);
+        mutated = true;
+        continue;
+      }
+      if (
+        staleState.unavailable_observations >= 2 &&
+        elapsed >= this.unavailableGraceMs
+      ) {
+        staleState.availability_state = "unavailable";
+        staleState.status = "suspended";
+        staleState.suspension_reason = "definition_unavailable_confirmed";
+        const created = this.createIncident({
+          session,
+          state: staleState,
+          reason: "definition_unavailable_confirmed",
+          generation,
+          timestamp,
+        });
+        if (created.created) createdIncidents.push(created.incident);
+        if (firstUnavailable || created.created) {
+          this.appendEvidence(staleState, "session-suspended", {
+            occurrenceId,
+            reason: "definition_unavailable_confirmed",
+            recordedAt: timestamp,
+          });
+        }
+      }
+      nextStates.push(staleState);
       mutated = true;
     }
 
@@ -1106,7 +1514,7 @@ export class SessionLoopDefinitionService {
       session.loops = nextStates;
       session.updated_at = timestamp;
     }
-    return { applies: true, mutated, session };
+    return { applies: true, mutated, session, createdIncidents };
   }
 
   syncLiveRuntimeFromLifecycleSession(session) {
@@ -1123,15 +1531,35 @@ export class SessionLoopDefinitionService {
     runtime.updated_at = session.updated_at;
   }
 
-  reconcileLifecycleForFolder({ storage }) {
+  reconcileLifecycleForFolder({ storage, explicitDeletedLoopId = null }) {
     const lifecycle = this.lifecycleStore.read();
+    const generation = this.nextFolderGeneration(storage, lifecycle);
     let mutated = false;
     let matchedSessionCount = 0;
+    const createdIncidents = [];
     for (const session of lifecycle.sessions) {
-      const result = this.reconcileLifecycleSession({ session, storage });
+      const result = this.reconcileLifecycleSession({
+        session,
+        storage,
+        generation,
+        explicitDeletedLoopId,
+      });
       if (!result.applies) continue;
       matchedSessionCount += 1;
       mutated = result.mutated || mutated;
+      for (const incident of result.createdIncidents || []) {
+        createdIncidents.push({
+          incident,
+          session: {
+            host_session_id: session.host_session_id,
+            agent_id: session.agent_id,
+            agent_folder: session.agent_folder,
+          },
+          state: session.loops.find((state) =>
+            (state.incidents || []).some((candidate) => candidate.id === incident.id)
+          ) || null,
+        });
+      }
     }
     const committed = mutated
       ? this.lifecycleStore.writeSessions(lifecycle.sessions)
@@ -1145,6 +1573,8 @@ export class SessionLoopDefinitionService {
       lifecycle: committed,
       mutated,
       matched_session_count: matchedSessionCount,
+      definition_generation: generation,
+      incident_count: createdIncidents.length,
     };
   }
 
@@ -1204,6 +1634,14 @@ export class SessionLoopDefinitionService {
         mutatedCount += 1;
         continue;
       }
+      const alreadySuspendedForLifecycle =
+        state.enabled === true &&
+        state.status === "suspended" &&
+        state.suspension_reason === resetReason &&
+        state.cadence_anchor_at === null &&
+        state.next_run_at === null &&
+        state.pending_occurrence === null;
+      if (alreadySuspendedForLifecycle) continue;
       const hadRuntimeAuthority =
         state.enabled === true ||
         state.status === "active" ||
@@ -1220,28 +1658,33 @@ export class SessionLoopDefinitionService {
         });
         cancelledCount += 1;
       }
-      state.enabled = false;
-      state.status = "disabled";
+      const enabledIntent = state.enabled === true;
+      state.enabled = enabledIntent;
+      state.status = enabledIntent ? "suspended" : "disabled";
       state.cadence_anchor_at = null;
       state.next_run_at = null;
       state.pending_occurrence = null;
-      state.suspension_reason = resetReason;
+      state.suspension_reason = enabledIntent ? resetReason : state.suspension_reason;
       state.last_error = null;
-      this.appendEvidence(state, "disabled", {
+      this.appendEvidence(state, enabledIntent ? "session-suspended" : "disabled", {
         occurrenceId,
         reason: resetReason,
         recordedAt: timestamp,
       });
       runtime.states.set(state.id, state);
-      disabledCount += 1;
+      if (!enabledIntent) disabledCount += 1;
       mutatedCount += 1;
     }
     if (mutatedCount > 0) this.persistRuntime(runtime);
+    this.sessions.delete(runtime.host_session_id);
     return {
-      status: "disabled",
+      status: "intent_preserved_runtime_suspended",
       host_session_id: runtime.host_session_id,
       runtime_state_count: runtime.states.size,
       disabled_count: disabledCount,
+      enabled_intent_preserved_count: [...runtime.states.values()].filter(
+        (state) => state.enabled === true
+      ).length,
       cancelled_count: cancelledCount,
       idempotent: mutatedCount === 0,
       reason: resetReason,
@@ -1364,7 +1807,7 @@ export class SessionLoopDefinitionService {
   }) {
     const sessionId = normalizeRequiredString(hostSessionId, "hostSessionId");
     const normalizedAgentId = normalizeRequiredString(agentId, "agentId");
-    const storage = this.store.readDefinitions(agentFolder);
+    const storage = this.readDefinitionsForReconciliation(agentFolder);
     const hadLiveRuntime = this.sessions.has(sessionId);
     const runtime = this.buildRuntimeFromLifecycle({
       sessionId,
@@ -1372,14 +1815,44 @@ export class SessionLoopDefinitionService {
       agentFolder,
       storage,
     });
-    const defaultOffReset = !hadLiveRuntime
-      ? this.resetRuntimeAuthorityForLifecycle({
-          runtime,
-          reason: defaultOffReason,
-        })
-      : null;
+    let reconstructed = null;
+    if (!hadLiveRuntime) {
+      const timestamp = nowIso(this.clock);
+      let mutated = false;
+      for (const state of runtime.states.values()) {
+        if (
+          state.enabled !== true ||
+          !["active", "suspended"].includes(state.status) ||
+          state.availability_state !== "available"
+        ) continue;
+        const definition = storage.loops.find((entry) => entry.id === state.id);
+        if (!definition || state.definition_revision !== definitionRevision(definition)) {
+          continue;
+        }
+        state.cadence_anchor_at = timestamp;
+        state.status = "active";
+        state.suspension_reason = null;
+        state.next_run_at = computeFirstCadenceBoundaryAfter({
+          anchorAt: timestamp,
+          intervalMs: definition.interval_ms,
+          after: timestamp,
+        });
+        state.pending_occurrence = null;
+        this.appendEvidence(state, "session-resumed", {
+          reason: "durable_enabled_intent_reconstructed_fresh_cadence",
+          recordedAt: timestamp,
+        });
+        mutated = true;
+      }
+      if (mutated) this.persistRuntime(runtime);
+      reconstructed = {
+        status: "intent_reconstructed",
+        reason: defaultOffReason,
+        lifecycle_mutated: mutated,
+      };
+    }
     this.sessions.set(sessionId, runtime);
-    return { runtime, storage, defaultOffReset };
+    return { runtime, storage, defaultOffReset: reconstructed };
   }
 
   ensureRuntimeSession(options) {
@@ -1406,7 +1879,13 @@ export class SessionLoopDefinitionService {
       agentId,
       agentFolder,
     });
-    return storage.loops.map((definition) =>
+    const definitions = new Map(storage.loops.map((definition) => [definition.id, definition]));
+    for (const state of runtime.states.values()) {
+      if (!definitions.has(state.id) && state.definition_snapshot) {
+        definitions.set(state.id, state.definition_snapshot);
+      }
+    }
+    return [...definitions.values()].map((definition) =>
       this.serializeForGui({ definition, runtime })
     );
   }
@@ -1599,14 +2078,12 @@ export class SessionLoopDefinitionService {
     }
     const refreshed = { runtime, storage: result.storage };
     if (typeof enabled === "boolean") {
-      this.setRuntimeEnabled({
-        runtime: refreshed.runtime,
-        definition: result.definition,
-        enabled,
-        rebase: result.status === "updated",
-      });
+      this.setRuntimeEnabled({ runtime, definition: result.definition, enabled });
       result.desired_enabled = enabled;
       result.previous_enabled = previousEnabled;
+    } else if (result.status === "updated") {
+      result.desired_enabled = null;
+      result.previous_enabled = previousEnabled;
     }
     return {
       status: result.status,
@@ -1675,7 +2152,11 @@ export class SessionLoopDefinitionService {
         agentFolder,
         loopId: scheduleId,
       },
-      () => this.reconcileLifecycleForFolder({ storage: result.storage })
+      () =>
+        this.reconcileLifecycleForFolder({
+          storage: result.storage,
+          explicitDeletedLoopId: scheduleId,
+        })
     );
     return {
       status: "deleted",
@@ -1722,7 +2203,7 @@ export class SessionLoopDefinitionService {
         };
     const removed = this.sessions.delete(sessionId);
     return {
-      status: runtime ? "disabled" : "already_clear",
+      status: runtime ? "intent_preserved_runtime_suspended" : "already_clear",
       host_session_id: sessionId,
       removed,
       runtime_state_count: runtimeStateCount,
@@ -1854,6 +2335,12 @@ export class SessionLoopDefinitionService {
         state.pending_occurrence = null;
       }
       state.last_error = null;
+      state.availability_state = "available";
+      state.unavailable_since = null;
+      state.unavailable_observations = 0;
+      state.candidate_definition = null;
+      state.candidate_revision = null;
+      this.resolveCurrentIncident(state, now);
       this.appendEvidence(state, "enabled", {
         reason: wasEnabled && !rebase ? "idempotent_enabled_intent" : "owner_enabled",
       });
@@ -1866,6 +2353,7 @@ export class SessionLoopDefinitionService {
       state.next_run_at = null;
       if (!occurrenceWasDispatching) state.pending_occurrence = null;
       state.suspension_reason = "owner_disabled";
+      this.resolveCurrentIncident(state, nowIso(this.clock));
       if (pendingOccurrenceId && !occurrenceWasDispatching) {
         this.appendEvidence(state, "cancelled", {
           occurrenceId: pendingOccurrenceId,
@@ -1884,6 +2372,63 @@ export class SessionLoopDefinitionService {
     return state;
   }
 
+  resolveIncidentForGui({
+    hostSessionId,
+    agentId,
+    agentFolder,
+    scheduleId,
+    action,
+  }) {
+    return this.withAgentFolderMutation(agentFolder, (canonicalFolder) => {
+      const { runtime, storage } = this.ensureRuntimeSessionUnlocked({
+        hostSessionId,
+        agentId,
+        agentFolder: canonicalFolder,
+      });
+      const state = runtime.states.get(scheduleId);
+      if (!state) throw new Error("Loop lifecycle state not found for recovery");
+      const incident = this.currentIncident(state);
+      if (!incident) throw new Error("Loop has no unresolved incident");
+      const normalizedAction = normalizeRequiredString(action, "loop recovery action");
+      const definition = storage.loops.find((entry) => entry.id === scheduleId) || null;
+      if (normalizedAction === "keep_disabled") {
+        if (definition) {
+          state.definition_revision = definitionRevision(definition);
+          state.definition_snapshot = snapshotDefinition(definition);
+        }
+        state.availability_state = definition ? "available" : state.availability_state;
+        state.candidate_definition = null;
+        state.candidate_revision = null;
+        state.enabled = false;
+        state.status = "disabled";
+        state.cadence_anchor_at = null;
+        state.next_run_at = null;
+        state.pending_occurrence = null;
+        state.suspension_reason = "owner_disabled";
+        this.resolveCurrentIncident(state, nowIso(this.clock));
+        this.appendEvidence(state, "disabled", { reason: "owner_kept_disabled" });
+        this.persistRuntime(runtime);
+      } else if (["restore", "restore_previous_enabled_state"].includes(normalizedAction)) {
+        if (!definition || definitionRevision(definition) !== state.definition_revision) {
+          throw new Error("The original Loop definition must return before it can be restored");
+        }
+        state.availability_state = "available";
+        state.unavailable_since = null;
+        state.unavailable_observations = 0;
+        this.setRuntimeEnabled({ runtime, definition, enabled: true, rebase: true });
+      } else {
+        throw new Error(`Unsupported Loop recovery action ${normalizedAction}`);
+      }
+      const projectionDefinition = definition || state.definition_snapshot;
+      return {
+        status: "incident_resolved",
+        action: normalizedAction,
+        incident_id: incident.id,
+        schedule: this.serializeForGui({ definition: projectionDefinition, runtime }),
+      };
+    });
+  }
+
   buildOccurrence(definition, state) {
     const dueAt = normalizeOptionalIsoTimestamp(
       state.next_run_at,
@@ -1931,7 +2476,7 @@ export class SessionLoopDefinitionService {
               agentFolder: canonicalFolder,
             },
             () => {
-              const currentStorage = this.store.readDefinitions(canonicalFolder);
+              const currentStorage = this.readDefinitionsForReconciliation(canonicalFolder);
               this.reconcileLifecycleForFolder({ storage: currentStorage });
               return currentStorage;
             }
@@ -1987,6 +2532,23 @@ export class SessionLoopDefinitionService {
     return due;
   }
 
+  refreshDueLoopForDispatch({ runtime, definition, state }) {
+    const occurrenceId = state.pending_occurrence?.occurrence_id;
+    return this.withAgentFolderMutation(runtime.agent_folder, (canonicalFolder) => {
+      const storage = this.readDefinitionsForReconciliation(canonicalFolder);
+      this.reconcileLifecycleForFolder({ storage });
+      const currentDefinition = storage.loops.find((entry) => entry.id === definition.id);
+      const currentState = runtime.states.get(definition.id);
+      if (!currentDefinition || !currentState || !occurrenceId ||
+          definitionRevision(currentDefinition) !== definitionRevision(definition) ||
+          currentState.definition_revision !== definitionRevision(definition) ||
+          currentState.enabled !== true || currentState.status !== "active" ||
+          currentState.pending_occurrence?.occurrence_id !== occurrenceId ||
+          currentState.pending_occurrence.state === "dispatching") return null;
+      return { runtime, definition: currentDefinition, state: currentState };
+    });
+  }
+
   recordSkipped({ runtime, definition, state, triggeredAt, reason }) {
     if (!state.pending_occurrence) {
       throw new Error("Busy Loop retry requires a pending occurrence");
@@ -2065,26 +2627,34 @@ export class SessionLoopDefinitionService {
       !durableState.pending_occurrence ||
       durableState.pending_occurrence.occurrence_id !== expectedOccurrenceId
     ) {
-      if (
-        durableState.enabled !== true &&
-        durableState.pending_occurrence === null
-      ) {
+      if (durableState.pending_occurrence === null) {
         Object.assign(state, durableState);
         state.dispatch_count += 1;
         state.last_run_at = triggeredAt;
-        state.last_status = "dispatched-after-lifecycle-disable";
+        state.last_status = durableState.enabled === true
+          ? "dispatched-after-lifecycle-reconstruction"
+          : "dispatched-after-lifecycle-disable";
         state.last_error = null;
         state.last_dispatched_message_id = dispatchedMessageId;
         this.appendEvidence(state, "succeeded", {
           occurrenceId: expectedOccurrenceId,
-          reason: "matrix_append_committed_after_lifecycle_default_off",
+          reason: durableState.enabled === true
+            ? "matrix_append_committed_after_intent_preserving_reconstruction"
+            : "matrix_append_committed_after_lifecycle_default_off",
           appendIdentity: matrixEventId || dispatchedMessageId,
           recordedAt: triggeredAt,
         });
         this.persistState(runtime, state);
         return state;
       }
-      throw new Error("Loop occurrence authority changed before success commit");
+      this.persistTerminalEvidence(runtime, {
+        transition: "succeeded", recorded_at: triggeredAt, loop_id: definition.id,
+        occurrence_id: expectedOccurrenceId,
+        reason: "matrix_append_committed_after_occurrence_superseded",
+        append_identity_sha256: hashText(matrixEventId || dispatchedMessageId),
+      });
+      Object.assign(state, durableState);
+      return state;
     }
     Object.assign(state, durableState);
     if (!state.pending_occurrence) {
@@ -2139,13 +2709,12 @@ export class SessionLoopDefinitionService {
       !durableState.pending_occurrence ||
       durableState.pending_occurrence.occurrence_id !== expectedOccurrenceId
     ) {
-      if (
-        durableState.enabled !== true &&
-        durableState.pending_occurrence === null
-      ) {
+      if (durableState.pending_occurrence === null) {
         Object.assign(state, durableState);
         state.last_run_at = triggeredAt;
-        state.last_status = "failed-after-lifecycle-disable";
+        state.last_status = durableState.enabled === true
+          ? "failed-after-lifecycle-reconstruction"
+          : "failed-after-lifecycle-disable";
         state.last_error = reason;
         this.appendEvidence(state, "failed", {
           occurrenceId: expectedOccurrenceId,
@@ -2155,7 +2724,13 @@ export class SessionLoopDefinitionService {
         this.persistState(runtime, state);
         return state;
       }
-      throw new Error("Loop occurrence authority changed before failure commit");
+      this.persistTerminalEvidence(runtime, {
+        transition: "failed", recorded_at: triggeredAt, loop_id: definition.id,
+        occurrence_id: expectedOccurrenceId, reason,
+        append_identity_sha256: null,
+      });
+      Object.assign(state, durableState);
+      return state;
     }
     Object.assign(state, durableState);
     if (!state.pending_occurrence) {
@@ -2209,7 +2784,7 @@ export class SessionLoopDefinitionService {
               agentFolder: canonicalFolder,
             },
             () => {
-              const currentStorage = this.store.readDefinitions(canonicalFolder);
+              const currentStorage = this.readDefinitionsForReconciliation(canonicalFolder);
               this.reconcileLifecycleForFolder({ storage: currentStorage });
               return currentStorage;
             }
@@ -2221,7 +2796,7 @@ export class SessionLoopDefinitionService {
       const loops = [];
       for (const [loopId, state] of runtime.states.entries()) {
         const definition = definitionsById.get(loopId);
-        if (!definition || state.enabled !== true) continue;
+        if (!definition || state.enabled !== true || state.status !== "active") continue;
         loops.push({
           loop_id: loopId,
           enabled: true,
@@ -2235,6 +2810,7 @@ export class SessionLoopDefinitionService {
           cadence_anchor_at: state.cadence_anchor_at || null,
           pending_occurrence: state.pending_occurrence || null,
           interval_ms: definition.interval_ms,
+          definition_revision: state.definition_revision,
           runtime_state_owner: SESSION_LOOP_RUNTIME_OWNER,
           definition_storage_owner: SESSION_LOOP_DEFINITION_STORAGE_OWNER,
         });
@@ -2258,7 +2834,12 @@ export class SessionLoopDefinitionService {
 
   restoreHostRestartRuntimeState(
     snapshot = {},
-    { restartId, restoredAt, restoredSessionIds = null } = {}
+    {
+      restartId,
+      restoredAt,
+      restoredSessionIds = null,
+      loopRestorePolicy = "default_off",
+    } = {}
   ) {
     const runtimeSessions = Array.isArray(snapshot.runtime_sessions)
       ? snapshot.runtime_sessions
@@ -2270,6 +2851,7 @@ export class SessionLoopDefinitionService {
           )
         )
       : null;
+    const restored = [];
     const disabled = [];
     const skipped = [];
     const timestamp = restoredAt || nowIso(this.clock);
@@ -2309,6 +2891,42 @@ export class SessionLoopDefinitionService {
             });
             continue;
           }
+          const revisionMatches =
+            typeof loop.definition_revision === "string" &&
+            loop.definition_revision === definitionRevision(definition);
+          if (
+            loopRestorePolicy === "restore_enabled_with_fresh_cadence" &&
+            sessionRuntimeRestored &&
+            revisionMatches
+          ) {
+            this.setRuntimeEnabled({
+              runtime,
+              definition,
+              enabled: true,
+              rebase: true,
+            });
+            restored.push({
+              host_session_id: entry.host_session_id,
+              loop_id: definition.id,
+              restart_id: restartId || null,
+              enabled: true,
+              next_run_at: runtime.states.get(definition.id)?.next_run_at || null,
+              reason: "restore_enabled_with_fresh_cadence",
+            });
+            continue;
+          }
+          const reason = loopRestorePolicy !== "restore_enabled_with_fresh_cadence"
+            ? "legacy_policy_default_off"
+            : !sessionRuntimeRestored
+              ? "session_restore_failed"
+              : "definition_revision_changed";
+          state.enabled = false;
+          state.status = "disabled";
+          state.cadence_anchor_at = null;
+          state.next_run_at = null;
+          state.pending_occurrence = null;
+          state.suspension_reason = reason;
+          this.persistRuntime(runtime);
           disabled.push({
             host_session_id: entry.host_session_id,
             loop_id: definition.id,
@@ -2317,7 +2935,7 @@ export class SessionLoopDefinitionService {
             enabled: false,
             pending_occurrence_id: null,
             next_run_at: null,
-            reason: resetReason,
+            reason,
             loops_json_mutated: false,
           });
         }
@@ -2332,11 +2950,12 @@ export class SessionLoopDefinitionService {
       }
     }
     return {
-      restored: [],
+      restored,
       disabled,
       skipped,
       restored_at: timestamp,
-      default_off: true,
+      default_off: loopRestorePolicy !== "restore_enabled_with_fresh_cadence",
+      loop_restore_policy: loopRestorePolicy,
     };
   }
 
@@ -2436,11 +3055,19 @@ export class SessionLoopDefinitionService {
       definition_revision: state.definition_revision,
       definition_revision_algorithm:
         SESSION_LOOP_DEFINITION_REVISION_ALGORITHM,
-      enabled: state.enabled === true && state.status === "active",
+      enabled: state.enabled === true,
       enabled_intent: state.enabled === true,
       runnable: state.enabled === true && state.status === "active",
       status: state.status,
       suspension_reason: state.suspension_reason,
+      definition_generation: state.definition_generation || 0,
+      definition_availability: state.availability_state || "available",
+      unavailable_since: state.unavailable_since || null,
+      unavailable_observations: state.unavailable_observations || 0,
+      candidate_definition_revision: state.candidate_revision || null,
+      incidents: (state.incidents || []).map((incident) => ({ ...incident })),
+      active_incident: this.currentIncident(state),
+      recovery_options: this.currentIncident(state)?.recovery_options || [],
       cadence_anchor_at: state.cadence_anchor_at,
       next_run_at: state.next_run_at,
       pending_occurrence: state.pending_occurrence