iterate-plugin 3.5.7 → 3.7.0

package/dist/file-lock.js

@@ -0,0 +1,193 @@
+/**
+ * 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;
+/** True when a pid refers to a live process (or we lack permission to tell). */
+function processAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** Synchronous sleep (Atomics.wait is a reliable sleep in Node). */
+function sleepSync(ms) {
+    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) {
+    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, name, options = {}) {
+    const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
+        ? options.waitMs
+        : DEFAULT_WAIT_MS;
+    const staleMs = Number.isFinite(options.staleMs) && (options.staleMs ?? 0) >= 0
+        ? options.staleMs
+        : 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 = null;
+        try {
+            fd = openSync(lockPath, 'wx');
+        }
+        catch (err) {
+            if (err.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
+        }
+        return makeLockRelease(lockPath);
+    }
+}
+/**
+ * Build the release function for a lock file this process just acquired.
+ *
+ * Advisory locks here are STOLEN when the recorded owner dies or the mtime
+ * goes ancient: the steal unlinks our file and creates a new one stamped with
+ * the STEALER's pid. An unguarded release would then unlink the new holder's
+ * lock — turning our release into a double-release that admits a third process
+ * into a "held" critical section. So the release re-reads the stamp and only
+ * unlinks a file that is still ours (same pid) or unstamped (the shape left
+ * when our own advisory pid write failed, or when the content is not a pid).
+ *
+ * Always callable, idempotent, and never throws.
+ */
+export function makeLockRelease(lockPath) {
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        let raw = '';
+        try {
+            raw = readFileSync(lockPath, 'utf-8').trim();
+        }
+        catch {
+            // Already gone (or unreadable) — nothing of ours left to remove.
+            return;
+        }
+        // A stamp naming another pid means the lock was stolen and reassigned:
+        // it is no longer ours to delete.
+        if (raw !== '' && Number(raw) !== process.pid)
+            return;
+        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(projectRoot, name, fn, options = {}) {
+    const release = acquireProjectLock(projectRoot, name, options);
+    try {
+        return fn();
+    }
+    finally {
+        release();
+    }
+}

package/dist/index.js

@@ -43,38 +43,71 @@ import { registerQualityGateTool } from "./tools/quality-gate.js";
 import { registerDefenseEventsTool } from "./tools/defense-events.js";
 import { registerSessionHooks } from "./session-hooks.js";
 import { registerLiveCapture } from "./live.js";
+import { installWorkingDirectoryContext } from "./working-directory.js";
 import { ITERATE_SKILL_PROMPT } from "./skill-prompt.js";
 export const name = 'iterate-plugin';
 export const inject = ['tools', 'systemPrompt'];
 export function apply(ctx) {
-    // 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.
+    //
+    //    The working-directory context is installed first for the same reason:
+    //    every cwd read below (gate policy, live capture, tool project roots)
+    //    must see dsh 0.2.1-alpha.2+ directory switches, and installing it last
+    //    would leave a partially-loaded plugin resolving the wrong workspace.
+    installWorkingDirectoryContext(ctx);
     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 = [
+        ['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/dist/jobs.js

@@ -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.
  */
 /**
  * Read `ctx.jobs` defensively: the dsh plugin context can be a Proxy whose
@@ -30,11 +39,25 @@ function safeJobs(ctx) {
         return 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) {
+    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}.
@@ -44,21 +67,43 @@ function safeJobs(ctx) {
  */
 export async function runWithJob(ctx, kind, label, fn) {
     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 };
     }
     let settle;
     const done = new Promise((resolve) => {
         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 = null;
+    const annotate = (detail) => cancelRequested === null
+        ? detail
+        : `${detail} (cancel requested: ${cancelRequested} — the wrapped tool call has no abort channel and ran to completion)`;
     let jobId = null;
     try {
-        jobId = jobs.start({
+        jobId = start.call(jobs, {
             kind,
             label,
-            run: () => ({
+            run: (job) => ({
                 done,
-                cancel: () => settle({ status: 'killed', detail: 'cancelled' }),
+                cancel: (reason) => {
+                    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 */
+                    }
+                },
             }),
         });
     }
@@ -69,13 +114,13 @@ export async function runWithJob(ctx, kind, label, fn) {
     }
     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/dist/live.js

@@ -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
@@ -27,7 +30,8 @@ import { mkdir, readFile, stat, appendFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { writeTextAtomicAsync } from "./atomic-fs.js";
 import { join } from 'node:path';
-import { resolveProjectRoot } from "./config-loader.js";
+import { loadEffectiveConfig, resolveProjectRoot } from "./config-loader.js";
+import { sessionCwdOf } from "./working-directory.js";
 /** Keep at most this many live activity entries. */
 export const LIVE_MAX_ENTRIES = 300;
 /** Rewrite the live file when its byte size exceeds this threshold. */
@@ -51,14 +55,41 @@ function enqueueLiveWrite(task) {
     liveWriteQueue = next.catch(() => { });
     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) {
+    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, entry) {
     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');
@@ -77,7 +108,7 @@ export function appendLive(projectRoot, entry) {
 }
 /** Resolve the project root a tool execution belongs to, if any. */
 function projectRootOf(exec) {
-    const cwd = exec.agent?.session?.header?.cwd;
+    const cwd = sessionCwdOf(exec);
     if (!cwd)
         return null;
     const resolved = resolveProjectRoot(undefined, cwd);
@@ -167,12 +198,21 @@ export async function readLive(projectRoot) {
  */
 export function registerLiveCapture(ctx) {
     ctx.on('tools/result', (exec) => {
-        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.
+        }
     });
 }