issue-flow 0.18.0 → 0.20.0

package/dist/chunk-44RF3VFG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agents/types.ts","../src/storage/schemas.ts","../src/agents/schemas.ts","../src/storage/lock.ts"],"sourcesContent":["/**\n * The agent layer: a swappable runner inside `runHeadless` / `executeClaude`.\n *\n * The pipeline still talks to those two facades. What changes is the binary\n * they spawn and how its stream is read. Defaults stay Claude, and an\n * unconfigured invocation produces the same argv the project has always used.\n */\n\nimport type { ClaudeUsage } from '../core/metrics.js';\n\n/** Providers the pipeline can invoke. A sixth would add a file, not a refactor. */\nexport type AgentProviderId = 'claude' | 'codex' | 'cursor' | 'antigravity' | 'opencode';\n\nexport const AGENT_PROVIDER_IDS: readonly AgentProviderId[] = [\n  'claude',\n  'codex',\n  'cursor',\n  'antigravity',\n  'opencode',\n];\n\nexport const AGENT_PROVIDER_LIST = AGENT_PROVIDER_IDS.join(', ');\n\n/** The eight invocations that actually call an agent. `init` is not one of them. */\nexport type AgentPhase =\n  | 'analyze'\n  | 'generate'\n  | 'prd'\n  | 'plan'\n  | 'execute'\n  | 'review'\n  | 'pr'\n  | 'pr-review';\n\nexport const AGENT_PHASES: readonly AgentPhase[] = [\n  'analyze',\n  'generate',\n  'prd',\n  'plan',\n  'execute',\n  'review',\n  'pr',\n  'pr-review',\n] as const;\n\nexport function isAgentPhase(value: string): value is AgentPhase {\n  return (AGENT_PHASES as readonly string[]).includes(value);\n}\n\nexport function isAgentProviderId(value: string): value is AgentProviderId {\n  return (AGENT_PROVIDER_IDS as readonly string[]).includes(value);\n}\n\n/**\n * Semantic permission of an invocation, translated by each runner.\n *\n *   read-only  — phases that only inspect (analyze, review, pr-review)\n *   workspace  — phases that write artifacts (generate, prd, plan, pr)\n *   autonomous — the execute loop\n */\nexport type AgentPermission = 'read-only' | 'workspace' | 'autonomous';\n\n/** Default permission of each phase. Analyze writes `analysis.md` via a\n * fallback when the agent cannot write, so it stays in the issue's read-only\n * set: the agent is asked not to mutate the project, and the command writes\n * the artifact itself when needed. */\nexport const DEFAULT_PHASE_PERMISSION: Record<AgentPhase, AgentPermission> = {\n  analyze: 'read-only',\n  generate: 'workspace',\n  prd: 'workspace',\n  plan: 'workspace',\n  execute: 'autonomous',\n  review: 'read-only',\n  pr: 'workspace',\n  'pr-review': 'read-only',\n};\n\n/** Token/cost metrics. Alias of the existing Claude shape so no import breaks. */\nexport type AgentUsage = ClaudeUsage;\n\nexport type AgentEvent =\n  | { kind: 'text'; text: string }\n  | { kind: 'tool'; name: string; detail?: string };\n\n/**\n * What a runner needs to execute one invocation.\n *\n * `onLine` is the watchdog heartbeat: a process writing anything is a process\n * that is alive, including a malformed line. `onEvent` is the normalised\n * stream the UI already consumes.\n */\nexport interface AgentInvocation {\n  prompt: string;\n  phase: AgentPhase;\n  workingDirectory?: string;\n  addDirs?: string[];\n  /** ms; 0 = no limit (the execute loop). */\n  timeout: number;\n  permission: AgentPermission;\n  maxTurns?: number;\n  allowedTools?: string[];\n  onEvent?: (event: AgentEvent) => void;\n  onLine?: (line: string) => void;\n  /**\n   * Silence tolerated before the agent is considered stuck. Absent or `0`\n   * disables the watchdog — verbose headless never had one.\n   */\n  inactivityTimeoutMs?: number;\n  /** Pin this invocation to a provider (L2 reviewer). Skips failover. */\n  forceProvider?: AgentProviderId;\n  /** Telemetry purpose when it is not the phase name (`verify`). */\n  purpose?: 'verify';\n  /** Observability context; it never changes provider behaviour or prompt contents. */\n  iteration?: number;\n  correctionCycle?: number;\n  storyIds?: string[];\n}\n\nexport interface AgentRunResult {\n  success: boolean;\n  result: string;\n  /** Combined raw output, for `isTransientFailure()` / `trimErrorMessage()`. */\n  rawOutput: string;\n  exitCode: number;\n  usage: AgentUsage | null;\n  error: string | null;\n  /** Who actually ran — never inferred afterwards. */\n  agent: { provider: AgentProviderId; model: string | null };\n  sessionId?: string;\n  /** Captured at invocation time and cached per process. */\n  harnessVersion?: string | null;\n}\n\n/**\n * What a runner can do. Declared so a new provider adds a file, not a\n * refactor. The core asks \"does this invocation need extraDirectories?\",\n * never \"which provider is this?\".\n */\nexport interface AgentCapabilities {\n  /** Extra directories beyond the workspace. `flag` is `--add-dir`. */\n  extraDirectories: 'flag' | 'permission-file' | 'none';\n  /** Convenience: `extraDirectories === 'flag'`. */\n  addDirs: boolean;\n  toolAllowlist: boolean;\n  maxTurns: boolean;\n  osSandbox: boolean;\n  modelSelection: boolean;\n  modelDiscovery: boolean;\n  usage: 'tokens-and-cost' | 'tokens-only' | 'none';\n  reportsUsage: boolean;\n  reportsCost: boolean;\n  sessionResume: boolean;\n  /** How the auth probe is interpreted. Cursor's `status` exits 0 while logged out. */\n  authProbe: 'exit-code' | 'text' | 'none';\n  bareModelAliases: boolean;\n  promptChannel: 'argv' | 'stdin' | 'both';\n  nativeTimeout: boolean;\n  contextFileName: string;\n  contextFileMaxBytes: number | null;\n  toolNameCase: 'CamelCase' | 'lowercase' | 'none';\n  readOnlyMode: 'native' | 'sandbox' | 'tool-allowlist' | 'none';\n}\n\nexport type CodexSandbox = 'read-only' | 'workspace-write' | 'danger-full-access';\nexport type CodexReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';\n\nexport interface ClaudeSettings {\n  ignoreUserConfig?: boolean;\n  /** Companion of `ignoreUserConfig`. Escape: `false` keeps user MCP servers. */\n  strictMcpConfig?: boolean;\n}\n\nexport interface CodexSettings {\n  reasoningEffort?: CodexReasoningEffort;\n  sandbox?: CodexSandbox;\n  ignoreUserConfig?: boolean;\n  skipGitRepoCheck?: boolean;\n  configOverrides?: Record<string, string | number | boolean>;\n}\n\nexport type CursorSandbox = 'enabled' | 'disabled';\nexport type CursorPermissionsFile = 'global' | 'project' | 'none';\n\nexport interface CursorSettings {\n  sandbox?: CursorSandbox;\n  approveMcps?: boolean;\n  permissionsFile?: CursorPermissionsFile;\n  minVersion?: string;\n}\n\nexport type AntigravityEffort = 'low' | 'medium' | 'high';\n\nexport interface AntigravitySettings {\n  effort?: AntigravityEffort;\n  sandbox?: boolean;\n  /** Ceiling used when `timeout === 0`. `null` / `0` is \"no ceiling\" and is rejected. */\n  executeTimeout?: number | string | null;\n  maxPromptBytes?: number;\n  minVersion?: string;\n}\n\nexport interface OpenCodeSettings {\n  /** Provider-specific reasoning effort, e.g. high, max, minimal. */\n  variant?: string;\n  minVersion?: string;\n  maxPromptBytes?: number;\n}\n\n/** One layer of the agent block — default or a single phase. */\nexport interface AgentBlock {\n  provider?: AgentProviderId;\n  model?: string | null;\n  claude?: ClaudeSettings;\n  codex?: CodexSettings;\n  cursor?: CursorSettings;\n  antigravity?: AntigravitySettings;\n  opencode?: OpenCodeSettings;\n}\n\nexport interface AgentConfig {\n  provider: AgentProviderId;\n  model: string | null;\n  claude: ClaudeSettings;\n  codex: CodexSettings;\n  cursor: CursorSettings;\n  antigravity: AntigravitySettings;\n  opencode: OpenCodeSettings;\n  phases: Partial<Record<AgentPhase, AgentBlock>>;\n}\n\n/** Which rung of the ladder produced a resolved value. */\nexport type AgentOrigin = 'default' | 'global' | 'project' | 'env' | 'cli';\n\nexport interface ResolvedAgentSettings {\n  provider: AgentProviderId;\n  model: string | null;\n  claude: ClaudeSettings;\n  codex: CodexSettings;\n  cursor: CursorSettings;\n  antigravity: AntigravitySettings;\n  opencode: OpenCodeSettings;\n  origin: {\n    provider: AgentOrigin;\n    model: AgentOrigin;\n  };\n}\n\nexport interface AgentRunner {\n  readonly id: AgentProviderId;\n  readonly capabilities: AgentCapabilities;\n  versionCommand(): { command: string; args: string[] };\n  authCommand?(): { command: string; args: string[] };\n  run(invocation: AgentInvocation, settings: ResolvedAgentSettings): Promise<AgentRunResult>;\n}\n\nexport const CLAUDE_CAPABILITIES: AgentCapabilities = {\n  extraDirectories: 'flag',\n  addDirs: true,\n  toolAllowlist: true,\n  maxTurns: true,\n  osSandbox: false,\n  modelSelection: true,\n  modelDiscovery: false,\n  usage: 'tokens-and-cost',\n  reportsUsage: true,\n  reportsCost: true,\n  sessionResume: false,\n  authProbe: 'none',\n  bareModelAliases: true,\n  promptChannel: 'both',\n  nativeTimeout: false,\n  contextFileName: 'CLAUDE.md',\n  contextFileMaxBytes: null,\n  toolNameCase: 'CamelCase',\n  readOnlyMode: 'native',\n};\n\nexport const CODEX_CAPABILITIES: AgentCapabilities = {\n  extraDirectories: 'flag',\n  addDirs: true,\n  toolAllowlist: false,\n  maxTurns: false,\n  osSandbox: true,\n  modelSelection: true,\n  modelDiscovery: false,\n  usage: 'tokens-only',\n  reportsUsage: true,\n  reportsCost: false,\n  sessionResume: true,\n  authProbe: 'exit-code',\n  bareModelAliases: false,\n  promptChannel: 'both',\n  nativeTimeout: false,\n  contextFileName: 'AGENTS.md',\n  contextFileMaxBytes: 32 * 1024,\n  toolNameCase: 'none',\n  readOnlyMode: 'sandbox',\n};\n\nexport const CURSOR_CAPABILITIES: AgentCapabilities = {\n  extraDirectories: 'permission-file',\n  addDirs: false,\n  toolAllowlist: false,\n  maxTurns: false,\n  osSandbox: true,\n  modelSelection: true,\n  modelDiscovery: true,\n  usage: 'none',\n  reportsUsage: false,\n  reportsCost: false,\n  sessionResume: true,\n  authProbe: 'text',\n  bareModelAliases: false,\n  promptChannel: 'argv',\n  nativeTimeout: false,\n  contextFileName: 'AGENTS.md',\n  contextFileMaxBytes: null,\n  toolNameCase: 'lowercase',\n  readOnlyMode: 'native',\n};\n\nexport const ANTIGRAVITY_CAPABILITIES: AgentCapabilities = {\n  extraDirectories: 'flag',\n  addDirs: true,\n  toolAllowlist: false,\n  maxTurns: false,\n  osSandbox: true,\n  modelSelection: true,\n  modelDiscovery: true,\n  usage: 'tokens-only',\n  reportsUsage: true,\n  reportsCost: false,\n  sessionResume: true,\n  authProbe: 'none',\n  bareModelAliases: false,\n  promptChannel: 'argv',\n  nativeTimeout: true,\n  contextFileName: 'AGENTS.md',\n  contextFileMaxBytes: null,\n  toolNameCase: 'CamelCase',\n  readOnlyMode: 'native',\n};\n\nexport const OPENCODE_CAPABILITIES: AgentCapabilities = {\n  extraDirectories: 'flag',\n  addDirs: true,\n  toolAllowlist: false,\n  maxTurns: false,\n  osSandbox: false,\n  modelSelection: true,\n  modelDiscovery: true,\n  usage: 'tokens-only',\n  reportsUsage: true,\n  reportsCost: false,\n  sessionResume: true,\n  authProbe: 'text',\n  bareModelAliases: false,\n  promptChannel: 'argv',\n  nativeTimeout: false,\n  contextFileName: 'AGENTS.md',\n  contextFileMaxBytes: null,\n  toolNameCase: 'lowercase',\n  readOnlyMode: 'native',\n};\n\nexport const AGENT_SCHEMA_VERSION = 1;\n\n/**\n * CLI overrides captured by `setAgentCliOverrides`.\n *\n * `forceProvider` / `forceModel` are the emergency buttons (`--agent` /\n * `--agent-model`): they overwrite every phase after the ladder has run.\n */\nexport interface AgentCliOverrides {\n  provider?: AgentProviderId;\n  model?: string | null;\n  forceProvider?: AgentProviderId;\n  forceModel?: string;\n  claude?: ClaudeSettings;\n  codex?: CodexSettings;\n  cursor?: CursorSettings;\n  antigravity?: AntigravitySettings;\n  opencode?: OpenCodeSettings;\n  phases?: Partial<Record<AgentPhase, AgentBlock>>;\n}\n","import { z } from 'zod';\nimport { agentConfigInputSchema } from '../agents/schemas.js';\nimport type { ExecutionPlan } from '../execution/types.js';\nimport type {\n  ExhaustedAction,\n  FailoverMode,\n  PolicyConfig as ResiliencePolicyConfig,\n  ResilienceProfile,\n  RetryConfigKey,\n  RetryPolicy,\n} from '../resilience/policy.js';\nimport { pullRequestRefSchema, routingConfigInputSchema, webConfigSchema } from '../schemas.js';\n\n/**\n * Zod schemas for the files written under the global storage tree\n * (`~/.issue-flow`): the per-project `metadata.json` and the global\n * `config.json`.\n *\n * They live here rather than in `src/schemas.ts` so that file stays focused on\n * the pipeline domain (task plans, Issue metadata, session snapshots) and the\n * storage layer keeps owning its own formats.\n */\n\n/** Version stamped on files written by this release of the storage layer. */\nexport const STORAGE_SCHEMA_VERSION = 1;\n\n/**\n * Where a `plan` run's `US-NNN` numbering came from (issue #36):\n *\n * - `history`: recovered from the highest number already used anywhere in the\n *   project's `tasks.json` files, automatically or via `--continue`.\n * - `start-us`: forced by the user via `--start-us <n>`, ignoring history.\n * - `none`: no history found (the project's first `plan` run) — starts at\n *   `US-001`.\n */\nexport const userStoryNumberingSourceSchema = z.enum(['history', 'start-us', 'none']);\n\n/**\n * A single numbering decision, persisted for audit under\n * `metadata.json`'s `userStoryNumbering` (see below) — never used to resolve\n * the *next* decision, which always re-scans `tasks.json` from scratch.\n */\nexport const userStoryNumberingDecisionSchema = z.object({\n  /** The `US-NNN` number the `plan` prompt was told to continue from. */\n  nextNumber: z.number().int().positive(),\n  source: userStoryNumberingSourceSchema,\n  /** Issue the decision was made for. */\n  issueNumber: z.string().min(1),\n  decidedAt: z.string().min(1),\n  /** Human-readable origin, e.g. the previous story id and issue it came from. */\n  detail: z.string().optional(),\n});\n\n/**\n * `~/.issue-flow/projects/<project-id>/metadata.json`.\n *\n * Deliberately **not** `.strict()`: a newer release may add fields (dashboard\n * history, counters) and an older one must still be able to read the file\n * instead of rejecting it. Unknown keys are dropped on parse, never fatal.\n *\n * `root` is the last known local checkout — informative only. Identity lives in\n * `projectId` (see `getProjectId()` in `paths.ts`), so moving the folder of a\n * project that has a remote updates `root` without changing the id.\n */\nexport const projectMetadataSchema = z.object({\n  schemaVersion: z.number().int().positive(),\n  projectId: z.string().min(1),\n  root: z.string().min(1),\n  /** Normalized remote (`host/org/repo`), or null when the project has none. */\n  remoteUrl: z.string().nullable(),\n  createdAt: z.string().min(1),\n  updatedAt: z.string().min(1),\n  /** Null until the project is used by a pipeline run. */\n  lastAttemptAt: z.string().nullable(),\n  /**\n   * Most recent User Story numbering decision made by `plan` (issue #36).\n   * Absent on a project whose `plan` never ran through the numbering\n   * resolver, or on a `metadata.json` written before the feature existed.\n   */\n  userStoryNumbering: userStoryNumberingDecisionSchema.optional(),\n});\n\n/**\n * Global counterpart of the `web` key of `.issue-flow.json`, restricted to the\n * settings that make sense machine-wide: `enabled` and `includeLogs` stay a\n * per-project decision.\n *\n * The validation of each field is reused from `webConfigSchema` through\n * `.unwrap()`, which strips the `.default()` and keeps the constraints. Picking\n * and calling `.partial()` would not be enough: in zod 4 an optional field\n * still materializes its default when the key is absent\n * (`z.object({ port: z.number().default(3737) }).partial().parse({})` yields\n * `{ port: 3737 }`), and a materialized default in this layer would override\n * the project layer during the merge.\n */\nconst webShape = webConfigSchema.shape;\nexport const globalWebConfigSchema = z\n  .object({\n    port: webShape.port.unwrap(),\n    host: webShape.host.unwrap(),\n    refreshSeconds: webShape.refreshSeconds.unwrap(),\n    logLimit: webShape.logLimit.unwrap(),\n  })\n  .partial();\n\n/** Global retry preferences, mirroring `DEFAULTS` in `config.ts`. */\nexport const globalRetryConfigSchema = z\n  .object({\n    retryLimit: z.number().int().nonnegative(),\n    retryForever: z.boolean(),\n    backoffBaseSeconds: z.number().nonnegative(),\n    backoffMaxSeconds: z.number().nonnegative(),\n  })\n  .partial();\n\n/* ── the `resilience` key ───────────────────────────────────────────────── */\n\n/**\n * The file format of the `resilience` key, shared by `.issue-flow.json` and\n * `~/.issue-flow/config.json` — the same object is accepted in both, because\n * they are two rungs of one ladder rather than two formats.\n *\n * **Every field is optional and none carries a `.default()`**, for the reason\n * stated on `globalConfigSchema` below and in `AGENTS.md`: both files are\n * intermediate precedence layers, and a default materialized in one of them is\n * indistinguishable from a value the user wrote.\n *\n * The enums are pinned to the types of `resilience/policy.ts` with `satisfies`,\n * so a value the resolver understands and the file rejects (or the reverse) is\n * a compile error rather than a silent drop at parse time.\n */\nconst resilienceProfileSchema = z.enum([\n  'default',\n  'continuous',\n]) satisfies z.ZodType<ResilienceProfile>;\nconst jitterSchema = z.enum(['none', 'full']) satisfies z.ZodType<RetryPolicy['jitter']>;\nconst failoverModeSchema = z.enum([\n  'never',\n  'after_attempts',\n  'immediate',\n]) satisfies z.ZodType<FailoverMode>;\nconst exhaustedActionSchema = z.enum(['fail', 'block']) satisfies z.ZodType<ExhaustedAction>;\n\n/** One `resilience.retry.<kind>` entry — a partial `RetryPolicy`. */\nexport const retryPolicyOverrideSchema = z\n  .object({\n    maxAttempts: z.number().int().nonnegative(),\n    initialDelayMs: z.number().nonnegative(),\n    maxDelayMs: z.number().nonnegative(),\n    backoffFactor: z.number().min(1),\n    jitter: jitterSchema,\n    retryForever: z.boolean(),\n    failover: failoverModeSchema,\n    failoverAfterAttempts: z.number().int().positive(),\n    onExhausted: exhaustedActionSchema,\n  })\n  .partial();\n\n/**\n * `resilience.retry`, one optional entry per `FailureKind`.\n *\n * Built from a `Record<RetryConfigKey, …>` on purpose: adding a `FailureKind`\n * without giving it a configuration key stops compiling here.\n */\nconst retryOverridesByKind: Record<RetryConfigKey, typeof retryPolicyOverrideSchema> = {\n  network: retryPolicyOverrideSchema,\n  timeout: retryPolicyOverrideSchema,\n  stalled: retryPolicyOverrideSchema,\n  rateLimit: retryPolicyOverrideSchema,\n  providerDown: retryPolicyOverrideSchema,\n  providerCrash: retryPolicyOverrideSchema,\n  authentication: retryPolicyOverrideSchema,\n  configuration: retryPolicyOverrideSchema,\n  repositoryState: retryPolicyOverrideSchema,\n  taskExecution: retryPolicyOverrideSchema,\n  internal: retryPolicyOverrideSchema,\n  unknown: retryPolicyOverrideSchema,\n};\n\nexport const resilienceRetryConfigSchema = z.object(retryOverridesByKind).partial();\n\n/** `resilience.providers` — agent health and failover (US-024, US-025). */\nexport const resilienceProvidersConfigSchema = z\n  .object({\n    failover: z.boolean(),\n    chain: z.array(z.string().min(1)),\n    cooldownMs: z.number().nonnegative(),\n    maxCooldownMs: z.number().nonnegative(),\n    failureWindowMs: z.number().positive(),\n    failuresToTrip: z.number().int().positive(),\n  })\n  .partial();\n\nexport const providerHealthStatusSchema = z.enum([\n  'healthy',\n  'degraded',\n  'unavailable',\n  'rate_limited',\n  'auth_failed',\n  'half_open',\n]);\n\nexport const providerHealthRecordSchema = z.object({\n  status: providerHealthStatusSchema.default('healthy'),\n  failures: z\n    .array(\n      z.object({\n        at: z.string(),\n        kind: z.enum([\n          'network',\n          'timeout',\n          'stalled',\n          'rate_limit',\n          'provider_down',\n          'provider_crash',\n          'authentication',\n          'configuration',\n          'repository_state',\n          'task_execution',\n          'internal',\n          'unknown',\n        ]),\n      }),\n    )\n    .default([]),\n  consecutiveFailures: z.number().int().nonnegative().default(0),\n  cooldownLevel: z.number().int().nonnegative().default(0),\n  cooldownUntil: z.string().nullable().default(null),\n  lastFailureKind: z\n    .enum([\n      'network',\n      'timeout',\n      'stalled',\n      'rate_limit',\n      'provider_down',\n      'provider_crash',\n      'authentication',\n      'configuration',\n      'repository_state',\n      'task_execution',\n      'internal',\n      'unknown',\n    ])\n    .nullable()\n    .default(null),\n  lastFailureAt: z.string().nullable().default(null),\n  lastSuccessAt: z.string().nullable().default(null),\n  probeInFlight: z.boolean().default(false),\n  probeStartedAt: z.string().nullable().default(null),\n});\n\nexport const providersHealthSchema = z.object({\n  schemaVersion: z.literal(1).default(1),\n  providers: z.record(z.string(), providerHealthRecordSchema).default({}),\n});\n\n/** `resilience.queue` — what a failing issue does to the rest of them (US-027). */\nexport const resilienceQueueConfigSchema = z\n  .object({\n    onIssueFailure: z.enum(['stop', 'skip', 'block']),\n    maxIssueAttempts: z.number().int().positive(),\n  })\n  .partial();\n\n/** `resilience.watchdog` — inactivity detection over the event stream (US-026). */\nexport const resilienceWatchdogConfigSchema = z\n  .object({\n    inactivityTimeoutMs: z.number().int().nonnegative(),\n  })\n  .partial();\n\n/** `resilience.journal` — the append-only `events.jsonl` (US-015). */\nexport const resilienceJournalConfigSchema = z\n  .object({\n    enabled: z.boolean(),\n    maxFileBytes: z.number().int().positive(),\n  })\n  .partial();\n\n/** `resilience.decompose` — the \"this issue is too large\" report (US-030). */\nexport const resilienceDecomposeConfigSchema = z\n  .object({\n    auto: z.boolean(),\n  })\n  .partial();\n\nexport const resilienceConfigSchema = z\n  .object({\n    profile: resilienceProfileSchema,\n    /** Whether a credential failure may migrate to another provider. */\n    failoverOnAuth: z.boolean(),\n    retry: resilienceRetryConfigSchema,\n    providers: resilienceProvidersConfigSchema,\n    queue: resilienceQueueConfigSchema,\n    watchdog: resilienceWatchdogConfigSchema,\n    journal: resilienceJournalConfigSchema,\n    decompose: resilienceDecomposeConfigSchema,\n  })\n  .partial();\n\n/**\n * Intermediate `telemetry` key. Every field optional, no `.default()` — this\n * file is a middle rung of the config ladder.\n */\nexport const telemetryPricingOverrideSchema = z\n  .object({\n    inputPerMillion: z.number(),\n    outputPerMillion: z.number(),\n    cacheReadPerMillion: z.number(),\n    cacheWritePerMillion: z.number(),\n  })\n  .partial();\n\nexport const telemetryConfigInputSchema = z\n  .object({\n    enabled: z.boolean(),\n    maxExecutions: z.number().int().positive(),\n    pricing: z\n      .object({\n        estimate: z.boolean(),\n        overrides: z.record(z.string(), telemetryPricingOverrideSchema),\n      })\n      .partial(),\n  })\n  .partial();\n\n/** Global commit preferences. `signoff` is consumed by `commitMessage()`. */\nexport const globalCommitConfigSchema = z\n  .object({\n    signoff: z.boolean(),\n    conventional: z.boolean(),\n  })\n  .partial();\n\n/**\n * SQLite adoption controls. They deliberately live in a separate `storage`\n * object so choosing the compatibility driver cannot be confused with the\n * location of the global storage tree (`storageDir`).\n */\nexport const storageConfigInputSchema = z\n  .object({\n    /** Keep legacy JSON as the active driver, for recovery or a staged rollout. */\n    driver: z.enum(['sqlite', 'json']),\n    /** Number of pre-migration database snapshots to retain. */\n    backupRetention: z.number().int().nonnegative(),\n    /** Explicit row-retention policy. Omitted values mean retain history. */\n    retention: z\n      .object({\n        executions: z.number().int().nonnegative(),\n        events: z.number().int().nonnegative(),\n        snapshots: z.number().int().nonnegative(),\n        backups: z.number().int().nonnegative(),\n      })\n      .partial(),\n  })\n  .partial();\n\n/**\n * `~/.issue-flow/config.json`.\n *\n * **Every key is optional and no key carries a `.default()`.** This is a design\n * constraint, not an omission: the global file is an intermediate precedence\n * layer (CLI > env > `.issue-flow.json` > `config.json` > defaults), so a\n * default materialized here would be indistinguishable from a value the user\n * actually wrote and would silently override the project layer during the\n * merge. Same reason `readWebConfigFile()` parses with\n * `webConfigSchema.partial()`. Defaults belong to the final layer only.\n */\nexport const globalConfigSchema = z\n  .object({\n    schemaVersion: z.number().int().positive(),\n    /** Override for the directory holding `projects/`. */\n    storageDir: z.string().min(1),\n    storage: storageConfigInputSchema,\n    web: globalWebConfigSchema,\n    retry: globalRetryConfigSchema,\n    commit: globalCommitConfigSchema,\n    resilience: resilienceConfigSchema,\n    agent: agentConfigInputSchema,\n    telemetry: telemetryConfigInputSchema,\n    routing: routingConfigInputSchema,\n  })\n  .partial();\n\n/**\n * `~/.issue-flow/web.lock`.\n *\n * Marks the single web monitoring server active on this machine: `pid` and\n * `port` let a new invocation tell a live instance from a stale one before\n * attempting to bind its own (see `web/lock.ts`). Not `.strict()` for the same\n * reason as the schemas above — a newer release may add fields.\n */\nexport const webLockSchema = z.object({\n  pid: z.number().int().positive(),\n  port: z.number().int().positive(),\n  host: z.string().min(1),\n  startedAt: z.string().min(1),\n  /** Added in a backward-compatible way: locks from older releases remain valid. */\n  instanceId: z.string().min(1).optional(),\n});\n\n/**\n * `~/.issue-flow/projects/<project-id>/run.lock`.\n *\n * Ownership of a run, so a second invocation in the same project refuses\n * instead of fighting the first one over `tasks.json` and the branch. Same\n * shape of guard as `web.lock` — a pid, a host and a timestamp — plus the\n * heartbeat that tells a dead owner from a slow one.\n *\n * No field defaults: a lock is written whole by its owner, and a half-read one\n * degrades to \"no lock\" at the reader, exactly like `readWebLock`.\n */\nexport const runLockSchema = z.object({\n  pid: z.number().int().positive(),\n  /** `os.hostname()`. A pid only means something on the host that wrote it. */\n  host: z.string().min(1),\n  /** The issue (or queue) identifier the owner is running. */\n  target: z.string().min(1),\n  startedAt: z.string().min(1),\n  lastHeartbeatAt: z.string().min(1),\n  /** Absent on a foreground run written before this field existed. */\n  detached: z.boolean().optional(),\n});\n\n/**\n * `~/.issue-flow/projects/<project-id>/queues/<queue-id>/execution-plan.json`.\n *\n * The coordination state of a multi-issue run: which Issues, in which order, on\n * which shared branch, and how far the queue got. Each Issue keeps its own\n * `tasks.json` — nothing of the task plan is duplicated here.\n *\n * Written only when a queue really has more than one Issue: a single-issue run\n * creates no queue directory at all, which is what keeps the storage layout of\n * every existing user unchanged.\n *\n * Not `.strict()`, like every other file schema here, and `satisfies` keeps it\n * in lockstep with the `ExecutionPlan` interface in `src/execution/types.ts`.\n */\nexport const executionPlanIssueSchema = z.object({\n  id: z.string().min(1),\n  number: z.number().int().positive().nullable(),\n  title: z.string(),\n  url: z.string().nullable(),\n  source: z.string().min(1),\n  position: z.number().int().positive(),\n  // `blocked` and `skipped` are additive: no plan written before them can\n  // carry one, and a reader that does not know them was never given one.\n  status: z.enum(['pending', 'in_progress', 'completed', 'failed', 'blocked', 'skipped']),\n  origin: z.enum(['requested', 'discovered']),\n  role: z.enum(['executable', 'container']).default('executable'),\n  externalDependencies: z.array(z.string()).default([]),\n  dependsOn: z.array(z.string()).default([]),\n  parent: z.string().nullable().default(null),\n  priority: z.enum(['high', 'medium', 'low']).nullable().default(null),\n  heuristic: z.boolean().default(false),\n  failedPhase: z.string().nullable().default(null),\n  lastError: z\n    .object({ category: z.string(), message: z.string(), at: z.string() })\n    .nullable()\n    .default(null),\n  startedAt: z.string().nullable().default(null),\n  completedAt: z.string().nullable().default(null),\n  // Both default, so an execution-plan.json written by an earlier release\n  // parses unchanged and reads as \"never attempted, not blocked\".\n  attempts: z.number().int().min(0).default(0),\n  blockedReason: z.string().nullable().default(null),\n});\n\nexport const executionPlanSchema = z.object({\n  closeIssue: z.boolean().optional(),\n  closedIssueIds: z.array(z.string()).optional(),\n  prReviewCompleted: z.boolean().optional(),\n  schemaVersion: z.literal(1),\n  id: z.string().min(1),\n  project: z.string().min(1),\n  requested: z.array(z.string().min(1)),\n  branchName: z.string().nullable().default(null),\n  noBranch: z.boolean().default(false),\n  prReview: z.boolean().default(false),\n  status: z.enum(['pending', 'in_progress', 'completed', 'failed']),\n  createdAt: z.string().min(1),\n  updatedAt: z.string().min(1),\n  truncated: z.boolean().default(false),\n  issues: z.array(executionPlanIssueSchema),\n  excluded: z\n    .array(\n      z.object({\n        id: z.string().min(1),\n        number: z.number().int().positive().nullable(),\n        title: z.string(),\n        url: z.string().nullable(),\n        reason: z.string(),\n      }),\n    )\n    .default([]),\n  pullRequest: pullRequestRefSchema.optional(),\n}) satisfies z.ZodType<ExecutionPlan>;\n\nexport type UserStoryNumberingSource = z.infer<typeof userStoryNumberingSourceSchema>;\nexport type UserStoryNumberingDecision = z.infer<typeof userStoryNumberingDecisionSchema>;\nexport type ProjectMetadata = z.infer<typeof projectMetadataSchema>;\nexport type ValidatedExecutionPlan = z.infer<typeof executionPlanSchema>;\nexport type GlobalWebConfig = z.infer<typeof globalWebConfigSchema>;\nexport type GlobalRetryConfig = z.infer<typeof globalRetryConfigSchema>;\nexport type GlobalCommitConfig = z.infer<typeof globalCommitConfigSchema>;\nexport type StorageConfigInput = z.infer<typeof storageConfigInputSchema>;\nexport type ResilienceRetryConfig = z.infer<typeof resilienceRetryConfigSchema>;\nexport type ResilienceProvidersConfig = z.infer<typeof resilienceProvidersConfigSchema>;\nexport type ProviderHealthStatus = z.infer<typeof providerHealthStatusSchema>;\nexport type ProviderHealthRecord = z.infer<typeof providerHealthRecordSchema>;\nexport type ProvidersHealth = z.infer<typeof providersHealthSchema>;\nexport type ResilienceQueueConfig = z.infer<typeof resilienceQueueConfigSchema>;\nexport type ResilienceWatchdogConfig = z.infer<typeof resilienceWatchdogConfigSchema>;\nexport type ResilienceJournalConfig = z.infer<typeof resilienceJournalConfigSchema>;\nexport type ResilienceDecomposeConfig = z.infer<typeof resilienceDecomposeConfigSchema>;\nexport type ResilienceConfig = z.infer<typeof resilienceConfigSchema>;\nexport type GlobalConfig = z.infer<typeof globalConfigSchema>;\nexport type TelemetryConfigInput = z.infer<typeof telemetryConfigInputSchema>;\n\n/**\n * The file format is a *superset* of what `resolvePolicy()` reads: it also\n * carries `providers`, `queue`, `watchdog`, `journal` and `decompose`, which\n * belong to later layers. This alias is the compile-time proof of the \"superset\"\n * half — a drift between the two shapes fails to build here rather than at the\n * first call site that passes one to the other.\n */\ntype Assert<T extends true> = T;\nexport type ResilienceConfigIsPolicyConfig = Assert<\n  ResilienceConfig extends ResiliencePolicyConfig ? true : false\n>;\nexport type WebLock = z.infer<typeof webLockSchema>;\nexport type RunLock = z.infer<typeof runLockSchema>;\n","import { z } from 'zod';\nimport { AGENT_PHASES, type AgentPhase } from './types.js';\n\n/**\n * File-format schemas for the `agent` key.\n *\n * These are intermediate layers (global `config.json` and `.issue-flow.json`).\n * No field carries a `.default()`: a default materialized here would look\n * like a value the user wrote and would silently override the rung above.\n */\n\nexport const agentProviderIdSchema = z.enum([\n  'claude',\n  'codex',\n  'cursor',\n  'antigravity',\n  'opencode',\n]);\n\nexport const codexSandboxSchema = z.enum(['read-only', 'workspace-write', 'danger-full-access']);\n\nexport const codexReasoningEffortSchema = z.enum(['minimal', 'low', 'medium', 'high', 'xhigh']);\n\nexport const claudeSettingsSchema = z\n  .object({\n    ignoreUserConfig: z.boolean(),\n    strictMcpConfig: z.boolean(),\n  })\n  .partial();\n\nexport const codexSettingsSchema = z\n  .object({\n    reasoningEffort: codexReasoningEffortSchema,\n    sandbox: codexSandboxSchema,\n    ignoreUserConfig: z.boolean(),\n    skipGitRepoCheck: z.boolean(),\n    configOverrides: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),\n  })\n  .partial();\n\nexport const cursorSandboxSchema = z.enum(['enabled', 'disabled']);\n\nexport const cursorPermissionsFileSchema = z.enum(['global', 'project', 'none']);\n\nexport const cursorSettingsSchema = z\n  .object({\n    sandbox: cursorSandboxSchema,\n    approveMcps: z.boolean(),\n    permissionsFile: cursorPermissionsFileSchema,\n    minVersion: z.string().min(1),\n    force: z.boolean().refine((value) => value !== false, {\n      message:\n        'agent.cursor.force cannot be false: without --force, Cursor finishes with exit 0 and writes nothing.',\n    }),\n  })\n  .partial();\n\nexport const antigravityEffortSchema = z.enum(['low', 'medium', 'high']);\n\nexport const antigravitySettingsSchema = z\n  .object({\n    effort: antigravityEffortSchema,\n    sandbox: z.boolean(),\n    executeTimeout: z.union([z.number().int(), z.string().min(1), z.null()]),\n    maxPromptBytes: z.number().int().positive(),\n    minVersion: z.string().min(1),\n    skipPermissions: z.boolean().refine((value) => value !== false, {\n      message:\n        'agent.antigravity.skipPermissions cannot be false: without --dangerously-skip-permissions, Antigravity finishes SUCCESS and writes nothing.',\n    }),\n  })\n  .partial();\n\nexport const opencodeSettingsSchema = z\n  .object({\n    variant: z.string().min(1),\n    minVersion: z.string().min(1),\n    maxPromptBytes: z.number().int().positive(),\n  })\n  .partial();\n\nexport const agentBlockSchema = z\n  .object({\n    provider: agentProviderIdSchema,\n    model: z.string().min(1).nullable(),\n    claude: claudeSettingsSchema,\n    codex: codexSettingsSchema,\n    cursor: cursorSettingsSchema,\n    antigravity: antigravitySettingsSchema,\n    opencode: opencodeSettingsSchema,\n  })\n  .partial();\n\n/**\n * The `phases` map as written in a file. Unknown keys are dropped by the\n * loader (with a warning); this schema only accepts the eight real phases.\n */\nexport const agentPhasesSchema = z\n  .object({\n    analyze: agentBlockSchema,\n    generate: agentBlockSchema,\n    prd: agentBlockSchema,\n    plan: agentBlockSchema,\n    execute: agentBlockSchema,\n    review: agentBlockSchema,\n    pr: agentBlockSchema,\n    'pr-review': agentBlockSchema,\n  })\n  .partial();\n\n/** Input shape of the `agent` key — every field optional, no defaults. */\nexport const agentConfigInputSchema = z\n  .object({\n    provider: agentProviderIdSchema,\n    model: z.string().min(1).nullable(),\n    claude: claudeSettingsSchema,\n    codex: codexSettingsSchema,\n    cursor: cursorSettingsSchema,\n    antigravity: antigravitySettingsSchema,\n    opencode: opencodeSettingsSchema,\n    phases: agentPhasesSchema,\n  })\n  .partial();\n\nexport type AgentConfigInput = z.infer<typeof agentConfigInputSchema>;\n\n/** Loose parse of a `phases` object so unknown keys can be reported. */\nexport function parsePhasesInput(\n  value: unknown,\n  warn: (message: string) => void,\n): Partial<Record<AgentPhase, z.infer<typeof agentBlockSchema>>> {\n  if (value === undefined || value === null) return {};\n  if (typeof value !== 'object' || Array.isArray(value)) {\n    warn('Ignoring \"agent.phases\": expected an object.');\n    return {};\n  }\n\n  const result: Partial<Record<AgentPhase, z.infer<typeof agentBlockSchema>>> = {};\n  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {\n    if (!(AGENT_PHASES as readonly string[]).includes(key)) {\n      warn(`Ignoring unknown agent phase \"${key}\".`);\n      continue;\n    }\n    const parsed = agentBlockSchema.safeParse(raw);\n    if (!parsed.success) {\n      warn(`Ignoring agent.phases.${key}: ${parsed.error.issues[0]?.message ?? 'invalid value'}.`);\n      continue;\n    }\n    result[key as AgentPhase] = parsed.data;\n  }\n  return result;\n}\n","import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport { hostname } from 'node:os';\nimport { dirname } from 'node:path';\nimport { type RunLock, runLockSchema } from './schemas.js';\n\n/**\n * Run ownership: who is executing in this project right now.\n *\n * Generalised from `web/lock.ts`, which has guarded the monitoring server the\n * same way since it existed — atomic `wx` create, `process.kill(pid, 0)` for\n * liveness, and a read that degrades to \"no lock\" on anything malformed. What\n * this module adds is the piece a *long* run needs and a server does not: a\n * **heartbeat**. A web server proves it is alive by answering a health probe;\n * a pipeline has no port to probe, so it says so in the file instead.\n *\n * The two signals answer different questions and both are needed:\n *\n * - the **pid** catches the machine that rebooted or the process that was\n *   `kill -9`ed — the lock outlives its owner, and nothing else would notice;\n * - the **heartbeat** catches the owner that is technically alive but no longer\n *   running (a pid reused by an unrelated process is the same case), and it is\n *   the only signal that survives being read from another host.\n *\n * Nothing here is destructive by inference: a lock is only taken over when it\n * is stale by both measures the policy states, and taking one over is reported\n * to the caller (`reclaimedFrom`) so the run can be recorded as interrupted\n * rather than silently restarted.\n */\n\n/** The lock is rewritten this often while a run holds it. */\nexport const RUN_LOCK_HEARTBEAT_MS = 10_000;\n\n/**\n * How many missed heartbeats make a lock stale.\n *\n * Three, not one: a machine under load, a suspended laptop or a slow\n * filesystem can miss a beat without the run being dead, and stealing a lock\n * from a live owner is the failure this module exists to prevent.\n */\nexport const RUN_LOCK_STALE_INTERVALS = 3;\n\n/** How many times a claim is retried after clearing a stale lock. */\nconst CLAIM_RETRIES = 3;\n\nexport interface RunLockHandle {\n  readonly lock: RunLock;\n  /**\n   * The dead owner this lock was taken from, when it was taken from one.\n   *\n   * `null` on a clean acquisition. Non-null is the fact a caller records as an\n   * *interrupted* run: something was executing here and never finished.\n   */\n  readonly reclaimedFrom: RunLock | null;\n  /** Stop the heartbeat and remove the lock. Never rejects. */\n  release(): Promise<void>;\n}\n\nexport type AcquireRunLockResult =\n  | { ok: true; handle: RunLockHandle }\n  | { ok: false; owner: RunLock };\n\nexport interface AcquireRunLockOptions {\n  /** Issue (or queue) identifier this run works on. */\n  target: string;\n  /** Rewrite interval. Also the unit `staleIntervals` counts. */\n  heartbeatMs?: number;\n  staleIntervals?: number;\n  /** Injectable identity, so a test can pretend to be another process. */\n  pid?: number;\n  host?: string;\n  /** Injectable clock, so staleness is testable without waiting. */\n  clock?: () => number;\n  /** Called once, when a stale lock is taken over. Never throws through. */\n  onTakeover?: (previous: RunLock) => void;\n  /**\n   * Start the rewriting timer. Default true; a test that drives the clock by\n   * hand turns it off and calls `touchRunLock` itself.\n   */\n  heartbeat?: boolean;\n  /** The owner is a process spawned by `--background`. */\n  detached?: boolean;\n}\n\n/**\n * `process.kill(pid, 0)` throws `ESRCH` when the pid is gone and `EPERM` when\n * it is alive but owned by another user — **only `ESRCH` means \"not alive\"**.\n * Reading `EPERM` as death is how a lock gets stolen from a healthy run\n * started by another user.\n */\nexport function isProcessAlive(pid: number): boolean {\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch (err) {\n    return (err as NodeJS.ErrnoException).code === 'EPERM';\n  }\n}\n\n/**\n * Read a lock, degrading anything unreadable to \"no lock\".\n *\n * A partial write, a file from an incompatible release, a truncated JSON: all\n * of them mean the same thing operationally, and none of them justifies\n * failing a run. Same behaviour as `readWebLock` and `loadGlobalConfig`.\n */\nexport async function readRunLock(lockFile: string): Promise<RunLock | null> {\n  let raw: string;\n  try {\n    raw = await readFile(lockFile, 'utf-8');\n  } catch {\n    return null;\n  }\n  try {\n    const result = runLockSchema.safeParse(JSON.parse(raw));\n    return result.success ? result.data : null;\n  } catch {\n    return null;\n  }\n}\n\n/** Remove a lock file. Best effort; never rejects. */\nexport async function removeRunLock(lockFile: string): Promise<void> {\n  try {\n    await rm(lockFile, { force: true });\n  } catch {\n    /* best-effort cleanup */\n  }\n}\n\nexport interface StalenessOptions {\n  heartbeatMs?: number;\n  staleIntervals?: number;\n  clock?: () => number;\n  /** Treat this pid as our own, so a re-entrant claim is not \"stale\". */\n  pid?: number;\n  host?: string;\n}\n\n/**\n * Whether `lock` may be taken over.\n *\n * A lock written on another host cannot be judged by pid — `process.kill` there\n * says nothing about a process here — so on a foreign host only the heartbeat\n * decides. That is the case a shared filesystem creates, and reading it wrong\n * is how two machines end up on the same branch.\n */\nexport function isRunLockStale(lock: RunLock, options: StalenessOptions = {}): boolean {\n  const heartbeatMs = options.heartbeatMs ?? RUN_LOCK_HEARTBEAT_MS;\n  const staleIntervals = options.staleIntervals ?? RUN_LOCK_STALE_INTERVALS;\n  const now = (options.clock ?? Date.now)();\n  const host = options.host ?? hostname();\n\n  const beat = Date.parse(lock.lastHeartbeatAt);\n  const silent = Number.isNaN(beat) || now - beat > heartbeatMs * staleIntervals;\n\n  if (lock.host !== host) return silent;\n  return silent || !isProcessAlive(lock.pid);\n}\n\n/** Whether this very process already owns `lock`. */\nfunction isSelf(lock: RunLock, pid: number, host: string): boolean {\n  return lock.pid === pid && lock.host === host;\n}\n\n/**\n * One line naming the owner, for the message a refused invocation prints.\n *\n * The pid alone is useless to a person; the pid *plus the host plus when it\n * last said anything* is what lets them decide between waiting and killing it.\n */\nexport function describeRunLockOwner(lock: RunLock): string {\n  return `pid ${lock.pid} on ${lock.host} (issue ${lock.target}, started ${lock.startedAt}, last heartbeat ${lock.lastHeartbeatAt})`;\n}\n\n/** Rewrite the lock with a fresh heartbeat. Never rejects. */\nexport async function touchRunLock(lockFile: string, lock: RunLock, at: string): Promise<RunLock> {\n  const next: RunLock = { ...lock, lastHeartbeatAt: at };\n  try {\n    await writeFile(lockFile, `${JSON.stringify(next, null, 2)}\\n`, 'utf-8');\n  } catch {\n    // A heartbeat that cannot be written is not worth failing a run over: the\n    // worst case is that another invocation eventually judges us stale, which\n    // is the same outcome as this process having died.\n  }\n  return next;\n}\n\n/**\n * Atomic exclusive create. `wx` fails with `EEXIST` when someone else won the\n * race, which is what lets two concurrent invocations agree on one winner\n * without a lock for the lock.\n */\nasync function claim(lockFile: string, lock: RunLock): Promise<boolean> {\n  try {\n    await mkdir(dirname(lockFile), { recursive: true });\n    await writeFile(lockFile, `${JSON.stringify(lock, null, 2)}\\n`, {\n      encoding: 'utf-8',\n      flag: 'wx',\n    });\n    return true;\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === 'EEXIST') return false;\n    throw err;\n  }\n}\n\n/**\n * Take ownership of the run in this project, or report who already has it.\n *\n * Three outcomes, and only three:\n *\n * 1. **free** — the lock is claimed and a heartbeat starts;\n * 2. **held by a dead owner** — the stale lock is cleared, claimed, and the\n *    previous owner comes back on `reclaimedFrom` so the caller can record the\n *    interrupted run;\n * 3. **held by a live owner** — `{ ok: false, owner }`, and the caller refuses\n *    with a message naming it. Nothing is deleted, nothing is retried into\n *    submission.\n *\n * A lock this very process already holds is outcome 1 with a no-op release:\n * re-entering is not a conflict, and a nested acquisition must not remove the\n * file the outer one still owns.\n */\nexport async function acquireRunLock(\n  lockFile: string,\n  options: AcquireRunLockOptions,\n): Promise<AcquireRunLockResult> {\n  const pid = options.pid ?? process.pid;\n  const host = options.host ?? hostname();\n  const heartbeatMs = options.heartbeatMs ?? RUN_LOCK_HEARTBEAT_MS;\n  const clock = options.clock ?? Date.now;\n  const staleness: StalenessOptions = {\n    heartbeatMs,\n    ...(options.staleIntervals === undefined ? {} : { staleIntervals: options.staleIntervals }),\n    clock,\n    pid,\n    host,\n  };\n\n  let reclaimedFrom: RunLock | null = null;\n\n  for (let attempt = 0; attempt <= CLAIM_RETRIES; attempt++) {\n    const at = new Date(clock()).toISOString();\n    const mine: RunLock = {\n      pid,\n      host,\n      target: options.target,\n      startedAt: at,\n      lastHeartbeatAt: at,\n      ...(options.detached === true ? { detached: true } : {}),\n    };\n\n    if (await claim(lockFile, mine)) {\n      return { ok: true, handle: startHandle(lockFile, mine, reclaimedFrom, options) };\n    }\n\n    const existing = await readRunLock(lockFile);\n\n    if (existing === null) {\n      // Unreadable: a partial write, or a file from a shape we do not know.\n      // Treated as absent, exactly as `readRunLock` documents.\n      await removeRunLock(lockFile);\n      continue;\n    }\n\n    if (isSelf(existing, pid, host)) {\n      return { ok: true, handle: nestedHandle(existing) };\n    }\n\n    if (!isRunLockStale(existing, staleness)) {\n      return { ok: false, owner: existing };\n    }\n\n    reclaimedFrom = existing;\n    try {\n      options.onTakeover?.(existing);\n    } catch {\n      // A caller's bookkeeping must not decide whether the run starts.\n    }\n    await removeRunLock(lockFile);\n  }\n\n  // Every attempt lost the race and every lock read was stale or unreadable:\n  // something else is fighting for this file. Refusing is the safe answer.\n  const owner = await readRunLock(lockFile);\n  if (owner !== null) return { ok: false, owner };\n  return {\n    ok: false,\n    owner: {\n      pid: 0,\n      host,\n      target: options.target,\n      startedAt: new Date(clock()).toISOString(),\n      lastHeartbeatAt: new Date(clock()).toISOString(),\n    },\n  };\n}\n\nfunction startHandle(\n  lockFile: string,\n  lock: RunLock,\n  reclaimedFrom: RunLock | null,\n  options: AcquireRunLockOptions,\n): RunLockHandle {\n  const heartbeatMs = options.heartbeatMs ?? RUN_LOCK_HEARTBEAT_MS;\n  const clock = options.clock ?? Date.now;\n  let current = lock;\n  let timer: NodeJS.Timeout | null = null;\n\n  if (options.heartbeat !== false) {\n    timer = setInterval(() => {\n      void touchRunLock(lockFile, current, new Date(clock()).toISOString()).then((next) => {\n        current = next;\n      });\n    }, heartbeatMs);\n    // The heartbeat must never be the reason a process stays alive.\n    timer.unref();\n  }\n\n  return {\n    lock,\n    reclaimedFrom,\n    release: async () => {\n      if (timer !== null) {\n        clearInterval(timer);\n        timer = null;\n      }\n      await removeRunLock(lockFile);\n    },\n  };\n}\n\n/** A re-entrant acquisition: same owner, no timer of its own, no removal. */\nfunction nestedHandle(lock: RunLock): RunLockHandle {\n  return { lock, reclaimedFrom: null, release: async () => {} };\n}\n"],"mappings":"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","names":["z","z"]}

package/dist/chunk-6AOZCWN2.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+// src/core/document-result.ts
+function parseDocumentResult(output, tag) {
+  if (!/^[a-z][a-z0-9-]*$/.test(tag)) throw new Error(`Invalid document tag: ${tag}`);
+  const pattern = new RegExp(`<${tag}>\\s*([\\s\\S]*?)\\s*</${tag}>\\s*$`);
+  const matches = [...output.matchAll(new RegExp(`<${tag}>`, "g"))];
+  const match = output.match(pattern);
+  if (matches.length !== 1 || match?.[1] === void 0) {
+    throw new Error(`Expected exactly one final <${tag}> block.`);
+  }
+  const content = match[1].trim();
+  if (content.length < 10) throw new Error(`<${tag}> content is empty or too short.`);
+  return `${content}
+`;
+}
+
+export {
+  parseDocumentResult
+};
+//# sourceMappingURL=chunk-6AOZCWN2.js.map

package/dist/chunk-6AOZCWN2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/document-result.ts"],"sourcesContent":["/** Extract one non-empty, final tagged document from a headless response. */\nexport function parseDocumentResult(output: string, tag: string): string {\n  if (!/^[a-z][a-z0-9-]*$/.test(tag)) throw new Error(`Invalid document tag: ${tag}`);\n  const pattern = new RegExp(`<${tag}>\\\\s*([\\\\s\\\\S]*?)\\\\s*</${tag}>\\\\s*$`);\n  const matches = [...output.matchAll(new RegExp(`<${tag}>`, 'g'))];\n  const match = output.match(pattern);\n  if (matches.length !== 1 || match?.[1] === undefined) {\n    throw new Error(`Expected exactly one final <${tag}> block.`);\n  }\n  const content = match[1].trim();\n  if (content.length < 10) throw new Error(`<${tag}> content is empty or too short.`);\n  return `${content}\\n`;\n}\n"],"mappings":";;;AACO,SAAS,oBAAoB,QAAgB,KAAqB;AACvE,MAAI,CAAC,oBAAoB,KAAK,GAAG,EAAG,OAAM,IAAI,MAAM,yBAAyB,GAAG,EAAE;AAClF,QAAM,UAAU,IAAI,OAAO,IAAI,GAAG,0BAA0B,GAAG,QAAQ;AACvE,QAAM,UAAU,CAAC,GAAG,OAAO,SAAS,IAAI,OAAO,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC;AAChE,QAAM,QAAQ,OAAO,MAAM,OAAO;AAClC,MAAI,QAAQ,WAAW,KAAK,QAAQ,CAAC,MAAM,QAAW;AACpD,UAAM,IAAI,MAAM,+BAA+B,GAAG,UAAU;AAAA,EAC9D;AACA,QAAM,UAAU,MAAM,CAAC,EAAE,KAAK;AAC9B,MAAI,QAAQ,SAAS,GAAI,OAAM,IAAI,MAAM,IAAI,GAAG,kCAAkC;AAClF,SAAO,GAAG,OAAO;AAAA;AACnB;","names":[]}