iterate-plugin 3.5.6 → 3.6.0

package/src/file-lock.ts

@@ -0,0 +1,184 @@
+/**
+ * src/file-lock.ts — generic cross-process advisory lock for `.iterate/` state.
+ *
+ * Several plugin writers mutate small JSON/JSONL state files with a
+ * read-modify-write cycle (fix registry, decision log, defense events,
+ * experience bank). `writeJsonAtomic` only makes a SINGLE write atomic — two
+ * plugin processes racing on the same project can still lose an update between
+ * their read and their write. The decision log already guards itself with a
+ * purpose-built mutex (see `tools/decision-log.ts`); this module generalizes
+ * that exact pattern so every other writer can serialize the same way.
+ *
+ * Semantics (identical to the decision-log lock, deliberately):
+ *   - exclusive create (`openSync(..., 'wx')`) with the holder pid stamped in;
+ *   - a lock whose owner process is gone, or whose mtime is ancient, is
+ *     stolen (unlink + retry);
+ *   - bounded wait — on timeout the lock degrades to "proceed unlocked"
+ *     (returns a callable no-op release) instead of wedging the tool call;
+ *   - the returned release is always callable, idempotent, and never throws.
+ *
+ * Best-effort by design: an advisory lock that cannot be taken must never turn
+ * a working tool into a failed one; the worst case is the pre-existing
+ * (unlocked) behavior.
+ *
+ * In-process callers get synchronous mutual exclusion through the same API —
+ * tools run on one thread, so acquiring twice in one process would self-deadlock;
+ * `withProjectLock` is therefore NOT reentrant and must not be nested for the
+ * same (projectRoot, name).
+ */
+
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeSync,
+} from 'node:fs'
+import { join } from 'node:path'
+
+const LOCK_DIR = '.iterate'
+const DEFAULT_WAIT_MS = 5000
+const DEFAULT_STALE_MS = 10000
+const POLL_MS = 25
+
+/** Tunables for tests (short waits) and callers wanting a different budget. */
+export interface LockOptions {
+  /** Max time to wait for a live holder before proceeding unlocked. */
+  waitMs?: number
+  /** Age after which an existing lock file is considered abandoned. */
+  staleMs?: number
+}
+
+/** 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 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)
+}
+
+/**
+ * Validate a lock name into a safe file-name fragment.
+ * Throws on anything that could escape `.iterate/` (path separators, dots).
+ */
+function lockFileName(name: string): string {
+  if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(name)) {
+    throw new Error(`invalid lock name: ${JSON.stringify(name)}`)
+  }
+  return `.${name}.lock`
+}
+
+/**
+ * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`.
+ *
+ * Returns a release function: always callable, idempotent, never throws.
+ * A no-op (but callable) release is returned when the lock directory cannot be
+ * created or the wait times out — callers then proceed unlocked, which is the
+ * historical best-effort behavior, rather than failing the operation.
+ */
+export function acquireProjectLock(
+  projectRoot: string,
+  name: string,
+  options: LockOptions = {},
+): () => void {
+  const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
+    ? (options.waitMs as number)
+    : DEFAULT_WAIT_MS
+  const staleMs = Number.isFinite(options.staleMs) && (options.staleMs ?? 0) >= 0
+    ? (options.staleMs as number)
+    : DEFAULT_STALE_MS
+
+  const dir = join(projectRoot, LOCK_DIR)
+  if (!existsSync(dir)) {
+    try {
+      mkdirSync(dir, { recursive: true })
+    } catch {
+      return () => {}
+    }
+  }
+  const lockPath = join(dir, lockFileName(name))
+  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 () => {}
+      // 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 first — retry immediately
+        }
+        continue
+      }
+      if (Date.now() - start > waitMs) return () => {}
+      sleepSync(POLL_MS)
+      continue
+    }
+    // Owned the lock: stamp the holder pid, then release once on return.
+    try {
+      writeSync(fd, String(process.pid))
+    } catch {
+      // pid stamp is advisory
+    }
+    try {
+      closeSync(fd)
+    } catch {
+      // best-effort
+    }
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      try {
+        unlinkSync(lockPath)
+      } catch {
+        // already gone
+      }
+    }
+  }
+}
+
+/**
+ * Run `fn` while holding the advisory lock named `name`.
+ * The release is guaranteed via `finally`; `fn`'s value or error propagates
+ * unchanged. Not reentrant for the same (projectRoot, name) — see header.
+ */
+export function withProjectLock<T>(
+  projectRoot: string,
+  name: string,
+  fn: () => T,
+  options: LockOptions = {},
+): T {
+  const release = acquireProjectLock(projectRoot, name, options)
+  try {
+    return fn()
+  } finally {
+    release()
+  }
+}

package/src/index.ts

