@aiwg/cli 2026.10.5 → 2026.10.7

package/dist/src/sessions/output-registration.js

@@ -2,34 +2,35 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameS
 import { createHash, randomUUID } from 'node:crypto';
 import { dirname, relative, resolve, sep } from 'node:path';
 import { z } from 'zod';
+import { integer } from '../schema/zod-validation.mjs';
 import { SessionContractError, sha256 } from './contracts.js';
 const DigestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/);
 const ReferenceSchema = z.string().min(1).max(512).refine(value => !/[\r\n\0]/.test(value), 'references must be single-line inert locators');
-export const OutputSourceReferenceSchema = z.object({
+export const OutputSourceReferenceSchema = z.strictObject({
     kind: z.enum(['file', 'url', 'note', 'session', 'artifact', 'context-pack']),
     ref: ReferenceSchema,
     digest: DigestSchema.nullable().default(null),
-    span: z.object({
-        start: z.number().int().nonnegative(),
-        end: z.number().int().positive(),
+    span: z.strictObject({
+        start: integer().nonnegative(),
+        end: integer().positive(),
         quoteDigest: DigestSchema,
-    }).strict().nullable().default(null),
-}).strict().superRefine((value, context) => {
+    }).nullable().default(null),
+}).superRefine((value, context) => {
     if (value.span && value.span.end <= value.span.start) {
         context.addIssue({ code: z.ZodIssueCode.custom, message: 'source span end must exceed start' });
     }
 });
-export const OutputRegistrationRequestSchema = z.object({
+export const OutputRegistrationRequestSchema = z.strictObject({
     outputPath: z.string().min(1),
     mediaType: z.string().min(1).max(128),
-    contextPack: z.object({
+    contextPack: z.strictObject({
         id: ReferenceSchema,
         digest: DigestSchema,
         sources: z.array(OutputSourceReferenceSchema).min(1).max(256),
-    }).strict(),
+    }),
     supersedes: z.array(ReferenceSchema).max(128).default([]),
     conflictsWith: z.array(ReferenceSchema).max(128).default([]),
-}).strict();
+});
 /**
  * Minimal incremental index sink. Each registration is independently atomic,
  * discoverable, and replay-safe; corpus-wide index builders can consume these

package/dist/src/sessions/workspace-discovery.js

@@ -466,13 +466,12 @@ async function rediscoverManifestIdentity(manifest) {
 }
 async function codexDiscoveryRoots(options) {
     const explicit = [...(options.codexRoots ?? []), ...(options.codexRoot ? [options.codexRoot] : [])];
-    if (explicit.length > 0)
-        return [...new Set(explicit.map((root) => resolve(root)))];
+    const roots = [...new Set(explicit.map((root) => resolve(root)))];
     // Shared stores require the same explicit provider-home authorization as the default root.
     if (!options.providerHome)
-        return [];
+        return roots;
     const codexHome = join(resolve(options.providerHome), '.codex');
-    const roots = [join(codexHome, 'sessions')];
+    roots.push(join(codexHome, 'sessions'));
     if (process.env.CODEX_HOME)
         roots.push(resolve(process.env.CODEX_HOME, 'sessions'));
     try {

package/dist/src/smiths/context-pipeline/aiwg-md.js

@@ -18,6 +18,7 @@ import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { projectControlPath } from '../../config/project-artifacts.js';
 import { buildClaudeHookBlock, CLAUDE_HOOK_START, CLAUDE_HOOK_END } from './claude-hook.js';
+import { dedupeProviderBootstrap } from './workspace-context.js';
 import { dominantLineEnding, withLineEnding } from './line-endings.js';
 import { buildParallelismSection, replaceOrAppendParallelismBlock } from './parallelism-section.js';
 import { buildContextFinalizationBlock, replaceOrAppendFinalizationBlock } from './finalization.js';
@@ -60,6 +61,7 @@ export async function buildAiwgMdContent(projectPath, stagedClaudeMdContent) {
         // Regenerate may mirror CLAUDE.md before its hook updater runs. Normalize
         // that managed block here too so legacy duplicate policy never reaches
         // AIWG.md, even on the first refresh. Operator content stays untouched.
+        claudeMdContent = dedupeProviderBootstrap(claudeMdContent);
         const start = claudeMdContent.indexOf(CLAUDE_HOOK_START);
         const end = claudeMdContent.indexOf(CLAUDE_HOOK_END, start);
         if (start >= 0 && end >= start) {
@@ -72,7 +74,22 @@ export async function buildAiwgMdContent(projectPath, stagedClaudeMdContent) {
         // context, so the directive becomes a self-reference when copied through.
         // Match the directive when it appears on its own line (possibly indented).
         const SELF_INCLUDE_PATTERN = /^\s*@AIWG\.md\s*$/;
-        const filtered = lines.filter((line) => !SELF_INCLUDE_PATTERN.test(line));
+        // #3451: CLAUDE.md already `@`-imports WORKSPACE.md; a second `@` path to
+        // the same file would load it twice, so AIWG.md refers to it in plain text.
+        const CONFIG_IMPORT_PATTERN = /^\s*@\S*aiwg\.config\s*$/;
+        const WORKSPACE_IMPORT_PATTERN = /^\s*@(?:\.\.\/)?WORKSPACE\.md\s*$/;
+        const filtered = lines
+            .filter((line) => !SELF_INCLUDE_PATTERN.test(line))
+            .map((line) => {
+            if (WORKSPACE_IMPORT_PATTERN.test(line)) {
+                return 'WORKSPACE.md is the canonical project context (loaded by CLAUDE.md; read it first if your harness did not).';
+            }
+            // Legacy CLAUDE.md files may still `@`-import the raw JSON config.
+            if (CONFIG_IMPORT_PATTERN.test(line)) {
+                return 'Project configuration: `.aiwg/aiwg.config` (not auto-loaded; run `aiwg config show --project` to view it).';
+            }
+            return line;
+        });
         const firstLine = filtered[0] ?? '';
         const rest = filtered.slice(1);
         // If the file already carries the signature elsewhere, don't double-insert.

package/dist/src/smiths/context-pipeline/claude-hook.js

@@ -21,9 +21,9 @@
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { buildProviderBootstrapBlock, PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END, } from './workspace-context.js';
+import { buildProviderBootstrapBlock, PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END, dedupeProviderBootstrap, } from './workspace-context.js';
 import { dominantLineEnding, withLineEnding } from './line-endings.js';
-import { assertSafeContextFile } from './context-file-safety.js';
+import { assertSafeContextFile, writeContextFileSync } from './context-file-safety.js';
 export const CLAUDE_HOOK_START = '<!-- AIWG:claude-md-hook:start -->';
 export const CLAUDE_HOOK_END = '<!-- AIWG:claude-md-hook:end -->';
 export function buildClaudeHookBlock(_policy = {}) {
@@ -31,7 +31,9 @@ export function buildClaudeHookBlock(_policy = {}) {
         CLAUDE_HOOK_START,
         '',
         buildProviderBootstrapBlock('claude'),
-        '@.aiwg/aiwg.config',
+        // Plain-text pointer, deliberately not an `@` import: the raw JSON config
+        // is several KB and would be pulled into every system prompt (#3451).
+        'Project configuration: `.aiwg/aiwg.config` (not auto-loaded; run `aiwg config show --project` to view it).',
         '',
         'Artifact destination authority: `aiwg show rule artifact-output-policy` (kernel).',
         '',
@@ -45,6 +47,30 @@ export function buildClaudeHookBlock(_policy = {}) {
         CLAUDE_HOOK_END,
     ].join('\n');
 }
+/** Keep the first managed hook block and drop any later complete copies. */
+function collapseExtraHookBlocks(content) {
+    const first = content.indexOf(CLAUDE_HOOK_START);
+    if (first === -1)
+        return content;
+    const firstEnd = content.indexOf(CLAUDE_HOOK_END, first);
+    if (firstEnd === -1)
+        return content;
+    const blockEnd = firstEnd + CLAUDE_HOOK_END.length;
+    let tail = content.slice(blockEnd);
+    const before = tail;
+    for (;;) {
+        const s = tail.indexOf(CLAUDE_HOOK_START);
+        if (s === -1)
+            break;
+        const e = tail.indexOf(CLAUDE_HOOK_END, s);
+        if (e === -1)
+            break;
+        tail = tail.slice(0, s) + tail.slice(e + CLAUDE_HOOK_END.length);
+    }
+    if (tail === before)
+        return content;
+    return content.slice(0, blockEnd) + tail.replace(/(?:\r?\n){3,}/g, '\n\n');
+}
 /**
  * Ensure CLAUDE.md at projectPath contains the AIWG-managed marker block
  * pointing at AIWG.md. Returns a result describing what was done.
@@ -66,12 +92,17 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
     catch (err) {
         if (err.code === 'ENOENT') {
             const minimal = `${block}\n`;
-            await fs.writeFile(claudeMdPath, minimal, 'utf8');
+            writeContextFileSync(claudeMdPath, minimal, 'utf8');
             result.action = 'created';
             return result;
         }
         throw err;
     }
+    // Repair duplicates left by earlier generations before locating markers, so
+    // regeneration converges on exactly one bootstrap (#3451).
+    const original = existing;
+    existing = collapseExtraHookBlocks(dedupeProviderBootstrap(existing));
+    const repaired = existing !== original;
     const lineEnding = dominantLineEnding(existing);
     block = withLineEnding(block, lineEnding);
     const startIdx = existing.indexOf(CLAUDE_HOOK_START);
@@ -90,7 +121,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
             const updated = existing.substring(0, bootstrapStartIdx)
                 + block
                 + existing.substring(bootstrapEndIdx);
-            await fs.writeFile(claudeMdPath, updated, 'utf8');
+            writeContextFileSync(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
             result.action = 'updated';
             return result;
         }
@@ -101,7 +132,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         // Ensure the file ends with a single newline before appending.
         const trimmed = existing.replace(/(?:\r?\n)+$/, lineEnding);
         const updated = `${trimmed}${lineEnding}${block}${lineEnding}`;
-        await fs.writeFile(claudeMdPath, updated, 'utf8');
+        writeContextFileSync(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
         result.action = 'inserted';
         return result;
     }
@@ -114,12 +145,12 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         // With --force, back up and append a fresh block.
         if (opts.detectExistingFiles !== false) {
             const backupPath = `${claudeMdPath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
-            await fs.writeFile(backupPath, existing, 'utf8');
+            writeContextFileSync(backupPath, existing, 'utf8');
             result.backupPath = backupPath;
         }
         const trimmed = existing.replace(/(?:\r?\n)+$/, lineEnding);
         const updated = `${trimmed}${lineEnding}${block}${lineEnding}`;
-        await fs.writeFile(claudeMdPath, updated, 'utf8');
+        writeContextFileSync(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
         result.action = 'inserted';
         return result;
     }
@@ -127,6 +158,11 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
     const blockEndOffset = endIdx + CLAUDE_HOOK_END.length;
     const currentBlock = existing.substring(startIdx, blockEndOffset);
     if (currentBlock === block) {
+        if (repaired) {
+            writeContextFileSync(claudeMdPath, existing, 'utf8');
+            result.action = 'updated';
+            return result;
+        }
         result.action = 'unchanged';
         return result;
     }
@@ -135,14 +171,14 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
     // the case where an operator made deliberate edits inside the block).
     if (opts.force) {
         const backupPath = `${claudeMdPath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
-        await fs.writeFile(backupPath, existing, 'utf8');
+        writeContextFileSync(backupPath, existing, 'utf8');
         result.backupPath = backupPath;
     }
     else {
         result.warnings.push(`CLAUDE.md AIWG hook block has been modified inside the markers; updating to canonical content. Operator content outside the block is preserved.`);
     }
     const updated = existing.substring(0, startIdx) + block + existing.substring(blockEndOffset);
-    await fs.writeFile(claudeMdPath, updated, 'utf8');
+    writeContextFileSync(claudeMdPath, dedupeProviderBootstrap(updated), 'utf8');
     result.action = 'updated';
     return result;
 }

package/dist/src/smiths/context-pipeline/context-file-safety.js

@@ -1,18 +1,339 @@
-import { lstat } from 'node:fs/promises';
-import { basename } from 'node:path';
-/** Never read or update a provider instruction file through a filesystem link. */
-export async function assertSafeContextFile(filePath) {
-    let stat;
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { trackTemporaryDirectory } from '../../utils/temporary-directory.js';
+const JOURNAL_ENV = 'AIWG_CONTEXT_WRITE_JOURNAL';
+export const CONTEXT_STAGE_ENV = 'AIWG_CONTEXT_STAGE_LOG';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const identity = (stat) => ({ dev: String(stat.dev), ino: String(stat.ino) });
+const sameIdentity = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const sameAncestors = (a, b) => a.length === b.length && a.every((identity, index) => sameIdentity(identity, b[index]));
+// Optional flags are absent on some supported hosts (notably Windows).
+function flags(...names) {
+    return names.reduce((value, name) => {
+        const flag = fs.constants[name];
+        return typeof flag === 'number' ? value | flag : value;
+    }, 0);
+}
+// Identity is dev/ino/size/mtime. A replacement that recycles the freed inode
+// number with the same size inside one coarse timestamp tick is
+// indistinguishable by metadata; the content hash still has to match deploy
+// output, so restoring over such a file loses nothing the deploy wrote.
+const version = (stat) => ({ ...identity(stat), size: String(stat.size), mtime: String(stat.mtimeNs) });
+const sameVersion = (a, b) => sameIdentity(a, b) && a.size === b.size && a.mtime === b.mtime;
+/** Probe child traversal, not just the descriptor link itself. /dev/fd on macOS
+ * can expose a descriptor without supporting directory-relative child opens. */
+function descriptorRoot(root) {
+    if (process.platform !== 'linux')
+        return null;
+    let fd;
+    try {
+        fd = fs.openSync(root, flags('O_RDONLY', 'O_DIRECTORY', 'O_NOFOLLOW'));
+        const child = `/proc/self/fd/${fd}/.`;
+        return sameIdentity(identity(fs.statSync(child, { bigint: true })), identity(fs.fstatSync(fd, { bigint: true }))) ? '/proc/self/fd' : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/** Pin directories on Linux when descriptor-relative child traversal works.
+ * Elsewhere lstat every ancestor and recheck paths around each mutation. The
+ * portable fallback has a residual check-then-write race: only descriptor
+ * anchoring closes the interval between the last path check and the write. */
+function withParent(file, create, action) {
+    const absolute = path.resolve(file);
+    const root = path.parse(absolute).root;
+    const parts = path.relative(root, absolute).split(path.sep);
+    const descriptors = [];
+    const identities = [];
+    const fdRoot = descriptorRoot(root);
+    try {
+        let directory = root;
+        for (const part of ['', ...parts.slice(0, -1)]) {
+            const next = part ? path.join(directory, part) : directory;
+            // Drive roots already exist; mkdir on a Windows drive root can be EPERM.
+            if (create && part) {
+                try {
+                    fs.mkdirSync(next);
+                }
+                catch (error) {
+                    if (error.code !== 'EEXIST')
+                        throw error;
+                }
+            }
+            const checked = fs.lstatSync(next, { bigint: true });
+            if (checked.isSymbolicLink() || !checked.isDirectory())
+                throw new Error('Context ancestor changed');
+            identities.push(identity(checked));
+            directory = next;
+            if (fdRoot) {
+                const fd = fs.openSync(next, flags('O_RDONLY', 'O_DIRECTORY', 'O_NOFOLLOW'));
+                descriptors.push(fd);
+                if (!sameIdentity(identity(fs.fstatSync(fd, { bigint: true })), identity(checked)))
+                    throw new Error('Context ancestor changed');
+                directory = `${fdRoot}/${fd}`;
+            }
+        }
+        const verify = () => {
+            let current = root;
+            for (let i = 0; i < identities.length; i++) {
+                if (i)
+                    current = path.join(current, parts[i - 1]);
+                const stat = fs.lstatSync(current, { bigint: true });
+                if (!stat.isDirectory() || stat.isSymbolicLink() || !sameIdentity(identity(stat), identities[i]))
+                    throw new Error('Context ancestor changed');
+            }
+        };
+        verify();
+        return action(path.join(directory, parts[parts.length - 1]), identities, verify);
+    }
+    finally {
+        for (const fd of descriptors.reverse())
+            fs.closeSync(fd);
+    }
+}
+function checkedVersion(stat) {
+    if (stat.isSymbolicLink() || !stat.isFile() || !(stat.mode & 292n) || !(stat.mode & 146n) || stat.nlink !== 1n)
+        throw new Error('Refusing unreadable, unwritable, linked or non-file context target');
+    return version(stat);
+}
+function verifyTarget(file, expected) {
+    if (!sameVersion(checkedVersion(fs.lstatSync(file, { bigint: true })), expected))
+        throw new Error('Context identity changed');
+}
+function state(fd) {
+    const stat = fs.fstatSync(fd, { bigint: true });
+    const before = checkedVersion(stat);
+    const bytes = Buffer.alloc(Number(stat.size));
+    let offset = 0;
+    while (offset < bytes.length) {
+        const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+        if (!count)
+            throw new Error('Context changed while reading');
+        offset += count;
+    }
+    if (!sameVersion(checkedVersion(fs.fstatSync(fd, { bigint: true })), before))
+        throw new Error('Context changed while reading');
+    return { ...before, mode: Number(stat.mode & 4095n), bytes: bytes.toString('base64'), hash: digest(bytes) };
+}
+function readState(file) {
+    let checked;
     try {
-        stat = await lstat(filePath);
+        checked = checkedVersion(fs.lstatSync(file, { bigint: true }));
     }
     catch (error) {
         if (error.code === 'ENOENT')
-            return;
+            return null;
         throw error;
     }
-    if (stat.isSymbolicLink() || !stat.isFile()) {
-        throw new Error(`Refusing unsafe ${basename(filePath)} target: ${filePath}`);
+    const fd = fs.openSync(file, flags('O_RDONLY', 'O_NOFOLLOW', 'O_NONBLOCK'));
+    try {
+        const result = state(fd);
+        if (!sameVersion(result, checked))
+            throw new Error('Context identity changed');
+        verifyTarget(file, result);
+        return result;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function matches(a, b) {
+    return sameVersion(a, b) && a.hash === b.hash && a.mode === b.mode;
+}
+function entries() {
+    const file = process.env[JOURNAL_ENV];
+    return file ? fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map(line => JSON.parse(line)) : [];
+}
+/** Every context writer uses this boundary, including staged provider writers.
+ * Record immediately after the mutation, before returning to a fallible step. */
+export function writeContextFileSync(file, content, _encoding) {
+    const absolute = path.resolve(file);
+    const stageLog = process.env[CONTEXT_STAGE_ENV];
+    const priorEntries = stageLog ? [] : entries();
+    withParent(absolute, true, (anchored, ancestors, verify) => {
+        const prior = readState(anchored);
+        const previous = priorEntries.reverse().find(entry => entry.path === absolute);
+        if (previous && (!prior || !matches(prior, previous.result) || !sameAncestors(ancestors, previous.ancestors)))
+            throw new Error(`Context changed during deployment: ${absolute}`);
+        verify();
+        const fd = fs.openSync(anchored, flags('O_RDWR', 'O_NOFOLLOW', 'O_NONBLOCK', ...(prior ? [] : ['O_CREAT', 'O_EXCL'])), prior?.mode ?? 0o666);
+        try {
+            verify();
+            if (prior && !matches(state(fd), prior))
+                throw new Error(`Context identity changed: ${absolute}`);
+            verify();
+            verifyTarget(anchored, prior ?? checkedVersion(fs.fstatSync(fd, { bigint: true })));
+            const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
+            const opened = fs.fstatSync(fd, { bigint: true });
+            const priorBytes = prior ? Buffer.from(prior.bytes, 'base64') : Buffer.alloc(0);
+            const expected = Buffer.alloc(Math.max(buffer.length, priorBytes.length));
+            priorBytes.copy(expected);
+            let length = priorBytes.length;
+            try {
+                let offset = 0;
+                while (offset < buffer.length) {
+                    const count = fs.writeSync(fd, buffer, offset, buffer.length - offset, offset);
+                    if (!count)
+                        throw new Error('Context write made no progress');
+                    buffer.copy(expected, offset, offset, offset + count);
+                    offset += count;
+                    length = Math.max(length, offset);
+                }
+                fs.ftruncateSync(fd, buffer.length);
+                length = buffer.length;
+            }
+            finally {
+                // Hash the bytes this writer produced, never a later read that could
+                // accidentally claim an operator's concurrent edit as deploy-owned.
+                const completed = fs.fstatSync(fd, { bigint: true });
+                const result = { ...version(completed), ...identity(opened), size: String(length), mode: Number(opened.mode & 4095n), hash: digest(expected.subarray(0, length)) };
+                if (stageLog)
+                    fs.appendFileSync(stageLog, `${JSON.stringify(absolute)}\n`);
+                else if (process.env[JOURNAL_ENV])
+                    fs.appendFileSync(process.env[JOURNAL_ENV], `${JSON.stringify({ path: absolute, prior, result, ancestors })}\n`);
+                verify();
+                verifyTarget(anchored, result);
+                if (!matches(state(fd), result))
+                    throw new Error(`Context changed during write: ${absolute}`);
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    });
+}
+/** Verify before reading provider startup files as well as at the write boundary. */
+export async function assertSafeContextFile(file) {
+    try {
+        withParent(file, false, anchored => { readState(anchored); });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw new Error(`Refusing unsafe ${path.basename(file)} target: ${file}`, { cause: error });
+    }
+}
+/** Owned by the outer use invocation; the private log also crosses subprocesses. */
+export class ContextWriteJournal {
+    directory = fs.mkdtempSync(path.join(tmpdir(), 'aiwg-context-writes-'));
+    removeDirectory = trackTemporaryDirectory(this.directory);
+    previous = process.env[JOURNAL_ENV];
+    constructor() {
+        fs.chmodSync(this.directory, 0o700);
+        const file = path.join(this.directory, 'writes.jsonl');
+        fs.writeFileSync(file, '', { mode: 0o600, flag: 'wx' });
+        process.env[JOURNAL_ENV] = file;
+    }
+    rollback() {
+        const result = { restored: [], conflicts: [] };
+        const blocked = new Set();
+        // Restoring a later pass changes mtime. Carry that verified version back
+        // through earlier entries rather than treating our own restore as an edit.
+        const restoredVersions = new Map();
+        for (const entry of entries().reverse()) {
+            if (blocked.has(entry.path))
+                continue;
+            try {
+                withParent(entry.path, false, (anchored, ancestors, verify) => {
+                    if (!sameAncestors(ancestors, entry.ancestors))
+                        throw new Error('Context ancestor identity changed');
+                    const checked = checkedVersion(fs.lstatSync(anchored, { bigint: true }));
+                    const fd = fs.openSync(anchored, flags('O_RDWR', 'O_NOFOLLOW', 'O_NONBLOCK'));
+                    try {
+                        verify();
+                        const current = state(fd);
+                        if (!sameVersion(current, checked))
+                            throw new Error('Context identity changed');
+                        if (!matches(current, restoredVersions.get(entry.path) ?? entry.result))
+                            throw new Error('Context changed since deployment wrote it');
+                        verify();
+                        verifyTarget(anchored, current);
+                        if (!matches(state(fd), current))
+                            throw new Error('Context changed before restore');
+                        if (entry.prior) {
+                            const bytes = Buffer.from(entry.prior.bytes, 'base64');
+                            let offset = 0;
+                            while (offset < bytes.length) {
+                                const count = fs.writeSync(fd, bytes, offset, bytes.length - offset, offset);
+                                if (!count)
+                                    throw new Error('Context restore made no progress');
+                                offset += count;
+                            }
+                            fs.ftruncateSync(fd, bytes.length);
+                            fs.fchmodSync(fd, entry.prior.mode);
+                            verify();
+                            const restored = state(fd);
+                            if (!sameIdentity(restored, current) || restored.hash !== entry.prior.hash || restored.mode !== entry.prior.mode)
+                                throw new Error('Context changed during restore');
+                            verifyTarget(anchored, restored);
+                            restoredVersions.set(entry.path, restored);
+                        }
+                        else {
+                            // Quarantine before deleting: a final-component swap between the
+                            // identity check and rename must be kept, never silently unlinked.
+                            const quarantine = fs.mkdtempSync(path.join(path.dirname(anchored), '.aiwg-context-rollback-'));
+                            const retained = path.join(quarantine, 'context');
+                            try {
+                                fs.renameSync(anchored, retained);
+                                try {
+                                    const moved = readState(retained);
+                                    if (!moved || !matches(moved, current))
+                                        throw new Error('Context changed during removal');
+                                    verify();
+                                    fs.unlinkSync(retained);
+                                }
+                                catch (error) {
+                                    try {
+                                        fs.linkSync(retained, anchored);
+                                        fs.unlinkSync(retained);
+                                    }
+                                    catch {
+                                        const saved = path.join(path.dirname(entry.path), path.basename(quarantine), 'context');
+                                        throw new Error(`Context changed during removal; preserved at ${saved}`, { cause: error });
+                                    }
+                                    throw error;
+                                }
+                                verify();
+                                if (fs.existsSync(anchored))
+                                    throw new Error('Context path replaced during rollback');
+                            }
+                            finally {
+                                try {
+                                    fs.rmdirSync(quarantine);
+                                }
+                                catch (error) {
+                                    if (error.code !== 'ENOTEMPTY')
+                                        throw error;
+                                }
+                            }
+                        }
+                    }
+                    finally {
+                        fs.closeSync(fd);
+                    }
+                });
+                if (!result.restored.includes(entry.path))
+                    result.restored.push(entry.path);
+            }
+            catch (error) {
+                blocked.add(entry.path);
+                result.conflicts.push({ path: entry.path, reason: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        return result;
+    }
+    dispose() {
+        if (this.previous === undefined)
+            delete process.env[JOURNAL_ENV];
+        else
+            process.env[JOURNAL_ENV] = this.previous;
+        this.removeDirectory();
     }
 }
 //# sourceMappingURL=context-file-safety.js.map

package/dist/src/smiths/context-pipeline/finalization.js

@@ -1,3 +1,4 @@
+import { writeContextFileSync } from './context-file-safety.js';
 /**
  * Context-finalization pass for generated provider context files.
  *
@@ -132,13 +133,13 @@ export async function writeNormalizedAiwgMd(projectPath) {
     const content = await buildNormalizedAiwgMd(projectPath, existing);
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
     const normalizedContent = content.endsWith('\n') ? content : `${content}\n`;
-    await fs.writeFile(targetPath, normalizedContent, 'utf8');
+    writeContextFileSync(targetPath, normalizedContent, 'utf8');
     const artifactRoot = resolveProjectAiwgDir(projectPath);
     const artifactPath = projectAiwgPath(projectPath, 'AIWG.md');
     if (artifactPath !== targetPath) {
         try {
             await fs.access(artifactRoot);
-            await fs.writeFile(artifactPath, normalizedContent, 'utf8');
+            writeContextFileSync(artifactPath, normalizedContent, 'utf8');
         }
         catch (error) {
             if (error.code !== 'ENOENT')