iterate-plugin 3.6.0 → 3.8.0

package/dist/tools/config.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFile, } from "../config-write.js";
+import { withProjectLock } from "../file-lock.js";
 /**
  * Register the `iterate_config` tool.
  * Reads and returns the iterate.config.yaml configuration, or writes a
@@ -105,42 +106,50 @@ export function registerConfigTool(ctx) {
                 if (updateErrors.length > 0) {
                     return { operation: 'write', ok: false, found: false, errors: updateErrors };
                 }
-                let base;
-                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();
-                }
-                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;
+                    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();
+                    }
+                    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,
                     };
-                }
-                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,
-                };
+                });
             }
             // ── Read operations (original behavior) ────────────────────────────
             const { config, source } = loadEffectiveConfig(projectRoot);

package/dist/tools/decision-log.js

@@ -1,7 +1,8 @@
-import { appendFileSync, readFileSync, mkdirSync, existsSync, openSync, writeSync, closeSync, unlinkSync, statSync, } from 'node:fs';
+import { appendFileSync, readFileSync, mkdirSync, existsSync, statSync, } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
+import { acquireProjectLockChecked } from "../file-lock.js";
 const LOG_DIR = '.iterate';
 const LOG_FILE = 'decision-log.jsonl';
 // ─── Cross-process log mutex ────────────────────────────────────────────────
@@ -18,34 +19,15 @@ const LOG_FILE = 'decision-log.jsonl';
 // be lost to a wedged append), never to a crash. The prune REWRITE is the
 // 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) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
-}
-/** Synchronous busy-wait 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);
-}
+/** 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, options = {}) {
     return acquireLogLockChecked(projectRoot, options).release;
@@ -56,83 +38,15 @@ export function acquireLogLock(projectRoot, options = {}) {
  * 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, options = {}) {
-    const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
-        ? options.waitMs
-        : LOCK_WAIT_MS;
-    const staleMs = Number.isFinite(options.staleMs) && (options.staleMs ?? 0) >= 0
-        ? options.staleMs
-        : 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 = null;
-        try {
-            fd = openSync(lockPath, 'wx');
-        }
-        catch (err) {
-            if (err.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.
-        try {
-            writeSync(fd, String(process.pid));
-        }
-        catch { /* pid stamp is advisory */ }
-        try {
-            closeSync(fd);
-        }
-        catch { /* best-effort */ }
-        let released = false;
-        return {
-            acquired: true,
-            release: () => {
-                if (released)
-                    return;
-                released = true;
-                try {
-                    unlinkSync(lockPath);
-                }
-                catch { /* already gone */ }
-            },
-        };
-    }
+    return acquireProjectLockChecked(projectRoot, LOG_LOCK_NAME, options);
 }
 // ─── Entry-count cache (avoid an O(n) full re-read per append) ─────────────
 /**

package/dist/tools/transcript.js

@@ -23,6 +23,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { mkdir, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { writeTextAtomicAsync } from "../atomic-fs.js";
+import { withProjectLock } from "../file-lock.js";
 import { dirname } from 'node:path';
 import { loadEffectiveConfig, resolveProjectRootForExec, } from "../config-loader.js";
 import { transcriptPath } from "../paths.js";
@@ -73,7 +74,7 @@ function normalizeCheckpoint(input) {
     if (round <= 0)
         return null;
     return {
-        mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : 'normal',
+        mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : null,
         round,
         maxRounds: typeof c.maxRounds === 'number' && Number.isFinite(c.maxRounds) ? c.maxRounds : 0,
         fixedCount: typeof c.fixedCount === 'number' && Number.isFinite(c.fixedCount) ? c.fixedCount : 0,
@@ -198,7 +199,23 @@ export function registerTranscriptTool(ctx) {
                     'the run console can show which commands ran and whether they passed.',
             },
             refReadFiles: { type: 'json', description: 'For `capture`: flat array of all read files across rounds (optional).' },
-            stoppedReason: { type: 'string', description: 'For `capture`: why the run ended — "converged" | "max_rounds_reached" | "aborted_by_validation" | "aborted_by_config" | "schema_invalid" | "no_usable_reviewer_output" | "inconclusive". When omitted, derived from the convergence trend (trailing 0 = converged, otherwise = max_rounds_reached once a round ran).' },
+            stoppedReason: {
+                type: 'string',
+                // Enum guard: the label renderer keys off this value, so a stray or
+                // prototype-chain string (e.g. "__proto__") must not enter the tool.
+                // The render path additionally uses Object.hasOwn (defense for
+                // hand-edited manifests that bypass this schema).
+                enum: [
+                    'converged',
+                    'max_rounds_reached',
+                    'aborted_by_validation',
+                    'aborted_by_config',
+                    'schema_invalid',
+                    'no_usable_reviewer_output',
+                    'inconclusive',
+                ],
+                description: 'For `capture`: why the run ended — "converged" | "max_rounds_reached" | "aborted_by_validation" | "aborted_by_config" | "schema_invalid" | "no_usable_reviewer_output" | "inconclusive". When omitted, derived from the convergence trend (trailing 0 = converged, otherwise = max_rounds_reached once a round ran).'
+            },
             // `string | null` (NOT plain `type: 'string'`): dsh validates arguments
             // against the compiled schema BEFORE execute, and the docs — plus the
             // client's clear button — advertise `{"operation":"nudge","text":null}`.
@@ -288,52 +305,65 @@ export function registerTranscriptTool(ctx) {
                 };
             }
             if (args.operation === 'nudge') {
-                let manifest = null;
-                if (existsSync(file)) {
-                    try {
-                        const parsed = JSON.parse(await readFile(file, 'utf-8'));
-                        manifest = parsed;
+                // Read-modify-write across processes: a concurrent nudge in a sibling
+                // process would otherwise read the same manifest and write back over
+                // each other's steering text. Serialize on the shared transcript lock
+                // (same pattern as the config/triage writers). The body still awaits,
+                // so the lock is held across the read and write; a same-process
+                // re-entry degrades to unlocked (the advisory lock is per-pid), which
+                // is the documented best-effort fallback for a low-value projection.
+                return withProjectLock(projectRoot, 'transcript', async () => {
+                    let manifest = null;
+                    if (existsSync(file)) {
+                        try {
+                            const parsed = JSON.parse(await readFile(file, 'utf-8'));
+                            manifest = parsed;
+                        }
+                        catch {
+                            manifest = null;
+                        }
                     }
-                    catch {
-                        manifest = null;
+                    // Rehydrating a parsed-but-malformed manifest (e.g. `rounds: [null]`
+                    // or a non-object) must never crash the nudge — degrade to a fresh
+                    // builder so the steering text still lands. The fallback must keep
+                    // the ORIGINAL run identity (mode/taskMode/goal/maxRounds) so a
+                    // stray malformed field can never silently rewrite a dry-run run
+                    // into a `normal` one.
+                    const fallbackOpts = {
+                        project: projectRoot,
+                        mode: (manifest?.mode === 'dry-run' || manifest?.mode === 'normal' ? manifest.mode : null),
+                        taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null),
+                        approval,
+                        goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
+                        maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
+                    };
+                    let builder;
+                    if (manifest) {
+                        try {
+                            builder = rehydrateBuilder(manifest, approval);
+                        }
+                        catch {
+                            builder = new ReviewTranscriptBuilder(fallbackOpts);
+                        }
                     }
-                }
-                // Rehydrating a parsed-but-malformed manifest (e.g. `rounds: [null]`
-                // or a non-object) must never crash the nudge — degrade to a fresh
-                // builder so the steering text still lands. The fallback must keep
-                // the ORIGINAL run identity (mode/taskMode/goal/maxRounds) so a
-                // stray malformed field can never silently rewrite a dry-run run
-                // into a `normal` one.
-                const fallbackOpts = {
-                    project: projectRoot,
-                    mode: (manifest?.mode === 'dry-run' || manifest?.mode === 'normal' ? manifest.mode : null),
-                    taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null),
-                    approval,
-                    goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
-                    maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
-                };
-                let builder;
-                if (manifest) {
-                    try {
-                        builder = rehydrateBuilder(manifest, approval);
+                    else {
+                        // No manifest yet: the run's mode is genuinely unknown at nudge
+                        // time (capture sets it). Recording `mode: 'normal'` here would
+                        // rewrite a dry-run run into a `normal` one in the status/badge
+                        // until capture lands — `null` honestly says "not captured yet".
+                        builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: null, approval });
                     }
-                    catch {
-                        builder = new ReviewTranscriptBuilder(fallbackOpts);
+                    builder.setNudge(typeof args.text === 'string' && args.text.trim() ? args.text : null);
+                    const persisted = await persistChecked(file, builder.serialize());
+                    if (!persisted.ok) {
+                        return { operation: 'nudge', updated: false, error: persisted.error };
                     }
-                }
-                else {
-                    builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval });
-                }
-                builder.setNudge(typeof args.text === 'string' && args.text.trim() ? args.text : null);
-                const persisted = await persistChecked(file, builder.serialize());
-                if (!persisted.ok) {
-                    return { operation: 'nudge', updated: false, error: persisted.error };
-                }
-                return {
-                    operation: 'nudge',
-                    updated: true,
-                    transcript: builder.serialize(),
-                };
+                    return {
+                        operation: 'nudge',
+                        updated: true,
+                        transcript: builder.serialize(),
+                    };
+                });
             }
             // capture
             // `observatory.capture: false` opts the project out of transcript

package/dist/tools/triage.js

@@ -5,6 +5,7 @@ import yaml from 'js-yaml';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { writeTextAtomic } from "../atomic-fs.js";
 import { configBackupSuffix } from "../config-write.js";
+import { withProjectLock } from "../file-lock.js";
 import { WHOLE_FILE_LINE } from "../evidence.js";
 const CONFIG_FILE = 'iterate.config.yaml';
 /** Personalization key that holds the known-intentional list. */