@@ -51,36 +51,60 @@ export const name = 'iterate-plugin'
 export const inject = ['tools', 'systemPrompt'] as const
 
 export function apply(ctx: Context): void {
-  // 1. Register the 17 tools (14 original + 3 v3.0)
-  registerConfigTool(ctx)
-  registerValidateTool(ctx)
-  registerDecisionLogTool(ctx)
-  registerContextTool(ctx)
-  registerReviewTool(ctx)
-  registerTriageTool(ctx)
-  registerFixTool(ctx)
-  registerDiffTool(ctx)
-  registerRollbackTool(ctx)
-  registerCheckpointTool(ctx)
-  registerStatusTool(ctx)
-  registerHistoryTool(ctx)
-  registerPruneTool(ctx)
-  registerTranscriptTool(ctx)
-  // v3.0: Quality Command Center tools
-  registerExperienceBankTool(ctx)
-  registerQualityGateTool(ctx)
-  registerDefenseEventsTool(ctx)
-
-  // 2. Wire the observatory approval gate onto dsh's tools/pre-execute waterfall,
-  //    and the live reviewer-activity feed onto tools/result.
+  // 0. Wire the SAFETY hooks BEFORE any tool is registered.
+  //    Registration is a list of 17 independent calls; if one of them threw
+  //    (duplicate name, malformed definition, hostile ctx) while the gate was
+  //    registered last, the tools registered up to that point would keep
+  //    running with NO `tools/pre-execute` approval gate — a fail-open hole
+  //    created by load order. Registering the gate first means a partial load
+  //    can only ever err on the side of MORE gating, never less.
   registerSessionHooks(ctx)
   registerLiveCapture(ctx)
 
-  // 2. Inject the iterate skill prompt as a system prompt section
-  // This teaches the model how to write iterate workflow scripts using the tools.
-  ctx.systemPrompt.section({
-    name: 'iterate-skill',
-    order: 100,
-    text: ITERATE_SKILL_PROMPT,
-  })
+  // 1. Register the 17 tools (14 original + 3 v3.0). Each registration is
+  //    isolated: one failing tool must not take down the other 16, the gate
+  //    above, or the prompt below (a partial plugin that still gates and
+  //    teaches the workflow beats an aborted `apply`). Failures are logged,
+  //    never swallowed silently.
+  const toolRegistrations: Array<[string, () => void]> = [
+    ['iterate_config', () => registerConfigTool(ctx)],
+    ['iterate_validate', () => registerValidateTool(ctx)],
+    ['iterate_decision_log', () => registerDecisionLogTool(ctx)],
+    ['iterate_context', () => registerContextTool(ctx)],
+    ['iterate_review', () => registerReviewTool(ctx)],
+    ['iterate_triage', () => registerTriageTool(ctx)],
+    ['iterate_fix', () => registerFixTool(ctx)],
+    ['iterate_diff', () => registerDiffTool(ctx)],
+    ['iterate_rollback', () => registerRollbackTool(ctx)],
+    ['iterate_checkpoint', () => registerCheckpointTool(ctx)],
+    ['iterate_status', () => registerStatusTool(ctx)],
+    ['iterate_history', () => registerHistoryTool(ctx)],
+    ['iterate_prune', () => registerPruneTool(ctx)],
+    ['iterate_transcript', () => registerTranscriptTool(ctx)],
+    // v3.0: Quality Command Center tools
+    ['iterate_experience', () => registerExperienceBankTool(ctx)],
+    ['iterate_quality_gate', () => registerQualityGateTool(ctx)],
+    ['iterate_defense_events', () => registerDefenseEventsTool(ctx)],
+  ]
+  for (const [toolName, register] of toolRegistrations) {
+    try {
+      register()
+    } catch (err) {
+      console.warn(`[iterate] failed to register ${toolName}; continuing.`, err)
+    }
+  }
+
+  // 2. Inject the iterate skill prompt as a system prompt section.
+  //    This teaches the model how to write iterate workflow scripts using the
+  //    tools. Guarded for the same reason as above: a prompt-injection failure
+  //    must not undo a load that already wired the gate and the tools.
+  try {
+    ctx.systemPrompt.section({
+      name: 'iterate-skill',
+      order: 100,
+      text: ITERATE_SKILL_PROMPT,
+    })
+  } catch (err) {
+    console.warn('[iterate] failed to inject the skill prompt section; continuing.', err)
+  }
 }

package/src/jobs.ts

@@ -11,10 +11,19 @@
  * - `ctx.jobs` only exists when the dsh host loaded a job registry + a
  *   controller serves the calling owner (`@deepseek-ai/dsh-tool-jobs` or an
  *   equivalent). When it is missing, `start()` throws or is absent — we
