@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/workflow/schedules/github-issue-watch.ts

@@ -0,0 +1,158 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { resolveTrustedExecutable } from '../../shared/trusted-executable';
+
+const execFileAsync = promisify(execFile);
+
+export interface GithubIssueWatchIssue {
+  number: number;
+  title: string;
+  state: 'open' | 'closed';
+  updatedAt: string;
+  url: string;
+}
+
+export interface GithubIssueWatchState {
+  schemaVersion: 1;
+  observedAt: string;
+  signatures: Record<string, string>;
+}
+
+export interface GithubIssueWatchObservation {
+  status: 'baseline' | 'unchanged' | 'changed';
+  shouldWake: boolean;
+  changedOpenIssues: GithubIssueWatchIssue[];
+  issues: GithubIssueWatchIssue[];
+  nextState: GithubIssueWatchState;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function boundedNumber(value: unknown, fallback: number, min: number, max: number): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(min, Math.min(Math.trunc(value), max))
+    : fallback;
+}
+
+function issueSignature(issue: GithubIssueWatchIssue): string {
+  return `${issue.state}:${issue.updatedAt}`;
+}
+
+function normalizeIssue(value: unknown): GithubIssueWatchIssue | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  const number = typeof record.number === 'number' && Number.isFinite(record.number) ? Math.trunc(record.number) : undefined;
+  const title = stringValue(record.title);
+  const state = record.state === 'open' || record.state === 'closed' ? record.state : undefined;
+  const updatedAt = stringValue(record.updatedAt);
+  const url = stringValue(record.url);
+  if (!number || !title || !state || !updatedAt || !url) return undefined;
+  return { number, title, state, updatedAt, url };
+}
+
+export function normalizeGithubIssueWatchState(value: unknown): GithubIssueWatchState | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  const signaturesValue = record.signatures;
+  if (!signaturesValue || typeof signaturesValue !== 'object' || Array.isArray(signaturesValue)) return undefined;
+  const signatures = Object.fromEntries(Object.entries(signaturesValue as Record<string, unknown>)
+    .filter((entry): entry is [string, string] => typeof entry[1] === 'string'));
+  return {
+    schemaVersion: 1,
+    observedAt: stringValue(record.observedAt) ?? new Date(0).toISOString(),
+    signatures,
+  };
+}
+
+export function classifyGithubIssueWatchObservation(
+  issues: GithubIssueWatchIssue[],
+  previousState: GithubIssueWatchState | undefined,
+  options: { since?: string; wakeOnFirstObservation?: boolean; observedAt?: string } = {},
+): GithubIssueWatchObservation {
+  const observedAt = options.observedAt ?? new Date().toISOString();
+  const signatures = Object.fromEntries(issues.map((issue) => [String(issue.number), issueSignature(issue)]));
+  const firstObservation = !previousState;
+  const sinceMs = options.since ? Date.parse(options.since) : Number.NaN;
+  const changedOpenIssues = issues.filter((issue) => {
+    if (issue.state !== 'open') return false;
+    if (!firstObservation) return previousState.signatures[String(issue.number)] !== issueSignature(issue);
+    if (options.wakeOnFirstObservation === true) return true;
+    return Number.isFinite(sinceMs) && Date.parse(issue.updatedAt) > sinceMs;
+  });
+  return {
+    status: firstObservation ? 'baseline' : changedOpenIssues.length > 0 ? 'changed' : 'unchanged',
+    shouldWake: changedOpenIssues.length > 0,
+    changedOpenIssues,
+    issues,
+    nextState: { schemaVersion: 1, observedAt, signatures },
+  };
+}
+
+const DEFAULT_GH_EXECUTABLE_CANDIDATES = [
+  '/opt/homebrew/bin/gh',
+  '/usr/local/bin/gh',
+  '/usr/bin/gh',
+] as const;
+
+export function resolveGithubIssueWatchExecutable(
+  args: Record<string, unknown>,
+  env: NodeJS.ProcessEnv = process.env,
+  preferredPaths: readonly string[] = DEFAULT_GH_EXECUTABLE_CANDIDATES,
+): string {
+  const configured = stringValue(args.gh_executable) ?? stringValue(env.FORGE_GH_EXECUTABLE);
+  const resolved = resolveTrustedExecutable({
+    name: 'gh',
+    configured,
+    preferredPaths,
+    env,
+  });
+  if (resolved.configuredInvalid) {
+    throw new Error('SCHEDULE_GITHUB_ISSUE_WATCH_GH_EXECUTABLE_INVALID: gh_executable/FORGE_GH_EXECUTABLE must be an absolute executable path.');
+  }
+  if (!resolved.executable) {
+    throw new Error('SCHEDULE_GITHUB_ISSUE_WATCH_GH_EXECUTABLE_NOT_FOUND: GitHub CLI was not found in trusted Homebrew/system locations or PATH.');
+  }
+  return resolved.executable;
+}
+
+export async function executeScheduledGithubIssueWatch(input: {
+  repoRoot: string;
+  args: Record<string, unknown>;
+  observedAt?: string;
+}): Promise<GithubIssueWatchObservation> {
+  const repository = stringValue(input.args.github_repository);
+  if (!repository || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) {
+    throw new Error('SCHEDULE_GITHUB_ISSUE_WATCH_REPOSITORY_REQUIRED');
+  }
+  const limit = boundedNumber(input.args.issue_limit, 50, 10, 100);
+  const timeoutMs = boundedNumber(input.args.timeout_ms, 15_000, 1_000, 60_000);
+  try {
+    const ghExecutable = resolveGithubIssueWatchExecutable(input.args);
+    const result = await execFileAsync(ghExecutable, [
+      'api',
+      '-H', 'Accept: application/vnd.github+json',
+      `repos/${repository}/issues?state=all&sort=updated&direction=desc&per_page=${limit}`,
+      '--jq', 'map(select(.pull_request|not)) | map({number,title,state,updatedAt:.updated_at,url:.html_url})',
+    ], {
+      cwd: input.repoRoot,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      maxBuffer: 2 * 1024 * 1024,
+    });
+    const parsed = JSON.parse(String(result.stdout)) as unknown;
+    if (!Array.isArray(parsed)) throw new Error('GitHub issue response was not an array.');
+    const issues = parsed.map(normalizeIssue).filter((issue): issue is GithubIssueWatchIssue => Boolean(issue));
+    const previousState = normalizeGithubIssueWatchState(input.args.issue_watch_state);
+    return classifyGithubIssueWatchObservation(issues, previousState, {
+      since: stringValue(input.args.issue_watch_since),
+      wakeOnFirstObservation: input.args.wake_on_first_observation === true,
+      observedAt: input.observedAt,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith('SCHEDULE_GITHUB_ISSUE_WATCH_GH_EXECUTABLE_')) throw error;
+    throw new Error(`SCHEDULE_GITHUB_ISSUE_WATCH_FAILED: ${message}`);
+  }
+}

package/src/runtime/workflow/schedules/settlement.ts

@@ -5,22 +5,29 @@ import {
   getSchedule,
   recordScheduleOccurrenceHandoff,
   saveOccurrence,
-  saveSchedule,
+  updateSchedule,
   type ScheduleOccurrenceHandoffInput,
 } from './store';
 
 const TERMINAL_OCCURRENCE_STATUSES = new Set<ScheduleOccurrence['status']>(['succeeded', 'failed', 'shadowed', 'skipped']);
 
-function computeScheduleFailureState(schedule: ReturnType<typeof getSchedule>, nextFailures: number): Pick<ReturnType<typeof getSchedule>, 'consecutiveFailures' | 'nextEligibleAt' | 'enabled' | 'pausedReason'> {
-  const shouldPause = nextFailures >= schedule.policy.maxFailures;
+function computeScheduleBackoff(schedule: ReturnType<typeof getSchedule>, nextFailures: number): string {
   const backoffBase = Math.max(1, schedule.policy.backoffBaseMinutes ?? schedule.policy.cooldownMinutes ?? 1);
   const backoffMax = Math.max(backoffBase, schedule.policy.backoffMaxMinutes ?? 24 * 60);
-  const backoffMinutes = Math.min(backoffMax, backoffBase * (2 ** Math.max(0, nextFailures - 1)));
+  // Persistent readiness failures may span hours or days. Cap the exponent so
+  // the calculation stays bounded even while the observable failure count grows.
+  const exponent = Math.min(16, Math.max(0, nextFailures - 1));
+  const backoffMinutes = Math.min(backoffMax, backoffBase * (2 ** exponent));
+  return new Date(Date.now() + backoffMinutes * 60_000).toISOString();
+}
+
+function computeScheduleFailureState(schedule: ReturnType<typeof getSchedule>, nextFailures: number): Pick<ReturnType<typeof getSchedule>, 'consecutiveFailures' | 'nextEligibleAt' | 'enabled' | 'pausedReason'> {
+  const shouldPause = nextFailures >= schedule.policy.maxFailures;
   return {
     consecutiveFailures: nextFailures,
-    nextEligibleAt: new Date(Date.now() + backoffMinutes * 60_000).toISOString(),
+    nextEligibleAt: computeScheduleBackoff(schedule, nextFailures),
     enabled: shouldPause ? false : schedule.enabled,
-    pausedReason: shouldPause ? 'Maximum consecutive failures reached.' : undefined,
+    pausedReason: shouldPause ? 'Maximum consecutive failures reached.' : schedule.enabled ? undefined : schedule.pausedReason,
   };
 }
 
@@ -55,16 +62,58 @@ export function applyScheduleFailure(
 
   const countFailure = options.countFailure !== false;
   const nextSchedule = options.pauseReason
-    ? saveSchedule(controllerHome, {
-      ...schedule,
+    ? updateSchedule(controllerHome, repoId, scheduleId, (current) => ({
       enabled: false,
       pausedReason: options.pauseReason,
       nextEligibleAt: undefined,
-      consecutiveFailures: countFailure ? schedule.consecutiveFailures + 1 : schedule.consecutiveFailures,
-    })
+      consecutiveFailures: countFailure ? current.consecutiveFailures + 1 : current.consecutiveFailures,
+    }))
     : countFailure
-      ? saveSchedule(controllerHome, { ...schedule, ...computeScheduleFailureState(schedule, schedule.consecutiveFailures + 1) })
-      : schedule;
+      ? updateSchedule(controllerHome, repoId, scheduleId, (current) => computeScheduleFailureState(current, current.consecutiveFailures + 1))
+      : getSchedule(controllerHome, repoId, scheduleId);
+  return { schedule: nextSchedule, occurrence: nextOccurrence };
+}
+
+export function applyScheduleRetryableFailure(
+  controllerHome: string,
+  scheduleId: string,
+  repoId: string,
+  occurrenceId: string,
+  options: {
+    outcome: 'failed' | 'skipped';
+    decision: ScheduleDecisionType;
+    reason: string;
+    countFailure?: boolean;
+  },
+): { schedule: ReturnType<typeof getSchedule>; occurrence?: ScheduleOccurrence } {
+  const occurrence = getOccurrence(controllerHome, repoId, occurrenceId);
+  let nextOccurrence = occurrence;
+  if (occurrence && !TERMINAL_OCCURRENCE_STATUSES.has(occurrence.status)) {
+    nextOccurrence = saveOccurrence(controllerHome, {
+      ...occurrence,
+      status: options.outcome,
+      decision: options.decision,
+      reason: options.reason,
+    });
+  }
+  const countFailure = options.countFailure !== false;
+  const nextSchedule = updateSchedule(controllerHome, repoId, scheduleId, (current) => {
+    const nextFailures = countFailure ? current.consecutiveFailures + 1 : current.consecutiveFailures;
+    const failureState = countFailure && current.enabled
+      ? computeScheduleFailureState(current, nextFailures)
+      : {
+        consecutiveFailures: nextFailures,
+        nextEligibleAt: countFailure
+          ? current.nextEligibleAt
+          : computeScheduleBackoff(current, Math.max(1, nextFailures)),
+        enabled: current.enabled,
+        pausedReason: current.enabled ? undefined : current.pausedReason,
+      };
+    // One transient fault backs off and re-arms. Repeated faults have crossed
+    // the already-declared failure budget and must stop before they consume
+    // further controller sessions or browser interactions.
+    return failureState;
+  });
   return { schedule: nextSchedule, occurrence: nextOccurrence };
 }
 
@@ -98,7 +147,6 @@ export function settleScheduledExecution(
   const occurrenceId = typeof job.payload.occurrenceId === 'string' ? job.payload.occurrenceId : undefined;
   if (!scheduleId || !occurrenceId) return;
   try {
-    const schedule = getSchedule(controllerHome, job.repoId, scheduleId);
     const occurrence = getOccurrence(controllerHome, job.repoId, occurrenceId);
     if (occurrence && !['succeeded', 'failed', 'shadowed', 'skipped'].includes(occurrence.status)) {
       saveOccurrence(controllerHome, {
@@ -131,12 +179,11 @@ export function settleScheduledExecution(
       });
       return;
     }
-    saveSchedule(controllerHome, {
-      ...schedule,
+    updateSchedule(controllerHome, job.repoId, scheduleId, (current) => ({
       consecutiveFailures: 0,
       nextEligibleAt: undefined,
-      pausedReason: undefined,
-    });
+      ...(current.enabled ? { pausedReason: undefined } : {}),
+    }));
   } catch {
     // Job terminal state remains authoritative even if an old schedule record
     // has already been removed. Reconciliation must not be blocked by it.

package/src/runtime/workflow/schedules/store.ts

@@ -1,9 +1,14 @@
 import { createHash, randomUUID } from 'crypto';
-import { existsSync, readdirSync } from 'fs';
+import { existsSync, readdirSync, rmSync } from 'fs';
 import { join } from 'path';
 import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
 import { withControllerLock } from '../../../cli/repositories/locks';
-import { createHandoffItem, getHandoffItem } from '../../control-plane/facade/handoff-inbox-store';
+import {
+  createHandoffItem,
+  getHandoffItem,
+  listHandoffItems,
+  resolveHandoffItem,
+} from '../../control-plane/facade/handoff-inbox-store';
 import { readJsonFile, writeJsonAtomic } from '../../shared/json-files';
 import { appendRuntimeEvent } from '../../evidence/event-ledger';
 import type { RepositorySchedule, ScheduleDecision, ScheduleOccurrence } from './types';
@@ -23,6 +28,7 @@ interface ScheduleRequestRecord {
   createdAt: string;
 }
 type CreateScheduleInput = Omit<RepositorySchedule, 'schemaVersion' | 'revision' | 'scheduleId' | 'createdAt' | 'updatedAt' | 'consecutiveFailures'>;
+type ScheduleMutableUpdate = Partial<Omit<RepositorySchedule, 'schemaVersion' | 'revision' | 'scheduleId' | 'repoId' | 'requestId' | 'createdAt' | 'updatedAt'>>;
 
 export interface ScheduleOccurrenceHandoffInput {
   title: string;
@@ -57,6 +63,30 @@ function occurrenceIndexPath(controllerHome: string, repoId: string): string {
 function requestPath(controllerHome: string, repoId: string, requestId: string): string {
   return join(schedulesRoot(controllerHome, repoId), 'indexes', 'requests', `${createHash('sha256').update(requestId).digest('hex')}.json`);
 }
+
+const EXTERNAL_CONTROLLER_WAKE_MAX_FAILURES = 3;
+const EXTERNAL_CONTROLLER_WAKE_DAILY_BUDGET_MINUTES = 60;
+const EXTERNAL_CONTROLLER_WAKE_MIN_COOLDOWN_MINUTES = 10;
+
+function boundedSchedulePolicy(schedule: RepositorySchedule): RepositorySchedule['policy'] {
+  const policy = {
+    ...schedule.policy,
+    backoffBaseMinutes: Math.max(1, schedule.policy.backoffBaseMinutes ?? schedule.policy.cooldownMinutes ?? 1),
+    backoffMaxMinutes: Math.max(1, schedule.policy.backoffMaxMinutes ?? 24 * 60),
+  };
+  if (schedule.action.operation !== 'external_controller_wake') return policy;
+  // A Work-bound controller wake is expensive and can affect the user's
+  // browser. No schedule payload may convert a transient tool outage into an
+  // all-day retry loop. Larger work needs an explicit future user action after
+  // the bounded lane records useful failure evidence.
+  return {
+    ...policy,
+    maxFailures: Math.max(1, Math.min(policy.maxFailures, EXTERNAL_CONTROLLER_WAKE_MAX_FAILURES)),
+    dailyBudgetMinutes: Math.max(1, Math.min(policy.dailyBudgetMinutes, EXTERNAL_CONTROLLER_WAKE_DAILY_BUDGET_MINUTES)),
+    cooldownMinutes: Math.max(policy.cooldownMinutes, EXTERNAL_CONTROLLER_WAKE_MIN_COOLDOWN_MINUTES),
+    backoffBaseMinutes: Math.max(policy.backoffBaseMinutes, EXTERNAL_CONTROLLER_WAKE_MIN_COOLDOWN_MINUTES),
+  };
+}
 function canonical(value: unknown): unknown {
   if (Array.isArray(value)) return value.map(canonical);
   if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value as Record<string, unknown>)
@@ -131,22 +161,62 @@ export function getSchedule(controllerHome: string, repoId: string, scheduleId:
     ...schedule,
     revision: Number.isFinite(schedule.revision) ? schedule.revision : 1,
     requestId: schedule.requestId || `legacy-schedule:${schedule.scheduleId}`,
-    policy: {
-      ...schedule.policy,
-      backoffBaseMinutes: Math.max(1, schedule.policy.backoffBaseMinutes ?? schedule.policy.cooldownMinutes ?? 1),
-      backoffMaxMinutes: Math.max(1, schedule.policy.backoffMaxMinutes ?? 24 * 60),
-    },
+    policy: boundedSchedulePolicy(schedule),
     consecutiveNoops: Math.max(0, schedule.consecutiveNoops ?? 0),
   };
 }
 
+function persistScheduleRevision(
+  controllerHome: string,
+  current: RepositorySchedule,
+  candidate: RepositorySchedule,
+): RepositorySchedule {
+  const next: RepositorySchedule = {
+    ...candidate,
+    schemaVersion: current.schemaVersion,
+    revision: current.revision + 1,
+    scheduleId: current.scheduleId,
+    repoId: current.repoId,
+    requestId: current.requestId,
+    createdAt: current.createdAt,
+    updatedAt: new Date().toISOString(),
+  };
+  writeJsonAtomic(schedulePath(controllerHome, next.repoId, next.scheduleId), next);
+  appendRuntimeEvent(controllerHome, { repoId: next.repoId, entityType: 'schedule', entityId: next.scheduleId, eventType: 'schedule_updated', requestId: next.requestId, revision: next.revision, data: { enabled: next.enabled, pausedReason: next.pausedReason } });
+  return next;
+}
+
+/**
+ * Persist a caller-owned Schedule snapshot only when its revision is still the
+ * current authority. User/configuration mutations use this path so stale
+ * writers fail closed instead of overwriting a newer decision.
+ */
 export function saveSchedule(controllerHome: string, schedule: RepositorySchedule): RepositorySchedule {
   return withControllerLock(controllerHome, { scope: 'task', repoId: schedule.repoId, taskId: `schedule-${schedule.scheduleId}` }, `save-schedule:${schedule.scheduleId}`, () => {
     const current = getSchedule(controllerHome, schedule.repoId, schedule.scheduleId);
-    const next = { ...schedule, revision: current.revision + 1, updatedAt: new Date().toISOString() };
-    writeJsonAtomic(schedulePath(controllerHome, next.repoId, next.scheduleId), next);
-    appendRuntimeEvent(controllerHome, { repoId: next.repoId, entityType: 'schedule', entityId: next.scheduleId, eventType: 'schedule_updated', requestId: next.requestId, revision: next.revision, data: { enabled: next.enabled, pausedReason: next.pausedReason } });
-    return next;
+    if (schedule.revision !== current.revision) {
+      throw new Error(`SCHEDULE_REVISION_CONFLICT: ${schedule.scheduleId}:expected=${schedule.revision}:actual=${current.revision}`);
+    }
+    return persistScheduleRevision(controllerHome, current, schedule);
+  }, 10_000);
+}
+
+/**
+ * Apply runtime-owned settlement/observation fields to the latest Schedule
+ * authority while holding the Schedule lock. Identity and revision fields are
+ * never writable through this path. Long-running occurrences use this instead
+ * of replaying a stale whole-record snapshot after user state may have changed.
+ */
+export function updateSchedule(
+  controllerHome: string,
+  repoId: string,
+  scheduleId: string,
+  update: (current: RepositorySchedule) => ScheduleMutableUpdate,
+): RepositorySchedule {
+  return withControllerLock(controllerHome, { scope: 'task', repoId, taskId: `schedule-${scheduleId}` }, `update-schedule:${scheduleId}`, () => {
+    const current = getSchedule(controllerHome, repoId, scheduleId);
+    const changes = update(current);
+    return persistScheduleRevision(controllerHome, current, { ...current, ...changes });
   }, 10_000);
 }
 
@@ -159,17 +229,124 @@ export function listSchedules(controllerHome: string, repoId: string): Repositor
   } catch { return []; }
 }
 
+export function deleteSchedule(controllerHome: string, repoId: string, scheduleId: string): RepositorySchedule {
+  return withControllerLock(controllerHome, { scope: 'task', repoId, taskId: `schedule-${scheduleId}` }, `delete-schedule:${scheduleId}`, () => {
+    const current = getSchedule(controllerHome, repoId, scheduleId);
+    if (current.enabled) throw new Error(`SCHEDULE_DELETE_REQUIRES_PAUSED: ${scheduleId}`);
+    if (listActiveOccurrences(controllerHome, repoId, scheduleId).length > 0) {
+      throw new Error(`SCHEDULE_DELETE_ACTIVE_OCCURRENCE: ${scheduleId}`);
+    }
+    rmSync(schedulePath(controllerHome, repoId, scheduleId), { force: true });
+    const requestRecordPath = requestPath(controllerHome, repoId, current.requestId);
+    if (existsSync(requestRecordPath)) {
+      const record = readJsonFile<ScheduleRequestRecord>(requestRecordPath);
+      if (record.scheduleId === scheduleId) rmSync(requestRecordPath, { force: true });
+    }
+    appendRuntimeEvent(controllerHome, {
+      repoId,
+      entityType: 'schedule',
+      entityId: scheduleId,
+      eventType: 'schedule_deleted',
+      requestId: current.requestId,
+      revision: current.revision + 1,
+      data: { name: current.name },
+    });
+    return current;
+  }, 10_000);
+}
+
+function scheduleFailureClass(reason: string): string {
+  const trimmed = reason.trim();
+  const explicitCode = trimmed.match(/^([A-Z][A-Z0-9_]{2,})(?::|\b)/)?.[1];
+  if (explicitCode) return explicitCode;
+  const prefix = (trimmed.split(':', 1)[0] ?? trimmed)
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase()
+    .slice(0, 120);
+  return prefix || 'unknown_failure';
+}
+
+function activeScheduleFailureHandoff(
+  controllerHome: string,
+  repoId: string,
+  scheduleId: string,
+  creationReason: ScheduleOccurrenceHandoffInput['creationReason'],
+  reason: string,
+) {
+  const failureClass = scheduleFailureClass(reason);
+  return listHandoffItems({ controllerHome, repoId, status: 'active', limit: 100 }).find((item) => (
+    item.currentState?.taskId === scheduleId
+    && item.creationReason === creationReason
+    && scheduleFailureClass(item.reason) === failureClass
+  ));
+}
+
+function stableScheduleFailureHandoffId(
+  controllerHome: string,
+  repoId: string,
+  scheduleId: string,
+  creationReason: ScheduleOccurrenceHandoffInput['creationReason'],
+  reason: string,
+  occurrenceId: string,
+): string {
+  const digest = createHash('sha256')
+    .update(`${scheduleId}:${creationReason}:${scheduleFailureClass(reason)}`)
+    .digest('hex')
+    .slice(0, 20);
+  const baseId = `schedule-failure-${digest}`;
+  if (!getHandoffItem({ controllerHome, repoId }, baseId)) return baseId;
+  // A previous failure streak may already have resolved the stable item. Handoff
+  // records are immutable apart from lifecycle status, so use one new epoch id;
+  // subsequent failures in this streak will discover and reuse the active item.
+  const epoch = createHash('sha256').update(occurrenceId).digest('hex').slice(0, 8);
+  return `${baseId}-${epoch}`;
+}
+
+function resolveRecoveredScheduleFailureHandoffs(controllerHome: string, occurrence: ScheduleOccurrence): void {
+  try {
+    const active = listHandoffItems({ controllerHome, repoId: occurrence.repoId, status: 'active', limit: 100 })
+      .filter((item) => (
+        item.currentState?.taskId === occurrence.scheduleId
+        && item.creationReason === 'repeated_infrastructure_failure'
+      ));
+    for (const item of active) {
+      try {
+        resolveHandoffItem(
+          { controllerHome, repoId: occurrence.repoId },
+          item.id,
+          {
+            decision: `Schedule ${occurrence.scheduleId} recovered on occurrence ${occurrence.occurrenceId}.`,
+            resolver: 'schedule-runtime',
+          },
+        );
+      } catch {
+        // The succeeded occurrence remains authoritative. Inbox cleanup is
+        // best-effort and must never turn schedule recovery into a failure.
+      }
+    }
+  } catch {
+    // Preserve successful Schedule settlement even if Inbox storage is unavailable.
+  }
+}
+
 export function saveOccurrence(controllerHome: string, occurrence: ScheduleOccurrence): ScheduleOccurrence {
-  return withControllerLock(controllerHome, { scope: 'task', repoId: occurrence.repoId, taskId: `schedule-${occurrence.scheduleId}` }, `save-occurrence:${occurrence.occurrenceId}`, () => {
+  const next = withControllerLock(controllerHome, { scope: 'task', repoId: occurrence.repoId, taskId: `schedule-${occurrence.scheduleId}` }, `save-occurrence:${occurrence.occurrenceId}`, () => {
     const existingPath = occurrencePath(controllerHome, occurrence.repoId, occurrence.occurrenceId);
     const previous = existsSync(existingPath) ? readJsonFile<ScheduleOccurrence>(existingPath) : undefined;
-    const next = { ...occurrence, revision: (previous?.revision ?? occurrence.revision ?? 0) + 1, updatedAt: new Date().toISOString() };
-    writeJsonAtomic(existingPath, next);
-    upsertOccurrenceIndexUnlocked(controllerHome, next);
-    const schedule = getSchedule(controllerHome, next.repoId, next.scheduleId);
-    appendRuntimeEvent(controllerHome, { repoId: next.repoId, entityType: 'occurrence', entityId: next.occurrenceId, eventType: `occurrence_${next.status}`, requestId: `${schedule.requestId}:${next.windowKey}`, revision: next.revision, correlationId: next.scheduleId, data: { decision: next.decision, jobId: next.jobId, reason: next.reason } });
-    return next;
+    const expectedRevision = previous?.revision ?? 0;
+    if (occurrence.revision !== expectedRevision) {
+      throw new Error(`SCHEDULE_OCCURRENCE_REVISION_CONFLICT: ${occurrence.occurrenceId}:expected=${occurrence.revision}:actual=${expectedRevision}`);
+    }
+    const saved = { ...occurrence, revision: expectedRevision + 1, updatedAt: new Date().toISOString() };
+    writeJsonAtomic(existingPath, saved);
+    upsertOccurrenceIndexUnlocked(controllerHome, saved);
+    const schedule = getSchedule(controllerHome, saved.repoId, saved.scheduleId);
+    appendRuntimeEvent(controllerHome, { repoId: saved.repoId, entityType: 'occurrence', entityId: saved.occurrenceId, eventType: `occurrence_${saved.status}`, requestId: `${schedule.requestId}:${saved.windowKey}`, revision: saved.revision, correlationId: saved.scheduleId, data: { decision: saved.decision, jobId: saved.jobId, reason: saved.reason } });
+    return saved;
   }, 10_000);
+  if (next.status === 'succeeded') resolveRecoveredScheduleFailureHandoffs(controllerHome, next);
+  return next;
 }
 
 export function getOccurrence(controllerHome: string, repoId: string, occurrenceId: string): ScheduleOccurrence | undefined {
@@ -184,7 +361,20 @@ export function recordScheduleOccurrenceHandoff(
   input: ScheduleOccurrenceHandoffInput,
 ): ScheduleOccurrence {
   if (occurrence.handoffId) return occurrence;
-  const handoffId = `schedule-${occurrence.occurrenceId}`;
+  const reusable = input.creationReason === 'repeated_infrastructure_failure'
+    ? activeScheduleFailureHandoff(controllerHome, occurrence.repoId, schedule.scheduleId, input.creationReason, input.reason)
+    : undefined;
+  if (reusable) return saveOccurrence(controllerHome, { ...occurrence, handoffId: reusable.id });
+  const handoffId = input.creationReason === 'repeated_infrastructure_failure'
+    ? stableScheduleFailureHandoffId(
+      controllerHome,
+      occurrence.repoId,
+      schedule.scheduleId,
+      input.creationReason,
+      input.reason,
+      occurrence.occurrenceId,
+    )
+    : `schedule-${occurrence.occurrenceId}`;
   const evidenceRefs: NonNullable<ScheduleOccurrenceHandoffInput['evidenceRefs']> = [
     { title: `Occurrence ${occurrence.occurrenceId}`, summary: occurrence.reason ?? input.reason, detailLevel: 'summary' as const },
   ];

package/src/runtime/workflow/schedules/types.ts

@@ -10,10 +10,8 @@ export type ScheduleTriggerType =
   | 'manual';
 
 export interface ScheduleCondition {
-  kind: 'repository_clean' | 'job_succeeded' | 'job_terminal' | 'candidate_observation_threshold';
+  kind: 'repository_clean' | 'job_succeeded' | 'job_terminal';
   jobId?: string;
-  semanticKey?: string;
-  observationThreshold?: number;
 }
 
 export interface ScheduleTrigger {
@@ -73,7 +71,7 @@ export interface RepositorySchedule {
   consecutiveNoops?: number;
   nextEligibleAt?: string;
   pausedReason?: string;
-  /** Last deterministic external observation for browser_watch/browser_keepalive. */
+  /** Last deterministic external observation for browser or issue watchers. */
   lastObservationAt?: string;
   lastObservationFingerprint?: string;
   lastObservationChangedAt?: string;