@@ -227,58 +228,64 @@ function readConfigFile(configPath) {
 /** Apply the triage entries: backup, merge, write, rollback on failure. */
 function applyEntries(projectRoot, incoming) {
     const configPath = join(projectRoot, CONFIG_FILE);
-    let config;
-    try {
-        config = readConfigFile(configPath);
-    }
-    catch (err) {
-        // The file exists but is malformed — refuse to overwrite user data.
-        return { ok: false, error: `Failed to read config: ${String(err)}` };
-    }
-    const existing = readKnownIntentional(config);
-    const { merged, added, skipped, dropped } = mergeKnownIntentional(existing, incoming);
-    const nextConfig = buildConfigWithKnownIntentional(config, merged);
-    const hadFile = existsSync(configPath);
-    const backupPath = hadFile ? `${configPath}.bak-${backupSuffix()}` : null;
-    if (backupPath) {
+    // Serialize against `iterate_config write` (SAME lock name) so a triage apply
+    // and a config write on one project cannot interleave their read-modify-write
+    // and silently drop each other's updates. The lock spans read → merge →
+    // backup → write → backup-prune so the whole cycle is atomic.
+    return withProjectLock(projectRoot, 'config-write', () => {
+        let config;
         try {
-            copyFileSync(configPath, backupPath);
+            config = readConfigFile(configPath);
         }
         catch (err) {
-            return {
-                ok: false,
-                error: `Failed to create backup: ${String(err)}`,
-            };
+            // The file exists but is malformed — refuse to overwrite user data.
+            return { ok: false, error: `Failed to read config: ${String(err)}` };
         }
-    }
-    const yamlText = yaml.dump(nextConfig, { noRefs: true });
-    try {
-        writeTextAtomic(configPath, yamlText);
-    }
-    catch (err) {
-        // Rollback: restore the backup, or REMOVE the file we just created when
-        // there was no prior config — an empty file left behind would poison all
-        // future config reads (empty YAML is not a valid mapping).
-        let rollbackError = '';
+        const existing = readKnownIntentional(config);
+        const { merged, added, skipped, dropped } = mergeKnownIntentional(existing, incoming);
+        const nextConfig = buildConfigWithKnownIntentional(config, merged);
+        const hadFile = existsSync(configPath);
+        const backupPath = hadFile ? `${configPath}.bak-${backupSuffix()}` : null;
+        if (backupPath) {
+            try {
+                copyFileSync(configPath, backupPath);
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    error: `Failed to create backup: ${String(err)}`,
+                };
+            }
+        }
+        const yamlText = yaml.dump(nextConfig, { noRefs: true });
         try {
-            if (backupPath)
-                copyFileSync(backupPath, configPath);
-            else if (existsSync(configPath))
-                rmSync(configPath, { force: true });
+            writeTextAtomic(configPath, yamlText);
         }
-        catch (rbErr) {
-            rollbackError = `; rollback also failed: ${String(rbErr)}`;
+        catch (err) {
+            // Rollback: restore the backup, or REMOVE the file we just created when
+            // there was no prior config — an empty file left behind would poison all
+            // future config reads (empty YAML is not a valid mapping).
+            let rollbackError = '';
+            try {
+                if (backupPath)
+                    copyFileSync(backupPath, configPath);
+                else if (existsSync(configPath))
+                    rmSync(configPath, { force: true });
+            }
+            catch (rbErr) {
+                rollbackError = `; rollback also failed: ${String(rbErr)}`;
+            }
+            return {
+                ok: false,
+                error: `Failed to write config: ${String(err)}${rollbackError}`,
+            };
         }
-        return {
-            ok: false,
-            error: `Failed to write config: ${String(err)}${rollbackError}`,
-        };
-    }
-    // Success: bound the accumulation of timestamped backups so a long-lived
-    // project never collects an unbounded pile of config snapshots.
-    if (backupPath)
-        pruneOldConfigBackups(configPath);
-    return { ok: true, added, skipped, dropped, count: merged.length, configPath, backupPath };
+        // Success: bound the accumulation of timestamped backups so a long-lived
+        // project never collects an unbounded pile of config snapshots.
+        if (backupPath)
+            pruneOldConfigBackups(configPath);
+        return { ok: true, added, skipped, dropped, count: merged.length, configPath, backupPath };
+    });
 }
 /**
  * Register the `iterate_triage` tool.

package/dist/transcript.js

@@ -501,7 +501,7 @@ export class ReviewTranscriptBuilder {
             return;
         }
         this.checkpoint = {
-            mode: state.mode === 'dry-run' || state.mode === 'normal' ? state.mode : 'normal',
+            mode: state.mode === 'dry-run' || state.mode === 'normal' ? state.mode : null,
             round: typeof state.round === 'number' ? state.round : 0,
             maxRounds: typeof state.maxRounds === 'number' ? state.maxRounds : 0,
             fixedCount: typeof state.fixedCount === 'number' ? state.fixedCount : 0,
@@ -725,7 +725,7 @@ function normalizeCheckpointRow(input) {
     if (round <= 0)
         return null;
     return {
-        mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : 'normal',
+        mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : null,
         round: clampRoundValue(c.round),
         maxRounds: clampCountValue(c.maxRounds),
         fixedCount: clampCountValue(c.fixedCount),

package/dist/working-directory.js

@@ -0,0 +1,114 @@
+/**
+ * src/working-directory.ts — follow dsh's mutable session working directory.
+ *
+ * Upstream history:
+ *   - through dsh 0.2.1-alpha.1 the session's working directory WAS the
+ *     immutable `Session.header.cwd`, so reading `exec.agent.session.header.cwd`
+ *     was authoritative;
+ *   - dsh 0.2.1-alpha.2 added the `working_directory` tool and the
+ *     `WorkingDirectoryService` (`@deepseek-ai/dsh-working-directory`), whose
+ *     contract explicitly states "the immutable Session header retains the
+ *     ORIGINAL project" while `working-directory/change` events record the
+ *     current one. After a model/user switches directories mid-session,
+ *     `header.cwd` is therefore stale BY DESIGN.
+ *
+ * The iterate plugin resolves the project root (where `.iterate/` lives, where
+ * fixes are written, and — critically — which workspace the F8 approval policy
+ * is read from) from the session cwd. Sticking to `header.cwd` on a host that
+ * supports directory switches would silently operate on the wrong project:
+ * reviews would anchor to the original checkout while the model edits files
+ * elsewhere, and a `deny` policy in the active workspace would be read from
+ * the original one.
+ *
+ * So the effective directory is resolved through the host's service when it
+ * exists, and degrades to `header.cwd` otherwise:
+ *   - feature-detected (`ctx.get('workingDirectory')`) — hosts older than
+ *     0.2.1-alpha.2 simply have no such service and keep the old behavior;
+ *   - `service.get(session)` is the service's synchronous, I/O-free read of
+ *     the committed directory, so this stays safe on the approval path;
+ *   - every failure mode (no service, service throws, hostile getters, a
+ *     non-string result) falls back to `header.cwd`, never to `undefined`
+ *     where a header cwd exists.
+ *
+ * The service object is fetched lazily on every call, not once at plugin
+ * apply: dsh may register the service after this plugin loads, and a disposed
+ * context must degrade rather than cache a dead handle.
+ */
+/** The plugin context, installed once by `apply()`; null on hosts without it. */
+let installedContext = null;
+/** True when `value` looks like a cordis context carrying `ctx.get`. */
+function isContextLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.get === 'function');
+}
+/**
+ * Install the plugin context used to look up the `workingDirectory` service.
+ * Passing anything without a callable `get` clears the installation (tests and
+ * hosts that load the plugin into a degraded context).
+ */
+export function installWorkingDirectoryContext(ctx) {
+    installedContext = isContextLike(ctx) ? ctx : null;
+}
+/** Forget the installed context (test isolation / unload). */
+export function resetWorkingDirectoryContext() {
+    installedContext = null;
+}
+/**
+ * Read the host's committed working directory for `session`, if the host
+ * provides the service and it answers with a usable absolute path.
+ *
+ * Returns `undefined` for every degradation path so callers keep their
+ * previous `header.cwd` behavior.
+ */
+function serviceWorkingDirectory(session) {
+    if (session === undefined || session === null)
+        return undefined;
+    const ctx = installedContext;
+    if (!ctx)
+        return undefined;
+    try {
+        const service = ctx.get?.('workingDirectory');
+        if (!service || typeof service.get !== 'function')
+            return undefined;
+        const dir = service.get(session);
+        // A relative or empty directory would move the project root somewhere
+        // unspecified — refuse it and keep the header value instead.
+        if (typeof dir !== 'string' || dir.length === 0)
+            return undefined;
+        return dir;
+    }
+    catch {
+        // Missing/disposed service, unpublished session, or a throwing getter —
+        // degrade to the historical source rather than failing the tool call.
+        return undefined;
+    }
+}
+/**
+ * The effective working directory of a session: the host's committed
+ * directory when available, else the immutable session header cwd.
+ *
+ * Returns `undefined` only when neither source yields a usable path.
+ */
+export function effectiveSessionCwd(session, headerCwd) {
+    const fromService = serviceWorkingDirectory(session);
+    if (fromService !== undefined)
+        return fromService;
+    return typeof headerCwd === 'string' && headerCwd.length > 0 ? headerCwd : undefined;
+}
+/**
+ * Extract the effective cwd from a tool execution (`exec.agent.session`),
+ * reading every property defensively: a hostile/proxied exec must degrade to
+ * the fallback path, never throw out of an approval or capture hook.
+ */
+export function sessionCwdOf(exec) {
+    try {
+        const agent = exec?.agent;
+        const session = agent?.session;
+        const headerCwd = typeof agent?.session?.header?.cwd === 'string' ? agent.session.header.cwd : undefined;
+        return effectiveSessionCwd(session, headerCwd);
+    }
+    catch {
+        return undefined;
+    }
+}