- *   detect both and fall through to plain execution, so the Job Panel is a
- *   pure enhancement and never breaks a tool call.
+ *   detect both (including a throwing `start` GETTER) and fall through to
+ *   plain execution, so the Job Panel is a pure enhancement and never breaks
+ *   a tool call.
  * - The registry is memory-only and panel rows are read-only (no progress
  *   updates), so these jobs are completion records, not control channels.
+ * - Cancellation is honest, not theatrical. `JobHooks.cancel` is REQUIRED by
+ *   `@deepseek-ai/dsh-jobs` (the registry calls it on kill/teardown), but the
+ *   wrapped tool `fn` exposes no abort channel — a panel kill cannot stop it.
+ *   So `cancel` records the REQUEST (synchronous + idempotent, first reason
+ *   wins), best-effort surfaces it on the record's progress line, and lets the
+ *   job settle with `fn`'s TRUE outcome, with the request annotated in
+ *   `detail`. Settling the record `killed` while `fn()` keeps running would
+ *   show a stopped job that is still running — a lie in the Job Panel.
  */
 
 import type { JobOutcome, JobRegistry } from '@deepseek-ai/dsh-jobs'
@@ -30,12 +39,18 @@ declare module '@deepseek-ai/dsh-jobs' {
 /** Custom job kinds this plugin registers. */
 export type IterateJobKind = 'iterate-review' | 'iterate-fix'
 
+/** The `JobHandle` surface we use (the registry passes the real one). */
+interface JobHandleLike {
+  updateProgress?(line: string): void
+}
+
 /** Shape of the `ctx.jobs` surface we rely on (duck-typed for safety). */
 interface JobsLike {
   start(spec: {
     kind: IterateJobKind
     label: string
-    run(): { done: Promise<JobOutcome>; cancel?: () => void }
+    // `cancel` mirrors JobHooks: required, synchronous, idempotent.
+    run(job: JobHandleLike): { done: Promise<JobOutcome>; cancel: (reason?: string) => void }
   }): string
 }
 
@@ -53,11 +68,25 @@ function safeJobs(ctx: unknown): JobsLike | undefined {
   }
 }
 
+/**
+ * Read `jobs.start` defensively: the `start` GETTER itself can throw on a
+ * hostile/proxied registry, and that read must degrade the same way as a
+ * missing registry — never escape `runWithJob`.
+ */
+function safeStart(jobs: JobsLike | undefined): JobsLike['start'] | undefined {
+  try {
+    return jobs?.start
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * Run `fn` wrapped in a dsh background job, settling it completed/failed
- * with the execution's outcome. When the host exposes no job registry (or
- * refuses the start), `fn` runs untouched and `null` is returned — the Job
- * Panel is an enhancement, never a dependency.
+ * with the execution's ACTUAL outcome (a requested cancel never falsifies it
+ * — see the header). When the host exposes no job registry (or refuses the
+ * start), `fn` runs untouched and `null` is returned — the Job Panel is an
+ * enhancement, never a dependency.
  *
  * @param ctx      the dsh plugin context (may or may not expose `jobs`).
  * @param kind     iterate job kind registered via {@link IterateJobKind}.
