iterate-plugin 3.7.0 → 3.9.0

package/src/session-record.ts

@@ -0,0 +1,333 @@
+/**
+ * src/session-record.ts — dsh session-linked run records (dsh ≥ 0.2.1-rc.1).
+ *
+ * Upstream capability (dsh `0.2.1-rc.1`, released 2026-10-17): the *Session
+ * state-record API*. An experimental plugin may append its own record onto a
+ * session's append-only log with `appendPluginRecord(session, type, data)` and
+ * read it back with `pluginRecordOf(event)` (`@deepseek-ai/dsh-session`). The
+ * record is marked `ignorable`, never enters the model-visible surface, and is
+ * carried along by fork / resume / format migration.
+ *
+ * Why the plugin adopts it:
+ *   The iterate run state has, until now, lived ONLY under `<projectRoot>/.iterate/`.
+ *   That is correct for normal operation but has two blind spots the session
+ *   log closes:
+ *     1. **Loss recovery** — if `.iterate/` is deleted, moved, or the working
+ *        directory changes, the observatory goes blank even though the session
+ *        that produced the run is still open. A compact run record on the
+ *        session log lets `iterate_transcript read` rehydrate the run summary
+ *        instead of returning an empty view.
+ *     2. **Session anchoring** — run provenance is tied to the *session* that
+ *        produced it, not only to whatever directory the process happens to be
+ *        in when someone looks afterwards.
+ *
+ * Design (fail-safe, never a hard dependency):
+ *   - The API is loaded lazily via a dynamic `import()` and used structurally
+ *     (no compile-time coupling to `PluginRecordMap`), so a host whose copy of
+ *     `@deepseek-ai/dsh-session` predates the API simply reports
+ *     `supported: false` instead of failing to load the plugin.
+ *   - Every entry point returns a structured result; nothing throws. Writing a
+ *     record is best-effort — a run must never fail because the session log
+ *     could not accept a bookkeeping record.
+ *   - `normalizeRunRecord` re-validates a restored payload, because a record
+ *     read from a resumed session carries whatever JSON an earlier build wrote.
+ */
+
+/** The `plugin:` record type this plugin owns (grammar-checked by dsh). */
+export const ITERATE_RUN_RECORD_TYPE = 'plugin:iterate/run'
+/** Bump when the record payload shape changes incompatibly. */
+export const ITERATE_RUN_RECORD_VERSION = 1
+
+/** Compact, lossless-JSON summary of one iterate run at a point in time. */
+export interface IterateRunRecord {
+  version: number
+  /** Project root the run belongs to (absolute at write time). */
+  project: string
+  goal: string
+  mode: 'dry-run' | 'normal' | null
+  taskMode: 'code' | 'iterate' | null
+  /** Highest round reached. */
+  round: number
+  maxRounds: number
+  /** False once the run recorded a terminal `stoppedReason`. */
+  active: boolean
+  stoppedReason: string | null
+  /** Per-round NEW-finding counts, newest last (drives the F2 trend on recovery). */
+  convergence: number[]
+  findings: {
+    total: number
+    critical: number
+    high: number
+    medium: number
+    low: number
+  }
+  /** Applied (successful) fixes recorded so far. */
+  fixedCount: number
+  /** Snapshot of the quality-gate verdict at write time, when known. */
+  qualityStatus: 'pass' | 'fail' | 'pending' | null
+  /** ISO timestamp the record was written. */
+  updatedAt: string
+}
+
+/** A run record read back from a session log, with its log position. */
+export interface StoredRunRecord extends IterateRunRecord {
+  /** Session-log sequence number the record occupies. */
+  seq: number
+  /** Unix epoch milliseconds at append (from the host). */
+  time: number
+}
+
+/** Minimal structural view of the session-log API we consume. */
+export interface SessionRecordApi {
+  appendPluginRecord(session: unknown, type: string, data: unknown): number
+  pluginRecordOf(event: unknown): { type: string; seq: number; time: number; data: unknown } | undefined
+}
+
+/** Minimal structural view of a dsh Session (only what this module reads). */
+export interface SessionLike {
+  ownEvents?(): readonly unknown[]
+  snapshotEvents?(): readonly unknown[]
+}
+
+/** Result of a best-effort record append. */
+export type AppendRecordResult =
+  | { ok: true; supported: true; seq: number }
+  | { ok: false; supported: boolean; error: string }
+
+/** Result of reading the session's iterate run records. */
+export interface ReadRecordsResult {
+  supported: boolean
+  /** Oldest → newest. */
+  records: StoredRunRecord[]
+  /** Present only when the read itself failed unexpectedly. */
+  error?: string
+}
+
+// ─── Pure payload construction / validation ─────────────────────────────────
+
+/** Coerce an unknown to a finite non-negative integer, else `fallback`. */
+function nonNegInt(value: unknown, fallback = 0): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  const n = Math.floor(value)
+  return n >= 0 ? n : fallback
+}
+
+/** Extract a string, else `''`. */
+function str(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+/** Extract one of the allowed literal values, else `null`. */
+function oneOf<T extends string>(value: unknown, allowed: readonly T[]): T | null {
+  return typeof value === 'string' && (allowed as readonly string[]).includes(value) ? (value as T) : null
+}
+
+/** Severity counts recovered from an on-disk manifest summary. */
+export interface RunRecordCounts {
+  total: number
+  critical: number
+  high: number
+  medium: number
+  low: number
+}
+
+/**
+ * Build a run record from the fields a persisted transcript manifest exposes.
+ * Pure: the caller passes already-normalized values, so this is unit-testable
+ * without touching disk or a session.
+ */
+export function buildRunRecord(input: {
+  project?: unknown
+  goal?: unknown
+  mode?: unknown
+  taskMode?: unknown
+  round?: unknown
+  maxRounds?: unknown
+  active?: unknown
+  stoppedReason?: unknown
+  convergence?: unknown
+  counts?: Partial<RunRecordCounts>
+  fixedCount?: unknown
+  qualityStatus?: unknown
+  now?: string
+}): IterateRunRecord {
+  const convergence = Array.isArray(input.convergence)
+    ? input.convergence
+        .filter((n): n is number => typeof n === 'number' && Number.isFinite(n) && n >= 0)
+        .slice(-1000)
+    : []
+  const c = input.counts ?? {}
+  const stopped = str(input.stoppedReason)
+  return {
+    version: ITERATE_RUN_RECORD_VERSION,
+    project: str(input.project),
+    goal: str(input.goal),
+    mode: oneOf(input.mode, ['dry-run', 'normal'] as const),
+    taskMode: oneOf(input.taskMode, ['code', 'iterate'] as const),
+    round: nonNegInt(input.round),
+    maxRounds: nonNegInt(input.maxRounds),
+    active: input.active !== false,
+    stoppedReason: stopped ? stopped : null,
+    convergence,
+    findings: {
+      total: nonNegInt(c.total),
+      critical: nonNegInt(c.critical),
+      high: nonNegInt(c.high),
+      medium: nonNegInt(c.medium),
+      low: nonNegInt(c.low),
+    },
+    fixedCount: nonNegInt(input.fixedCount),
+    qualityStatus: oneOf(input.qualityStatus, ['pass', 'fail', 'pending'] as const),
+    updatedAt: str(input.now) || new Date().toISOString(),
+  }
+}
+
+/**
+ * Owner-side validation of a payload read back from a session log.
+ * A restored record carries whatever JSON an earlier build of this plugin
+ * wrote, so every field is re-checked; anything unrecognizable returns `null`
+ * (the caller skips it) rather than surfacing junk to a renderer.
+ */
+export function normalizeRunRecord(data: unknown): IterateRunRecord | null {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return null
+  const d = data as Record<string, unknown>
+  // A record written by a future/incompatible build is skipped rather than
+  // coerced: the version gate is the contract that lets the payload evolve.
+  if (nonNegInt(d.version) !== ITERATE_RUN_RECORD_VERSION) return null
+  const findings = (d.findings && typeof d.findings === 'object' && !Array.isArray(d.findings)
+    ? (d.findings as Record<string, unknown>)
+    : {}) as Record<string, unknown>
+  return buildRunRecord({
+    project: d.project,
+    goal: d.goal,
+    mode: d.mode,
+    taskMode: d.taskMode,
+    round: d.round,
+    maxRounds: d.maxRounds,
+    active: d.active,
+    stoppedReason: d.stoppedReason,
+    convergence: d.convergence,
+    counts: {
+      total: findings.total as number,
+      critical: findings.critical as number,
+      high: findings.high as number,
+      medium: findings.medium as number,
+      low: findings.low as number,
+    },
+    fixedCount: d.fixedCount,
+    qualityStatus: d.qualityStatus,
+    now: typeof d.updatedAt === 'string' ? d.updatedAt : undefined,
+  })
+}
+
+// ─── Session access (lazy, fail-safe) ────────────────────────────────────────
+
+/** Lazily-resolved production API; `undefined` = not yet attempted. */
+let cachedApi: Promise<SessionRecordApi | null> | undefined
+/** Test override; when set (including `null`) the dynamic import is bypassed. */
+let testApiOverride: SessionRecordApi | null | undefined
+
+/** Resolve the `@deepseek-ai/dsh-session` record API, or `null` when absent. */
+export function loadSessionRecordApi(): Promise<SessionRecordApi | null> {
+  if (testApiOverride !== undefined) return Promise.resolve(testApiOverride)
+  if (cachedApi === undefined) {
+    cachedApi = import('@deepseek-ai/dsh-session')
+      .then((mod) => {
+        const m = mod as unknown as Partial<SessionRecordApi>
+        if (typeof m.appendPluginRecord !== 'function' || typeof m.pluginRecordOf !== 'function') {
+          return null
+        }
+        return {
+          appendPluginRecord: m.appendPluginRecord.bind(mod),
+          pluginRecordOf: m.pluginRecordOf.bind(mod),
+        }
+      })
+      .catch(() => null)
+  }
+  return cachedApi
+}
+
+/**
+ * Override the session-record API for tests. Pass `undefined` to restore the
+ * real dynamic import, or an object / `null` to force a deterministic result.
+ */
+export function setSessionRecordApiForTests(api: SessionRecordApi | null | undefined): void {
+  testApiOverride = api
+}
+
+/** Extract the session from a tool execution (`exec.agent.session`), defensively. */
+export function sessionOf(exec: unknown): SessionLike | undefined {
+  try {
+    const agent = (exec as { agent?: { session?: unknown } } | null | undefined)?.agent
+    const session = agent?.session
+    if (!session || typeof session !== 'object') return undefined
+    const s = session as SessionLike
+    if (typeof s.ownEvents === 'function' || typeof s.snapshotEvents === 'function') return s
+    return undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Read every event a session exposes (own events preferred, snapshot fallback). */
+function eventsOf(session: SessionLike): readonly unknown[] {
+  try {
+    if (typeof session.ownEvents === 'function') return session.ownEvents() ?? []
+  } catch {
+    // fall through to snapshot
+  }
+  try {
+    if (typeof session.snapshotEvents === 'function') return session.snapshotEvents() ?? []
+  } catch {
+    // no readable log
+  }
+  return []
+}
+
+/**
+ * Best-effort append of one run record to the session log.
+ * Never throws: an absent API, a degraded session, or a rejected payload all
+ * surface as `{ ok: false }` so the surrounding tool call can continue.
+ */
+export async function appendRunRecord(
+  session: SessionLike | undefined,
+  record: IterateRunRecord,
+): Promise<AppendRecordResult> {
+  const api = await loadSessionRecordApi()
+  if (!api) return { ok: false, supported: false, error: 'session record API unavailable' }
+  if (!session) return { ok: false, supported: true, error: 'no session in scope' }
+  try {
+    const seq = api.appendPluginRecord(session, ITERATE_RUN_RECORD_TYPE, record)
+    return { ok: true, supported: true, seq }
+  } catch (err) {
+    return {
+      ok: false,
+      supported: true,
+      error: `session rejected the run record: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+}
+
+/** Read every iterate run record from the session log (oldest → newest). */
+export async function readRunRecords(session: SessionLike | undefined): Promise<ReadRecordsResult> {
+  const api = await loadSessionRecordApi()
+  if (!api) return { supported: false, records: [] }
+  if (!session) return { supported: true, records: [] }
+  try {
+    const records: StoredRunRecord[] = []
+    for (const event of eventsOf(session)) {
+      const rec = api.pluginRecordOf(event)
+      if (!rec || rec.type !== ITERATE_RUN_RECORD_TYPE) continue
+      const normalized = normalizeRunRecord(rec.data)
+      if (!normalized) continue
+      records.push({ ...normalized, seq: nonNegInt(rec.seq), time: nonNegInt(rec.time) })
+    }
+    return { supported: true, records }
+  } catch (err) {
+    return {
+      supported: true,
+      records: [],
+      error: `failed to read session records: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+}

package/src/skill-prompt.ts

@@ -23,7 +23,8 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence, and whether the run was interrupted (a checkpoint on disk with no newer decision-log activity means the previous run was interrupted and can be resumed)
 - \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
 - \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
-- \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers; \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, per-round validation results (\`validations\`: command + exitCode + allowed + rejectReason), and timeline so the client observatory panel reflects the run; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
+- \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers — and, when the file is missing or malformed, recovers a summary manifest from the session log's run record (returns \`recovered:true\`); \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, per-round validation results (\`validations\`: command + exitCode + allowed + rejectReason), and timeline so the client observatory panel reflects the run, and links the run to the dsh session (\`sessionRecord\`); \`recall\` lists the run records linked to this session (newest first) so a run stays traceable after \`.iterate/\` is wiped; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
+- \`iterate_report\` — export the current run as a portable report. \`format:"markdown"\` (default) renders a PR-pasteable report (run header, quality gate, findings, fixes, validations, defense events, experience bank); \`format:"sarif"\` renders a SARIF 2.1.0 log for CI / GitHub Code Scanning (one rule per review dimension, severity → error/warning/note, file+line locations, suggested fix attached). Set \`write:true\` to persist it under \`.iterate/report.md\` / \`.iterate/report.sarif\`; \`lang\` (zh | en) selects the report language. Read-only apart from the optional report file.
 - \`iterate_experience\` — experience bank (\`.iterate/experience.json\`): \`list\`/\`search\`/\`get\` recall verified fixes and patterns from past sessions (read the bank before fixing so proven fixes are applied first); \`add\` records a new verified fix — re-adding the same pattern+dimension bumps its hit count instead of duplicating it; \`remove\` deletes a stale or incorrect entry by \`id\` so bad experiences never resurface.
 - \`iterate_quality_gate\` — quality certificate: \`read\` loads the persisted dimension convergence rates / verification pass rate / PASS-FAIL status; \`compute\` recomputes a fresh snapshot from this round's findings + validation results (supply \`findingsByRound\` for real convergence) and persists it to \`.iterate/quality-gate.json\`; \`clear\` removes the persisted certificate to reset a stale gate before a fresh iteration.
 - \`iterate_defense_events\` — defense event stream (\`.iterate/defense-events.json\`): \`list\`/\`counts\` review precondition failures, rollbacks, invariant violations, and falsified assumptions; \`record\` logs a new event when a defense fires. Human-readable labels follow the project \`language\` (en/zh).
@@ -135,7 +136,7 @@ for (let r = 1; r <= maxRounds; r++) {
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Already-known findings (do NOT re-report): ' +
         JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.'
-      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta?.findingsSchema }, backend))
     }))
     // A per-dimension reviewer subagent resolves \`null\` on child failure; the
     // aggregate below would report an all-failed round as an empty round, and
@@ -464,7 +465,7 @@ for (let r = startRound; r <= maxRounds; r++) {
         (steering ? '\\n STEERING — read this first: ' + steering : '') +
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.'
-      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta?.findingsSchema }, backend))
     }))
     // ALL reviewers returning null (child failures) means this round produced
     // no usable output — an empty aggregate must not read like a clean

package/src/tools/checkpoint.ts

@@ -14,6 +14,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { writeJsonAtomic } from '../atomic-fs.ts'
+import { withProjectLock } from '../file-lock.ts'
 import { checkpointPath, iterateDir, transcriptPath } from '../paths.ts'
 import { readRegistry } from './fix.ts'
 import { readDecisionEntries } from './decision-log.ts'
@@ -322,22 +323,28 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
         }
 
         if (args.operation === 'resume') {
-          const current = readCheckpoint(projectRoot)
-          if (!current) {
-            return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' }
-          }
-          const resumed: IterationCheckpoint = {
-            ...current,
-            resumeCount: (current.resumeCount ?? 0) + 1,
-            updatedAt: new Date().toISOString(),
-          }
-          try {
-            mkdirSync(iterateDir(projectRoot), { recursive: true })
-            writeJsonAtomic(checkpointPath(projectRoot), resumed)
-          } catch (err) {
-            return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` }
-          }
-          return { operation: 'resume', ok: true, checkpoint: resumed as unknown as JsonValue }
+          // Read-modify-write across processes: a concurrent resume in a
+          // sibling process would read the same resumeCount and write it back,
+          // losing one increment. Serialize on a checkpoint lock (the same
+          // advisory pattern the config/triage/transcript writers use).
+          return withProjectLock(projectRoot, 'checkpoint', () => {
+            const current = readCheckpoint(projectRoot)
+            if (!current) {
+              return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' }
+            }
+            const resumed: IterationCheckpoint = {
+              ...current,
+              resumeCount: (current.resumeCount ?? 0) + 1,
+              updatedAt: new Date().toISOString(),
+            }
+            try {
+              mkdirSync(iterateDir(projectRoot), { recursive: true })
+              writeJsonAtomic(checkpointPath(projectRoot), resumed)
+            } catch (err) {
+              return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` }
+            }
+            return { operation: 'resume', ok: true, checkpoint: resumed as unknown as JsonValue }
+          })
         }
 
         if (args.operation === 'clear') {

package/src/tools/config.ts

@@ -9,6 +9,7 @@ import {
   validateConfigUpdates,
   writeConfigFile,
 } from '../config-write.ts'
+import { withProjectLock } from '../file-lock.ts'
 
 /**
  * Register the `iterate_config` tool.
@@ -121,40 +122,48 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           if (updateErrors.length > 0) {
             return { operation: 'write', ok: false, found: false, errors: updateErrors }
           }
-          let base: Record<string, unknown>
-          try {
-            // Partial updates must be mergeable on a FRESH project (no config
-            // file yet): otherwise `{max_rounds: 5}` alone fails schema
-            // validation with a misleading "missing goal". Merge against the
-            // built-in defaults when there is no file to read, so the written
-            // config captures the effective config (defaults + update) and the
-            // documented "write a partial update" contract works out of the box.
-            base = existsSync(join(projectRoot, 'iterate.config.yaml'))
-              ? readRawConfig(join(projectRoot, 'iterate.config.yaml'))
-              : (defaultConfig() as unknown as Record<string, unknown>)
-          } catch (err) {
-            return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` }
-          }
-          const merged = applyConfigUpdates(base, updates ?? {})
-          const schemaErrors = validateConfig(merged)
-          if (schemaErrors.length > 0) {
+          // Serialize the read→merge→validate→write cycle against any other
+          // config/triage writer in a sibling process: without the lock, two
+          // sessions on the same project each read a stale base and the second
+          // merge silently discards the first's update (lost update). The same
+          // lock name is shared with `iterate_triage apply` so the two writers
+          // are mutually exclusive.
+          return withProjectLock(projectRoot, 'config-write', () => {
+            let base: Record<string, unknown>
+            try {
+              // Partial updates must be mergeable on a FRESH project (no config
+              // file yet): otherwise `{max_rounds: 5}` alone fails schema
+              // validation with a misleading "missing goal". Merge against the
+              // built-in defaults when there is no file to read, so the written
+              // config captures the effective config (defaults + update) and the
+              // documented "write a partial update" contract works out of the box.
+              base = existsSync(join(projectRoot, 'iterate.config.yaml'))
+                ? readRawConfig(join(projectRoot, 'iterate.config.yaml'))
+                : (defaultConfig() as unknown as Record<string, unknown>)
+            } catch (err) {
+              return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` }
+            }
+            const merged = applyConfigUpdates(base, updates ?? {})
+            const schemaErrors = validateConfig(merged)
+            if (schemaErrors.length > 0) {
+              return {
+                operation: 'write',
+                ok: false,
+                found: false,
+                errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+              }
+            }
+            const result = writeConfigFile(projectRoot, merged)
+            if (!result.ok) return { operation: 'write', ok: false, found: false, error: result.error }
+            const { config } = loadEffectiveConfig(projectRoot)
             return {
               operation: 'write',
-              ok: false,
-              found: false,
-              errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+              ok: true,
+              found: true,
+              backupPath: result.backupPath ?? null,
+              config: config as unknown as JsonValue,
             }
-          }
-          const result = writeConfigFile(projectRoot, merged)
-          if (!result.ok) return { operation: 'write', ok: false, found: false, error: result.error }
-          const { config } = loadEffectiveConfig(projectRoot)
-          return {
-            operation: 'write',
-            ok: true,
-            found: true,
-            backupPath: result.backupPath ?? null,
-            config: config as unknown as JsonValue,
-          }
+          })
         }
 
         // ── Read operations (original behavior) ────────────────────────────

package/src/tools/decision-log.ts

@@ -3,17 +3,13 @@ import {
   readFileSync,
   mkdirSync,
   existsSync,
-  openSync,
-  writeSync,
-  closeSync,
-  unlinkSync,
   statSync,
 } from 'node:fs'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
-import { makeLockRelease } from '../file-lock.ts'
+import { acquireProjectLockChecked } from '../file-lock.ts'
 import type { DecisionLogEntry } from '../types.ts'
 
 const LOG_DIR = '.iterate'
@@ -34,35 +30,16 @@ const LOG_FILE = 'decision-log.jsonl'
 // opposite — it renames the log and therefore refuses to run when the lock
 // cannot be taken (see `rewriteDecisionLogKeepingRecent` in prune.ts).
 
-const LOCK_FILE = '.decision-log.lock'
-const LOCK_WAIT_MS = 5000
-const LOCK_STALE_MS = 10000
-const LOCK_POLL_MS = 25
-
-/** True when a pid refers to a live process (or we lack permission to tell). */
-function processAlive(pid: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false
-  try {
-    process.kill(pid, 0)
-    return true
-  } catch (err) {
-    return (err as NodeJS.ErrnoException).code === 'EPERM'
-  }
-}
-
-/** Synchronous busy-wait sleep (Atomics.wait is a reliable sleep in Node). */
-function sleepSync(ms: number): void {
-  const sab = new Int32Array(new SharedArrayBuffer(4))
-  Atomics.wait(sab, 0, 0, ms)
-}
+/** Lock name shared with the prune rewrite (→ `.iterate/.decision-log.lock`). */
+const LOG_LOCK_NAME = 'decision-log'
 
 /**
  * Acquire the decision-log lock for `projectRoot`.
  * Returns a release function (always callable; a no-op when the lock could
  * not be taken — never wedge an append behind a vanished holder).
  *
- * `options.waitMs` / `options.staleMs` override the defaults (tests use short
- * waits so a live-holder timeout is exercised in milliseconds, not 5s).
+ * `options.waitMs` / `options.staleMs` override the shared defaults (tests use
+ * short waits so a live-holder timeout is exercised in milliseconds, not 5s).
  */
 export function acquireLogLock(
   projectRoot: string,
@@ -77,63 +54,18 @@ export function acquireLogLock(
  * audit line must not be lost to a wedged append), but the rewrite renames the
  * log under any unlocked concurrent appender — it must refuse to run without
  * the mutex rather than silently dropping an audit line.
+ *
+ * Delegates to the shared `acquireProjectLockChecked` with lock name
+ * `decision-log`: the decision-log mutex IS that generic project lock. This
+ * module used to hand-roll an identical copy of the acquire/steal/wait logic,
+ * and the two stale/wait parameter sets could drift apart — one implementation,
+ * one set of defaults, one ownership-checked release.
  */
 export function acquireLogLockChecked(
   projectRoot: string,
   options: { waitMs?: number; staleMs?: number } = {},
 ): { acquired: boolean; release: () => void } {
-  const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
-    ? (options.waitMs as number)
-    : LOCK_WAIT_MS
-  const staleMs = Number.isFinite(options.staleMs) && (options.staleMs ?? 0) >= 0
-    ? (options.staleMs as number)
-    : LOCK_STALE_MS
-  const dir = join(projectRoot, LOG_DIR)
-  if (!existsSync(dir)) {
-    try {
-      mkdirSync(dir, { recursive: true })
-    } catch {
-      return { acquired: false, release: () => {} }
-    }
-  }
-  const lockPath = join(dir, LOCK_FILE)
-  const start = Date.now()
-  for (;;) {
-    let fd: number | null = null
-    try {
-      fd = openSync(lockPath, 'wx')
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return { acquired: false, release: () => {} }
-      // Lock exists — steal it when the owner is gone or the lock is ancient.
-      let stale = false
-      try {
-        const st = statSync(lockPath)
-        if (Date.now() - st.mtimeMs > staleMs) stale = true
-        else {
-          const pid = Number(readFileSync(lockPath, 'utf-8'))
-          if (!processAlive(pid)) stale = true
-        }
-      } catch {
-        stale = true // unreadable/vanishing lock → retry as stale
-      }
-      if (stale) {
-        try { unlinkSync(lockPath) } catch { /* another holder stole it */ }
-        continue
-      }
-      if (Date.now() - start > waitMs) return { acquired: false, release: () => {} }
-      sleepSync(LOCK_POLL_MS)
-      continue
-    }
-    // Owned the lock: stamp the holder pid, then release once on return.
-    // The release is ownership-checked (see `makeLockRelease`): a lock stolen
-    // from this process after its owner went stale must not be unlinked by us.
-    try { writeSync(fd, String(process.pid)) } catch { /* pid stamp is advisory */ }
-    try { closeSync(fd) } catch { /* best-effort */ }
-    return {
-      acquired: true,
-      release: makeLockRelease(lockPath),
-    }
-  }
+  return acquireProjectLockChecked(projectRoot, LOG_LOCK_NAME, options)
 }
 
 // ─── Entry-count cache (avoid an O(n) full re-read per append) ─────────────