@@ -72,7 +101,8 @@ export async function runWithJob<T>(
   fn: () => Promise<T> | T,
 ): Promise<{ result: T; jobId: string | null }> {
   const jobs = safeJobs(ctx)
-  if (!jobs || typeof jobs.start !== 'function') {
+  const start = safeStart(jobs)
+  if (!jobs || !start || typeof start !== 'function') {
     return { result: await fn(), jobId: null }
   }
 
@@ -81,14 +111,35 @@ export async function runWithJob<T>(
     settle = resolve
   })
 
+  // Honest cancel bookkeeping: the request is recorded (first reason wins),
+  // but `done` is NOT settled here — `fn()` is still running and the panel
+  // must not claim otherwise. The settlement below carries `fn`'s real
+  // outcome, annotated with the request.
+  let cancelRequested: string | null = null
+  const annotate = (detail: string): string =>
+    cancelRequested === null
+      ? detail
+      : `${detail} (cancel requested: ${cancelRequested} — the wrapped tool call has no abort channel and ran to completion)`
+
   let jobId: string | null = null
   try {
-    jobId = jobs.start({
+    jobId = start.call(jobs, {
       kind,
       label,
-      run: () => ({
+      run: (job: JobHandleLike) => ({
         done,
-        cancel: () => settle({ status: 'killed', detail: 'cancelled' }),
+        cancel: (reason?: string) => {
+          if (cancelRequested !== null) return // idempotent — first reason wins
+          cancelRequested = reason ?? 'cancel requested'
+          // Best-effort panel hint while the record is stopping; the registry
+          // drops writes it cannot apply, and a throwing update must not
+          // propagate out of the registry's kill path.
+          try {
+            job?.updateProgress?.('cancel requested — waiting for the tool call to finish (no abort channel)')
+          } catch {
+            /* progress hint is cosmetic */
+          }
+        },
       }),
     })
   } catch {
@@ -99,12 +150,12 @@ export async function runWithJob<T>(
 
   try {
     const result = await fn()
-    settle({ status: 'completed', detail: 'done' })
+    settle({ status: 'completed', detail: annotate('done') })
     return { result, jobId }
   } catch (error) {
     settle({
       status: 'failed',
-      detail: error instanceof Error ? error.message : 'execution failed',
+      detail: annotate(error instanceof Error ? error.message : 'execution failed'),
     })
     throw error
   }

package/src/live.ts

@@ -18,6 +18,9 @@
  * Safety:
  *   - Read-only observer: never mutates source files; writes only the NDJSON
  *     live file under `.iterate/`.
+ *   - Privacy switch: when the project's effective config sets
+ *     `observatory.capture: false`, nothing is persisted (the file stays
+ *     absent/unchanged). An unreadable config keeps capture ON (defaults).
  *   - The live file is byte-capped (rewrite to last N lines when it grows too
  *     large) so it can never grow unbounded.
  *   - Any capture failure is swallowed (fire-and-forget) so it can never block
@@ -30,7 +33,7 @@ import { writeTextAtomicAsync } from './atomic-fs.ts'
 import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
-import { resolveProjectRoot } from './config-loader.ts'
+import { loadEffectiveConfig, resolveProjectRoot } from './config-loader.ts'
 
 /** Keep at most this many live activity entries. */
 export const LIVE_MAX_ENTRIES = 300
@@ -85,14 +88,40 @@ function enqueueLiveWrite(task: () => Promise<void>): Promise<void> {
   return next
 }
 
-/** Append one activity record to the project's live feed (byte-capped). */
+/**
+ * True when the project's effective config still allows live capture.
+ * `observatory.capture: false` opts the project out — nothing is persisted.
+ * Failure modes keep TODAY'S behavior: `loadEffectiveConfig` never throws on
+ * an unreadable config (it falls back to defaults, capture on), and any
+ * unexpected loader error here also degrades to capture ON rather than
+ * silently eating activity the operator expected to see.
+ */
+function captureEnabled(projectRoot: string): boolean {
+  try {
+    return loadEffectiveConfig(projectRoot).config.observatory?.capture !== false
+  } catch {
+    return true
+  }
+}
+
+/**
+ * Append one activity record to the project's live feed (byte-capped).
+ * Never rejects: every failure (capture disabled, `.iterate` existing as a
+ * regular file, locked/unwritable feed) is swallowed — the header promises
+ * this path can never crash or block a tool call (`void appendLive(...)`
+ * would otherwise turn a rejection into an unhandled rejection).
+ */
 export function appendLive(projectRoot: string, entry: LiveActivityEntry): Promise<void> {
   return enqueueLiveWrite(async () => {
-    const file = liveFilePath(projectRoot)
-    const line = JSON.stringify(entry) + '\n'
-    await mkdir(join(projectRoot, '.iterate'), { recursive: true })
-    // Amortized O(1): only read+rewrite when the file has grown past the cap.
     try {
+      // Privacy: capture off → do not touch the feed at all.
+      if (!captureEnabled(projectRoot)) return
+      const file = liveFilePath(projectRoot)
+      const line = JSON.stringify(entry) + '\n'
+      // mkdir is INSIDE the guard: `.iterate` may be a regular file (or the
+      // dir unwritable) — it must reject neither the caller nor the queue.
+      await mkdir(join(projectRoot, '.iterate'), { recursive: true })
+      // Amortized O(1): only read+rewrite when the file has grown past the cap.
       const st = await stat(file).catch(() => null)
       if (st && st.size > LIVE_MAX_BYTES) {
         const raw = await readFile(file, 'utf-8')
@@ -201,10 +230,18 @@ export async function readLive(projectRoot: string): Promise<LiveActivityEntry[]
  */
 export function registerLiveCapture(ctx: Context): void {
   ctx.on('tools/result', (exec: ToolExecution) => {
-    const root = projectRootOf(exec)
-    if (!root) return
-    const entry = classifyTool(exec.name, exec.arguments, root)
-    if (!entry) return
-    void appendLive(root, entry)
+    // Defensive: a hostile/proxied exec whose getters throw (`agent`,
+    // `name`, `arguments`) must not abort the observer — unlike the guarded
+    // siblings below, an unguarded throw here would lose the record and
+    // surface an error from a read-only hook. Degrade to a no-op.
+    try {
+      const root = projectRootOf(exec)
+      if (!root) return
+      const entry = classifyTool(exec.name, exec.arguments, root)
+      if (!entry) return
+      void appendLive(root, entry)
+    } catch {
+      // An observer must never throw.
+    }
   })
 }