@mono-agent/agent-app 0.6.2 → 0.9.0

package/dist/init.js

@@ -1,22 +1,78 @@
-import { mkdir, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, realpath, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { parseEnv } from "node:util";
 import { writeMonoAgentConfigJson } from "@mono-agent/config";
-import { composeWizardPlan, defaultAnswers } from "./wizard/answers.js";
+import { composeWizardPlan, defaultAnswers, humanizeAgentName } from "./wizard/answers.js";
+import { initializeFirstRunManagedMemory, preflightFirstRunManagedMemory, } from "./first-run-managed-memory.js";
+import { assertManagedProjectSkillInitSafe } from "./project-skills.js";
+export class SecretEnvPersistenceRefusedError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SecretEnvPersistenceRefusedError";
+        this.code = code;
+    }
+}
+export class SecretEnvConcurrentModificationError extends Error {
+    ownerPid;
+    ownerCreatedAt;
+    recoveryPath;
+    constructor(path, owner, recoveryPath) {
+        super(recoveryPath !== undefined
+            ? `Secret persistence detected a concurrent or interrupted change to ${path}; bytes were retained at ${recoveryPath}. Inspect both paths before retrying.`
+            : owner === undefined
+                ? `Refusing to replace ${path} because it changed during secret persistence.`
+                : `Secret persistence for ${path} is already held by live PID ${owner.pid} since ${owner.createdAt}; retry after that process exits.`);
+        this.name = "SecretEnvConcurrentModificationError";
+        this.ownerPid = owner?.pid;
+        this.ownerCreatedAt = owner?.createdAt;
+        this.recoveryPath = recoveryPath;
+    }
+}
 const KNOWLEDGE_FILE_CANDIDATES = ["AGENTS.md", "CLAUDE.md", "README.md", "SOUL.md"];
 /**
  * Non-destructively scaffolds a config-first mono-agent folder: a
  * `mono-agent.config.json` composed from the wizard answers (default scaffold when
  * none are supplied), an `IDENTITY.md` seeded from any knowledge files already in
  * the folder, the `.mono-agent/` working directories, and — when the composed plan
- * carries them — a `.env.example` and any capability files. Existing files are
- * never overwritten. With `dryRun`, nothing is written and `created` reports what
- * would have been.
+ * carries them — a `.env.example` and any capability files. Existing
+ * scaffold/config files are never overwritten; reviewed secret persistence is
+ * the deliberate exception that can transactionally replace `.env` and update
+ * `.gitignore`. With `dryRun`, nothing is written and `created` reports what would
+ * have been.
  */
 export async function initMonoAgentFolder(options = {}) {
     const dir = resolve(options.dir ?? process.cwd());
     const dryRun = options.dryRun === true;
+    const answers = options.answers ?? defaultAnswers();
     const created = [];
     const skipped = [];
+    const changes = [];
+    await assertManagedProjectSkillInitSafe(dir);
+    const ctx = {
+        dirBasename: basename(dir),
+        skillsRootExists: await pathExists(join(dir, "skills")),
+    };
+    const plan = composeWizardPlan(answers, ctx);
+    const configPath = join(dir, "mono-agent.config.json");
+    await assertSafeScaffoldTarget(configPath, "config");
+    const configAlreadyExists = await pathExists(configPath);
+    if (options.requireConfigCreation === true && configAlreadyExists) {
+        const error = new Error(`Refusing guided init because ${configPath} already exists.`);
+        error.code = "EEXIST";
+        throw error;
+    }
+    if (!configAlreadyExists) {
+        await preflightFirstRunManagedMemory({
+            agentRoot: dir,
+            plan,
+            ...(options.env === undefined ? {} : { env: options.env }),
+        });
+    }
     const knowledgeFiles = [];
     for (const candidate of KNOWLEDGE_FILE_CANDIDATES) {
         if (await pathExists(join(dir, candidate))) {
@@ -26,43 +82,1110 @@ export async function initMonoAgentFolder(options = {}) {
     async function planFile(path, write) {
         if (await pathExists(path)) {
             skipped.push(path);
-            return;
+            changes.push({ path, kind: "unchanged" });
+            return false;
         }
         if (!dryRun) {
             await write();
         }
         created.push(path);
+        changes.push({ path, kind: dryRun ? "planned-create" : "created" });
+        return true;
     }
     const identityPath = join(dir, "IDENTITY.md");
-    await planFile(identityPath, () => writeFile(identityPath, identityTemplate(dir, knowledgeFiles), { flag: "wx" }));
+    await assertSafeScaffoldTarget(identityPath, "identity");
+    const identityCreated = await planFile(identityPath, () => writeFile(identityPath, identityTemplate(dir, answers.name?.trim() || humanizeAgentName(basename(dir)), answers.purpose?.trim() || "Help the operator work effectively in this folder.", knowledgeFiles), { flag: "wx" }));
     for (const subdir of [join(dir, ".mono-agent", "artifacts"), join(dir, ".mono-agent", "workspace")]) {
-        await planFile(subdir, () => mkdir(subdir, { recursive: true }));
+        await assertSafeScaffoldTarget(subdir, "working directory");
+        await ensureSafeScaffoldParent(dir, subdir, !dryRun);
+        await planFile(subdir, async () => {
+            await ensureSafeScaffoldParent(dir, subdir, true);
+            await createSafeScaffoldDirectory(subdir);
+        });
+    }
+    let configCreatedByThisInit = false;
+    let configCreatedIdentity;
+    if (options.requireConfigCreation === true) {
+        if (dryRun) {
+            if (await pathExists(configPath)) {
+                throw new Error(`Refusing guided init because ${configPath} already exists.`);
+            }
+        }
+        else {
+            await createMonoAgentConfigExclusively(configPath, plan.configJson);
+        }
+        created.push(configPath);
+        changes.push({ path: configPath, kind: dryRun ? "planned-create" : "created" });
+        configCreatedByThisInit = !dryRun;
+    }
+    else {
+        const configPlanned = await planFile(configPath, () => writeMonoAgentConfigJson({ path: configPath, patch: plan.configJson }));
+        configCreatedByThisInit = !dryRun && configPlanned;
+    }
+    if (configCreatedByThisInit) {
+        const configStat = await lstat(configPath);
+        configCreatedIdentity = { dev: configStat.dev, ino: configStat.ino };
     }
-    const ctx = {
-        dirBasename: basename(dir),
-        skillsRootExists: await pathExists(join(dir, "skills")),
-    };
-    const answers = options.answers ?? defaultAnswers();
-    const plan = composeWizardPlan(answers, ctx);
-    const configPath = join(dir, "mono-agent.config.json");
-    await planFile(configPath, () => writeMonoAgentConfigJson({ path: configPath, patch: plan.configJson }));
     const envExample = plan.envExample;
     if (typeof envExample === "string" && envExample.length > 0) {
         const envExamplePath = join(dir, ".env.example");
+        await assertSafeScaffoldTarget(envExamplePath, "environment example");
         await planFile(envExamplePath, () => writeFile(envExamplePath, envExample, { flag: "wx" }));
     }
+    const requestedSecrets = options.secretValues !== undefined && Object.keys(options.secretValues).length > 0;
+    const requestedEnvSecurity = requestedSecrets || options.secureExistingDotenv === true;
+    let secretPersistence = { status: "not-requested", changed: false };
+    if (requestedEnvSecurity) {
+        const envPath = join(dir, ".env");
+        try {
+            const result = await mergeSecretEnvFile(envPath, options.secretValues ?? {}, {
+                dryRun,
+                secureExistingFile: options.secureExistingDotenv === true,
+            });
+            changes.push(...result.changes);
+            for (const change of result.changes) {
+                if (change.kind === "created" || change.kind === "planned-create")
+                    created.push(change.path);
+                if (change.kind === "unchanged")
+                    skipped.push(change.path);
+            }
+            secretPersistence = {
+                status: dryRun ? "planned" : "persisted",
+                path: envPath,
+                changed: result.valuesChanged > 0,
+            };
+        }
+        catch (error) {
+            if (!(error instanceof SecretEnvPersistenceRefusedError))
+                throw error;
+            secretPersistence = {
+                status: "refused",
+                path: envPath,
+                changed: false,
+                reason: error.code,
+                detail: error.message,
+            };
+        }
+    }
     for (const file of plan.files) {
-        const filePath = join(dir, file.path);
+        const filePath = resolve(dir, file.path);
+        await ensureSafeScaffoldParent(dir, filePath, !dryRun);
+        await assertSafeScaffoldTarget(filePath, `generated capability file ${file.path}`);
         await planFile(filePath, async () => {
-            await mkdir(dirname(filePath), { recursive: true });
+            await ensureSafeScaffoldParent(dir, filePath, true);
             await writeFile(filePath, file.contents, { flag: "wx" });
         });
     }
-    return { dir, configPath, identityPath, created, skipped, knowledgeFiles, dryRun, plan };
+    if (configCreatedByThisInit) {
+        try {
+            const initializedMemory = await initializeFirstRunManagedMemory({
+                agentRoot: dir,
+                plan,
+                ...(options.env === undefined ? {} : { env: options.env }),
+                ...(options.firstRunManagedMemoryHooks === undefined
+                    ? {}
+                    : { hooks: options.firstRunManagedMemoryHooks }),
+            });
+            if (initializedMemory.initialized && initializedMemory.root !== undefined) {
+                created.push(initializedMemory.root);
+                changes.push({ path: initializedMemory.root, kind: "created" });
+            }
+        }
+        catch (error) {
+            if (configCreatedIdentity !== undefined) {
+                await removeCreatedConfigIfUnchanged(configPath, configCreatedIdentity, `${JSON.stringify(plan.configJson, null, 2)}\n`);
+            }
+            throw error;
+        }
+    }
+    return {
+        dir,
+        configPath,
+        identityPath,
+        identityRole: {
+            path: identityPath,
+            section: "## Role",
+            status: identityCreated ? (dryRun ? "planned-create" : "created") : "preserved",
+        },
+        created,
+        skipped,
+        knowledgeFiles,
+        dryRun,
+        secretsPersisted: !dryRun && secretPersistence.status === "persisted" && secretPersistence.changed,
+        changes,
+        secretPersistence,
+        plan,
+    };
+}
+/**
+ * Securely merge required secrets into `.env` without replacing non-empty
+ * operator values. The destination and its git-ignore guard are preflighted,
+ * then each changed file is committed through an exclusive same-directory
+ * temporary file. The `.env` commit is always mode 0600 on supported systems.
+ */
+export async function mergeSecretEnvFile(path, secretValues, options = {}) {
+    const secretEntries = Object.entries(secretValues);
+    if (secretEntries.length === 0 && options.secureExistingFile !== true) {
+        return { changes: [], valuesChanged: 0 };
+    }
+    const platform = options.platform ?? process.platform;
+    const ownerOnlyPermissionsSupported = options.ownerOnlyPermissionsSupported ?? platform !== "win32";
+    if (!ownerOnlyPermissionsSupported) {
+        throw new SecretEnvPersistenceRefusedError("owner-only-permissions-unsupported", "Automatic secret persistence requires verifiable owner-only file permissions.");
+    }
+    const renderedValues = new Map();
+    for (const [name, value] of secretEntries) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name)) {
+            throw new SecretEnvPersistenceRefusedError("invalid-secret-name", `Automatic secret persistence refused an invalid environment variable name: ${name}.`);
+        }
+        renderedValues.set(name, renderDotenvValue(name, value));
+    }
+    const target = await resolveSafeSecretEnvTarget(path);
+    // A dry run has no commit to serialize and must remain write-free. Real
+    // persistence holds one same-directory lock across both snapshots, the git
+    // safety check, the ignore-file commit, and the env-file commit. Without this
+    // boundary two writers can read the same old .env, both pass the optimistic
+    // comparison, then rename over one another and silently lose one update.
+    return options.dryRun === true
+        ? await mergeSecretEnvFileLocked(target.path, path, renderedValues, target.ownerUid, options)
+        : await withSecretEnvFileLock(target.path, target.ownerUid, () => mergeSecretEnvFileLocked(target.path, path, renderedValues, target.ownerUid, options));
+}
+async function mergeSecretEnvFileLocked(path, reportedPath, renderedValues, ownerUid, options) {
+    const envSnapshot = await readSafeFile(path, "unsafe-env-path", "malformed-env", ownerUid, [1], reportedPath);
+    if (await isGitTracked(path)) {
+        throw new SecretEnvPersistenceRefusedError("tracked-env", `Automatic secret persistence refused because ${path} is tracked by git.`);
+    }
+    const existingEnv = snapshotText(envSnapshot);
+    const merged = mergeDotenvContents(existingEnv, renderedValues);
+    const envContents = Buffer.from(merged.contents, "utf8");
+    const envNeedsWrite = !envSnapshot.exists || !envSnapshot.contents.equals(envContents) || fileMode(envSnapshot) !== 0o600;
+    const gitIgnorePath = join(dirname(path), ".gitignore");
+    const reportedGitIgnorePath = join(dirname(reportedPath), ".gitignore");
+    const gitIgnoreSnapshot = await readSafeFile(gitIgnorePath, "unsafe-gitignore-path", "malformed-gitignore", ownerUid, [1], reportedGitIgnorePath);
+    const gitIgnoreContents = Buffer.from(ensureExactEnvIgnore(snapshotText(gitIgnoreSnapshot)), "utf8");
+    const gitIgnoreMode = gitIgnoreSnapshot.exists
+        ? (fileMode(gitIgnoreSnapshot) || 0o644) & ~0o022
+        : 0o644;
+    const gitIgnoreNeedsWrite = !gitIgnoreSnapshot.exists ||
+        !gitIgnoreSnapshot.contents.equals(gitIgnoreContents) ||
+        fileMode(gitIgnoreSnapshot) !== gitIgnoreMode;
+    const changes = [
+        changeFor(reportedGitIgnorePath, gitIgnoreSnapshot.exists, gitIgnoreNeedsWrite, options.dryRun === true),
+        { ...changeFor(reportedPath, envSnapshot.exists, envNeedsWrite, options.dryRun === true), sensitive: true },
+    ];
+    if (options.dryRun === true) {
+        return { changes, valuesChanged: merged.valuesChanged };
+    }
+    if (gitIgnoreNeedsWrite) {
+        await atomicReplaceFile({
+            path: gitIgnorePath,
+            reportedPath: reportedGitIgnorePath,
+            contents: gitIgnoreContents,
+            expected: gitIgnoreSnapshot,
+            ownerUid,
+            mode: gitIgnoreMode,
+            beforeCommit: options.beforeCommit,
+            beforePromotion: options.beforePromotion,
+            beforeInstallLink: options.beforeInstallLink,
+            afterInstallLink: options.afterInstallLink,
+        });
+    }
+    const committedGitIgnoreSnapshot = gitIgnoreNeedsWrite
+        ? await readSafeFile(gitIgnorePath, "unsafe-gitignore-path", "malformed-gitignore", ownerUid, [1], reportedGitIgnorePath)
+        : gitIgnoreSnapshot;
+    if (!committedGitIgnoreSnapshot.exists ||
+        !committedGitIgnoreSnapshot.contents.equals(gitIgnoreContents)) {
+        throw new SecretEnvConcurrentModificationError(gitIgnorePath);
+    }
+    if (envNeedsWrite) {
+        await atomicReplaceFile({
+            path,
+            reportedPath,
+            contents: envContents,
+            expected: envSnapshot,
+            ownerUid,
+            mode: 0o600,
+            verifyOwnerOnly: true,
+            beforeCommit: options.beforeCommit,
+            beforeRename: async () => {
+                if (await isGitTracked(path)) {
+                    throw new SecretEnvPersistenceRefusedError("tracked-env", `Automatic secret persistence refused because ${path} became tracked by git before commit.`);
+                }
+                await assertSnapshotUnchanged(gitIgnorePath, reportedGitIgnorePath, committedGitIgnoreSnapshot, ownerUid);
+            },
+            beforePromotion: options.beforePromotion,
+            beforeInstallLink: options.beforeInstallLink,
+            afterInstallLink: options.afterInstallLink,
+        });
+    }
+    return { changes, valuesChanged: merged.valuesChanged };
+}
+async function withSecretEnvFileLock(path, ownerUid, task) {
+    const lockPath = await secretEnvLockPathForCanonical(path, ownerUid);
+    const owner = {
+        version: 1,
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+        ownerUid,
+        token: randomUUID(),
+    };
+    const lock = await acquireSecretEnvLock(path, lockPath, owner);
+    try {
+        return await task();
+    }
+    finally {
+        try {
+            await lock.handle.close();
+        }
+        finally {
+            await releaseSecretEnvLock(lockPath, lock);
+        }
+    }
+}
+const MAX_SECRET_ENV_LOCK_BYTES = 4096;
+const MAX_SECRET_ENV_LOCK_ACQUIRE_ATTEMPTS = 4;
+async function acquireSecretEnvLock(envPath, lockPath, owner) {
+    for (let attempt = 0; attempt < MAX_SECRET_ENV_LOCK_ACQUIRE_ATTEMPTS; attempt += 1) {
+        let handle;
+        try {
+            handle = await open(lockPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EEXIST" && code !== "ELOOP")
+                throw error;
+            let existing;
+            try {
+                existing = await readSecretEnvLockSnapshot(lockPath, owner.ownerUid);
+            }
+            catch (readError) {
+                // O_EXCL publishes the directory entry just before its owner record is
+                // written. Give that tiny creation window a bounded retry so a real
+                // concurrent owner is reported as live instead of as malformed.
+                if (readError instanceof SecretEnvPersistenceRefusedError &&
+                    readError.code === "unsafe-lock-path" &&
+                    attempt + 1 < MAX_SECRET_ENV_LOCK_ACQUIRE_ATTEMPTS) {
+                    await new Promise((resolveRetry) => setTimeout(resolveRetry, 10));
+                    continue;
+                }
+                throw readError;
+            }
+            if (existing === undefined)
+                continue;
+            const ownerState = secretEnvLockOwnerState(existing.owner.pid);
+            if (ownerState === "live") {
+                throw new SecretEnvConcurrentModificationError(envPath, existing.owner);
+            }
+            if (ownerState === "unknown") {
+                throw unsafeSecretEnvLockError(lockPath, `the owner process state for PID ${existing.owner.pid} could not be verified`);
+            }
+            throw unsafeSecretEnvLockError(lockPath, `the recorded owner PID ${existing.owner.pid} is no longer running`);
+        }
+        const contents = Buffer.from(`${JSON.stringify(owner)}\n`, "utf8");
+        let identity;
+        try {
+            const initialStat = await handle.stat();
+            identity = { dev: initialStat.dev, ino: initialStat.ino };
+            assertSecretEnvLockFileStat(lockPath, initialStat, owner.ownerUid);
+            await handle.writeFile(contents);
+            await handle.sync();
+            const writtenStat = await handle.stat();
+            assertSecretEnvLockFileStat(lockPath, writtenStat, owner.ownerUid);
+            if (writtenStat.dev !== initialStat.dev ||
+                writtenStat.ino !== initialStat.ino ||
+                writtenStat.size !== contents.length) {
+                throw unsafeSecretEnvLockError(lockPath, "the durable owner record changed while it was being created");
+            }
+            await syncDirectoryBestEffort(dirname(lockPath));
+            return {
+                handle,
+                dev: writtenStat.dev,
+                ino: writtenStat.ino,
+                contents,
+                owner,
+            };
+        }
+        catch (error) {
+            try {
+                await handle.close();
+            }
+            finally {
+                if (identity !== undefined) {
+                    await removeSecretEnvLockWithIdentity(lockPath, identity);
+                }
+            }
+            throw error;
+        }
+    }
+    throw new SecretEnvConcurrentModificationError(envPath);
+}
+function currentProcessUid(lockPath) {
+    if (typeof process.getuid !== "function") {
+        throw unsafeSecretEnvLockError(lockPath, "the current operating-system user id is unavailable");
+    }
+    return process.getuid();
+}
+function assertSecretEnvLockFileStat(lockPath, lockStat, ownerUid) {
+    if (!lockStat.isFile() ||
+        lockStat.uid !== ownerUid ||
+        (lockStat.mode & 0o777) !== 0o600 ||
+        lockStat.nlink !== 1) {
+        throw unsafeSecretEnvLockError(lockPath, "it is not a same-user, owner-only regular file with one link");
+    }
+}
+async function readSecretEnvLockSnapshot(lockPath, ownerUid) {
+    let pathStat;
+    try {
+        pathStat = await lstat(lockPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (pathStat.isSymbolicLink() ||
+        !pathStat.isFile() ||
+        pathStat.uid !== ownerUid ||
+        (pathStat.mode & 0o777) !== 0o600 ||
+        pathStat.nlink !== 1) {
+        throw unsafeSecretEnvLockError(lockPath, "same-user ownership and owner-only regular-file identity could not be proven");
+    }
+    if (pathStat.size <= 0 || pathStat.size > MAX_SECRET_ENV_LOCK_BYTES) {
+        throw unsafeSecretEnvLockError(lockPath, "the durable owner record has an invalid size");
+    }
+    let handle;
+    try {
+        handle = await open(lockPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const handleStat = await handle.stat();
+        assertSecretEnvLockFileStat(lockPath, handleStat, ownerUid);
+        if (handleStat.dev !== pathStat.dev || handleStat.ino !== pathStat.ino)
+            return undefined;
+        const contents = await handle.readFile();
+        if (contents.length !== handleStat.size)
+            return undefined;
+        const owner = parseSecretEnvLockOwner(lockPath, contents, ownerUid);
+        return { dev: handleStat.dev, ino: handleStat.ino, contents, owner };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        if (error.code === "ELOOP") {
+            throw unsafeSecretEnvLockError(lockPath, "the lock path became a symbolic link");
+        }
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function parseSecretEnvLockOwner(lockPath, contents, ownerUid) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(contents));
+    }
+    catch {
+        throw unsafeSecretEnvLockError(lockPath, "the durable owner record is not valid UTF-8 JSON");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw unsafeSecretEnvLockError(lockPath, "the durable owner record is not an object");
+    }
+    const record = parsed;
+    const createdAtMs = typeof record.createdAt === "string" ? Date.parse(record.createdAt) : Number.NaN;
+    if (record.version !== 1 ||
+        !Number.isInteger(record.pid) ||
+        record.pid <= 0 ||
+        typeof record.createdAt !== "string" ||
+        record.createdAt.length > 64 ||
+        !Number.isFinite(createdAtMs) ||
+        record.ownerUid !== ownerUid ||
+        typeof record.token !== "string" ||
+        record.token.length === 0 ||
+        record.token.length > 128) {
+        throw unsafeSecretEnvLockError(lockPath, "the durable owner record is malformed or belongs to another user");
+    }
+    return {
+        version: 1,
+        pid: record.pid,
+        createdAt: record.createdAt,
+        ownerUid,
+        token: record.token,
+    };
+}
+function secretEnvLockOwnerState(pid) {
+    try {
+        process.kill(pid, 0);
+        return "live";
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return "dead";
+        return "unknown";
+    }
+}
+async function releaseSecretEnvLock(lockPath, expected) {
+    let current;
+    try {
+        current = await readSecretEnvLockSnapshot(lockPath, expected.owner.ownerUid);
+    }
+    catch {
+        // Never remove a path whose ownership changed while this process held the
+        // original descriptor; it may now be another process's live lock.
+        return;
+    }
+    if (current === undefined || !sameSecretEnvLockSnapshot(current, expected))
+        return;
+    try {
+        await rm(lockPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await syncDirectoryBestEffort(dirname(lockPath));
+}
+async function resolveSafeSecretEnvTarget(path) {
+    const canonicalParent = await realpath(dirname(path));
+    const ownerUid = currentProcessUid(canonicalParent);
+    const pathStat = await lstat(canonicalParent);
+    let handle;
+    try {
+        handle = await open(canonicalParent, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        const handleStat = await handle.stat();
+        if (pathStat.isSymbolicLink() ||
+            !pathStat.isDirectory() ||
+            !handleStat.isDirectory() ||
+            pathStat.dev !== handleStat.dev ||
+            pathStat.ino !== handleStat.ino ||
+            handleStat.uid !== ownerUid ||
+            (handleStat.mode & 0o022) !== 0) {
+            throw new SecretEnvPersistenceRefusedError("unsafe-env-path", `Automatic secret persistence requires parent directory ${canonicalParent} to be owned by the current user and not group/world-writable.`);
+        }
+    }
+    finally {
+        await handle?.close();
+    }
+    return { path: join(canonicalParent, basename(path)), ownerUid };
+}
+/** Stable, repository-external lock path for one canonical dotenv target. */
+export async function secretEnvLockPathFor(path) {
+    const target = await resolveSafeSecretEnvTarget(path);
+    return await secretEnvLockPathForCanonical(target.path, target.ownerUid);
+}
+async function secretEnvLockPathForCanonical(path, ownerUid) {
+    const root = join(tmpdir(), `mono-agent-secret-env-locks-${ownerUid}`);
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const rootStat = await lstat(root);
+    if (rootStat.isSymbolicLink() ||
+        !rootStat.isDirectory() ||
+        rootStat.uid !== ownerUid ||
+        (rootStat.mode & 0o077) !== 0) {
+        throw unsafeSecretEnvLockError(root, "the repository-external lock directory is not private to the current user");
+    }
+    const key = createHash("sha256")
+        .update(dirname(path))
+        .update("\0")
+        .update(basename(path))
+        .digest("hex");
+    return join(root, `${key}.lock`);
+}
+function sameSecretEnvLockSnapshot(left, right) {
+    return left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.owner.token === right.owner.token &&
+        left.contents.equals(right.contents);
+}
+async function removeSecretEnvLockWithIdentity(lockPath, expected) {
+    try {
+        const current = await lstat(lockPath);
+        if (current.dev !== expected.dev || current.ino !== expected.ino)
+            return;
+        await rm(lockPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function unsafeSecretEnvLockError(lockPath, detail) {
+    return new SecretEnvPersistenceRefusedError("unsafe-lock-path", `Automatic secret persistence cannot safely use lock ${lockPath}: ${detail}. Verify no mono-agent init is running, then remove the stale lock manually and retry.`);
+}
+async function readSafeFile(path, unsafeCode, malformedCode, ownerUid, allowedLinkCounts = [1], reportedPath = path) {
+    let pathStat;
+    try {
+        pathStat = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { exists: false };
+        throw error;
+    }
+    assertSafeSecretFileStat(reportedPath, pathStat, unsafeCode, ownerUid, allowedLinkCounts);
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const handleStat = await handle.stat();
+        assertSafeSecretFileStat(reportedPath, handleStat, unsafeCode, ownerUid, allowedLinkCounts);
+        if (handleStat.dev !== pathStat.dev || handleStat.ino !== pathStat.ino) {
+            throw new SecretEnvConcurrentModificationError(reportedPath);
+        }
+        const contents = await handle.readFile();
+        decodeUtf8(contents, reportedPath, malformedCode);
+        const finalPathStat = await lstat(path);
+        assertSafeSecretFileStat(reportedPath, finalPathStat, unsafeCode, ownerUid, allowedLinkCounts);
+        if (finalPathStat.dev !== handleStat.dev || finalPathStat.ino !== handleStat.ino) {
+            throw new SecretEnvConcurrentModificationError(reportedPath);
+        }
+        return {
+            exists: true,
+            contents,
+            mode: handleStat.mode,
+            dev: handleStat.dev,
+            ino: handleStat.ino,
+            uid: handleStat.uid,
+            nlink: handleStat.nlink,
+            size: handleStat.size,
+            mtimeMs: handleStat.mtimeMs,
+            ctimeMs: handleStat.ctimeMs,
+        };
+    }
+    catch (error) {
+        if (error.code === "ELOOP") {
+            throw new SecretEnvPersistenceRefusedError(unsafeCode, `Automatic secret persistence refused unsafe path ${reportedPath}.`);
+        }
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function assertSafeSecretFileStat(path, value, unsafeCode, ownerUid, allowedLinkCounts) {
+    if (value.isSymbolicLink() || !value.isFile()) {
+        throw new SecretEnvPersistenceRefusedError(unsafeCode, `Automatic secret persistence refused unsafe path ${path}.`);
+    }
+    if (value.uid !== ownerUid) {
+        throw new SecretEnvPersistenceRefusedError(unsafeCode, `Automatic secret persistence refused ${path} because it is not owned by the current user.`);
+    }
+    if (!allowedLinkCounts.includes(value.nlink)) {
+        throw new SecretEnvPersistenceRefusedError(unsafeCode, `Automatic secret persistence refused ${path} because its hard-link identity is unsafe.`);
+    }
+}
+function snapshotText(snapshot) {
+    if (!snapshot.exists)
+        return "";
+    return new TextDecoder("utf-8", { fatal: true }).decode(snapshot.contents);
+}
+function decodeUtf8(contents, path, code) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(contents);
+    }
+    catch {
+        throw new SecretEnvPersistenceRefusedError(code, `Automatic secret persistence requires UTF-8 text at ${path}.`);
+    }
+}
+function fileMode(snapshot) {
+    return snapshot.exists ? snapshot.mode & 0o777 : 0;
+}
+function changeFor(path, exists, needsWrite, dryRun) {
+    if (!needsWrite)
+        return { path, kind: "unchanged" };
+    if (dryRun)
+        return { path, kind: exists ? "planned-update" : "planned-create" };
+    return { path, kind: exists ? "updated" : "created" };
+}
+function renderDotenvValue(name, value) {
+    if (value.length === 0 || value.includes("\0")) {
+        throw new SecretEnvPersistenceRefusedError("unrepresentable-secret-value", `Automatic secret persistence requires a non-empty dotenv-safe value for ${name}.`);
+    }
+    const candidates = [
+        ...(value.includes("'") ? [] : [`'${value}'`]),
+        ...(value.includes('"') ? [] : [`"${value}"`]),
+        value,
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (parseEnv(`${name}=${candidate}\n`)[name] === value)
+                return candidate;
+        }
+        catch {
+            // Try the next representation. Some values have no lossless dotenv form.
+        }
+    }
+    throw new SecretEnvPersistenceRefusedError("unrepresentable-secret-value", `Automatic secret persistence cannot represent the supplied value for ${name} losslessly.`);
+}
+function mergeDotenvContents(existing, renderedValues) {
+    let parsed;
+    try {
+        parsed = parseEnv(existing);
+    }
+    catch {
+        throw new SecretEnvPersistenceRefusedError("malformed-env", "Automatic secret persistence refused a malformed .env file.");
+    }
+    const lines = splitLinesPreservingEndings(existing);
+    const preferredNewline = lines.find((line) => line.ending.length > 0)?.ending ?? "\n";
+    let valuesChanged = 0;
+    for (const [name, renderedValue] of renderedValues) {
+        if ((parsed[name] ?? "").length > 0)
+            continue;
+        const matcher = new RegExp(`^(\\s*(?:export\\s+)?${escapeRegExp(name)}\\s*=)(.*)$`, "u");
+        let index = -1;
+        for (let candidate = lines.length - 1; candidate >= 0; candidate -= 1) {
+            const body = lines[candidate]?.body ?? "";
+            const assignment = matcher.exec(body);
+            if (assignment === null)
+                continue;
+            const placeholder = /^\s*(?:''|"")?\s*(#.*)?$/u.exec(assignment[2] ?? "");
+            if (placeholder === null)
+                continue;
+            const marker = `__MONO_AGENT_EMPTY_${name}__`;
+            const markedLines = lines.map((line, lineIndex) => lineIndex === candidate
+                ? { ...line, body: `${assignment[1]}'${marker}'${placeholder[1] === undefined ? "" : ` ${placeholder[1]}`}` }
+                : line);
+            try {
+                if (parseEnv(joinPreservedLines(markedLines))[name] === marker) {
+                    index = candidate;
+                    break;
+                }
+            }
+            catch {
+                // The full file validation below reports malformed input without writing.
+            }
+        }
+        if (index === -1) {
+            if (parsed[name] !== undefined) {
+                throw new SecretEnvPersistenceRefusedError("malformed-env", `Automatic secret persistence could not safely replace the empty placeholder for ${name}.`);
+            }
+            const last = lines[lines.length - 1];
+            if (last !== undefined && last.ending.length === 0)
+                last.ending = preferredNewline;
+            lines.push({ body: `${name}=${renderedValue}`, ending: preferredNewline });
+            valuesChanged += 1;
+            continue;
+        }
+        const currentLine = lines[index];
+        const assignment = matcher.exec(currentLine?.body ?? "");
+        const placeholder = /^\s*(?:''|"")?\s*(#.*)?$/u.exec(assignment?.[2] ?? "");
+        if (currentLine === undefined || assignment === null || placeholder === null) {
+            throw new SecretEnvPersistenceRefusedError("malformed-env", `Automatic secret persistence could not safely replace the empty placeholder for ${name}.`);
+        }
+        const comment = placeholder[1];
+        currentLine.body = `${assignment[1]}${renderedValue}${comment === undefined ? "" : ` ${comment}`}`;
+        valuesChanged += 1;
+    }
+    return { contents: joinPreservedLines(lines), valuesChanged };
+}
+function splitLinesPreservingEndings(value) {
+    if (value.length === 0)
+        return [];
+    const lines = [];
+    const endings = /\r\n|\n|\r/gu;
+    let cursor = 0;
+    for (const match of value.matchAll(endings)) {
+        const index = match.index;
+        lines.push({ body: value.slice(cursor, index), ending: match[0] });
+        cursor = index + match[0].length;
+    }
+    if (cursor < value.length)
+        lines.push({ body: value.slice(cursor), ending: "" });
+    return lines;
+}
+function joinPreservedLines(lines) {
+    return lines.map((line) => `${line.body}${line.ending}`).join("");
+}
+const SECRET_ENV_IGNORE_RULES = [
+    "/.env",
+    "/..env.mono-agent-*.tmp",
+    "/.env.mono-agent-*.backup",
+];
+function ensureExactEnvIgnore(existing) {
+    const lines = existing.length === 0 ? [] : existing.split(/\r?\n/u);
+    // Keep the whole secret-file transaction block as the final effective rules.
+    // An earlier rule can be cancelled by a later negation, while the temporary
+    // and rollback names can contain the same secret bytes as the final .env.
+    const meaningful = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const trimmed = (lines[index] ?? "").trim();
+        if (trimmed.length === 0 || trimmed.startsWith("#"))
+            continue;
+        meaningful.push(trimmed);
+    }
+    if (meaningful.length >= SECRET_ENV_IGNORE_RULES.length &&
+        SECRET_ENV_IGNORE_RULES.every((rule, index) => meaningful[meaningful.length - SECRET_ENV_IGNORE_RULES.length + index] === rule))
+        return existing;
+    const newline = existing.includes("\r\n") ? "\r\n" : "\n";
+    return `${existing}${existing.length > 0 && !existing.endsWith("\n") ? newline : ""}` +
+        `${SECRET_ENV_IGNORE_RULES.join(newline)}${newline}`;
+}
+async function atomicReplaceFile(options) {
+    const temporaryPath = join(dirname(options.path), `.${basename(options.path)}.mono-agent-${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporaryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        await handle.writeFile(options.contents);
+        await handle.chmod(options.mode);
+        const tempStat = await handle.stat();
+        if (options.verifyOwnerOnly === true && (tempStat.mode & 0o777) !== 0o600) {
+            throw new SecretEnvPersistenceRefusedError("owner-only-permissions-unsupported", "Automatic secret persistence could not verify owner-only permissions.");
+        }
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await options.beforeCommit?.(options.reportedPath, temporaryPath);
+        await assertSnapshotUnchanged(options.path, options.reportedPath, options.expected, options.ownerUid);
+        await options.beforeRename?.();
+        // beforeRename may perform async Git and cross-file checks. Re-read the
+        // target afterwards so an editor cannot win that widened window silently.
+        await assertSnapshotUnchanged(options.path, options.reportedPath, options.expected, options.ownerUid);
+        await options.beforePromotion?.(options.reportedPath, temporaryPath);
+        await promoteTemporaryFileWithoutClobber(options, temporaryPath);
+        await syncDirectoryBestEffort(dirname(options.path));
+    }
+    finally {
+        await handle?.close();
+        await rm(temporaryPath, { force: true });
+    }
+}
+async function promoteTemporaryFileWithoutClobber(options, temporaryPath) {
+    if (!options.expected.exists) {
+        if (!await linkIfAbsent(temporaryPath, options.path)) {
+            throw new SecretEnvConcurrentModificationError(options.reportedPath);
+        }
+        await assertPromotedContents(options, temporaryPath);
+        return;
+    }
+    const backupPath = join(dirname(options.path), `${basename(options.path)}.mono-agent-${randomUUID()}.backup`);
+    let backupContainsExpected = false;
+    // Once target is moved, this backup is the only durable copy until a target
+    // is proven present. Preserve it by default on every unexpected failure.
+    let preserveConcurrentBackup = true;
+    try {
+        try {
+            // Claim whichever inode occupies the pathname at this exact instant.
+            // A path-based writer racing after this point creates a new target that
+            // the exclusive link below will preserve rather than overwrite.
+            await rename(options.path, backupPath);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw new SecretEnvConcurrentModificationError(options.reportedPath);
+            }
+            throw error;
+        }
+        let moved;
+        try {
+            moved = await readSafeFile(backupPath, basename(options.path) === ".gitignore" ? "unsafe-gitignore-path" : "unsafe-env-path", basename(options.path) === ".gitignore" ? "malformed-gitignore" : "malformed-env", options.ownerUid);
+        }
+        catch {
+            await tightenFileOwnerOnlyBestEffort(backupPath);
+            throw new SecretEnvConcurrentModificationError(options.reportedPath, undefined, backupPath);
+        }
+        backupContainsExpected = moved.exists && sameMovedFileSnapshot(moved, options.expected);
+        if (!backupContainsExpected) {
+            // We claimed a newer writer's file. Restore it without replacing any
+            // still-newer target; if restoration loses that race, retain a private,
+            // ignored recovery copy and fail closed.
+            try {
+                if (await linkIfAbsent(backupPath, options.path)) {
+                    await rm(backupPath, { force: true });
+                    preserveConcurrentBackup = false;
+                }
+                else {
+                    await tightenFileOwnerOnlyBestEffort(backupPath);
+                }
+            }
+            catch {
+                await tightenFileOwnerOnlyBestEffort(backupPath);
+                throw new SecretEnvConcurrentModificationError(options.reportedPath, undefined, backupPath);
+            }
+            throw new SecretEnvConcurrentModificationError(options.reportedPath, undefined, preserveConcurrentBackup ? backupPath : undefined);
+        }
+        let installed;
+        try {
+            await options.beforeInstallLink?.(options.reportedPath, temporaryPath);
+            if (!await claimedBackupStillMatchesExpected(options, backupPath)) {
+                // A writer holding the pre-rename inode changed it after pathname
+                // claim. Restore that inode when the target is still absent so future
+                // writes through the held descriptor remain visible at the target.
+                try {
+                    if (await linkIfAbsent(backupPath, options.path)) {
+                        preserveConcurrentBackup = false;
+                    }
+                    else {
+                        await tightenFileOwnerOnlyBestEffort(backupPath);
+                    }
+                }
+                catch {
+                    await tightenFileOwnerOnlyBestEffort(backupPath);
+                    throw new SecretEnvConcurrentModificationError(options.reportedPath, undefined, backupPath);
+                }
+                throw new SecretEnvConcurrentModificationError(options.reportedPath, undefined, preserveConcurrentBackup ? backupPath : undefined);
+            }
+            installed = await linkIfAbsent(temporaryPath, options.path);
+        }
+        catch {
+            if (!preserveConcurrentBackup) {
+                throw new SecretEnvConcurrentModificationError(options.reportedPath);
+            }
+            await tightenFileOwnerOnlyBestEffort(backupPath);
+            throw new SecretEnvConcurrentModificationError(options.reportedPath, undefined, backupPath);
+        }
+        if (!installed) {
+            // A newer target already exists; the backup is only the superseded
+            // expected snapshot and is safe to remove.
+            preserveConcurrentBackup = false;
+            throw new SecretEnvConcurrentModificationError(options.reportedPath);
+        }
+        try {
+            await options.afterInstallLink?.(options.reportedPath, temporaryPath);
+            await assertPromotedContents(options, temporaryPath);
+        }
+        catch {
+            // If a racing writer deleted our new target, restore the old expected
+            // snapshot. If it wrote a newer target, exclusive link preserves it.
+            const backupStillExpected = await claimedBackupStillMatchesExpected(options, backupPath);
+            try {
+                const restored = await linkIfAbsent(backupPath, options.path);
+                if (restored || backupStillExpected) {
+                    preserveConcurrentBackup = false;
+                }
+                else {
+                    await tightenFileOwnerOnlyBestEffort(backupPath);
+                }
+            }
+            catch {
+                await tightenFileOwnerOnlyBestEffort(backupPath);
+                throw new SecretEnvConcurrentModificationError(options.reportedPath, undefined, backupPath);
+            }
+            throw new SecretEnvConcurrentModificationError(options.reportedPath, undefined, preserveConcurrentBackup ? backupPath : undefined);
+        }
+        if (!await claimedBackupStillMatchesExpected(options, backupPath)) {
+            // The new target is already installed. Preserve the mutated claimed
+            // inode as an owner-only recovery copy instead of discarding its bytes.
+            await tightenFileOwnerOnlyBestEffort(backupPath);
+            throw new SecretEnvConcurrentModificationError(options.reportedPath, undefined, backupPath);
+        }
+        preserveConcurrentBackup = false;
+    }
+    finally {
+        if (!preserveConcurrentBackup) {
+            // Once a newer target exists, the backup is only the superseded expected
+            // snapshot. Removing it cannot discard the racing writer's bytes.
+            await rm(backupPath, { force: true });
+        }
+        else {
+            await tightenFileOwnerOnlyBestEffort(backupPath);
+        }
+    }
+}
+async function claimedBackupStillMatchesExpected(options, backupPath) {
+    try {
+        const current = await readSafeFile(backupPath, basename(options.path) === ".gitignore" ? "unsafe-gitignore-path" : "unsafe-env-path", basename(options.path) === ".gitignore" ? "malformed-gitignore" : "malformed-env", options.ownerUid);
+        return current.exists && options.expected.exists && sameMovedFileSnapshot(current, options.expected);
+    }
+    catch {
+        return false;
+    }
+}
+function sameMovedFileSnapshot(current, expected) {
+    return current.dev === expected.dev &&
+        current.ino === expected.ino &&
+        current.uid === expected.uid &&
+        current.nlink === expected.nlink &&
+        current.size === expected.size &&
+        current.mode === expected.mode &&
+        current.contents.equals(expected.contents);
+}
+async function linkIfAbsent(source, target) {
+    try {
+        await link(source, target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+}
+async function assertPromotedContents(options, temporaryPath) {
+    const temporary = await readSafeFile(temporaryPath, basename(options.path) === ".gitignore" ? "unsafe-gitignore-path" : "unsafe-env-path", basename(options.path) === ".gitignore" ? "malformed-gitignore" : "malformed-env", options.ownerUid, [2]);
+    const promoted = await readSafeFile(options.path, basename(options.path) === ".gitignore" ? "unsafe-gitignore-path" : "unsafe-env-path", basename(options.path) === ".gitignore" ? "malformed-gitignore" : "malformed-env", options.ownerUid, [2], options.reportedPath);
+    if (!temporary.exists ||
+        !promoted.exists ||
+        temporary.dev !== promoted.dev ||
+        temporary.ino !== promoted.ino ||
+        !temporary.contents.equals(options.contents) ||
+        !promoted.contents.equals(options.contents) ||
+        fileMode(promoted) !== options.mode) {
+        throw new SecretEnvConcurrentModificationError(options.reportedPath);
+    }
+}
+async function tightenFileOwnerOnlyBestEffort(path) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_WRONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        if ((await handle.stat()).isFile())
+            await handle.chmod(0o600);
+    }
+    catch {
+        // The recovery copy is already fail-closed and ignored; preserve bytes.
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function createMonoAgentConfigExclusively(path, config) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporaryPath = join(dirname(path), `.${basename(path)}.mono-agent-${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporaryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        await handle.writeFile(`${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8" });
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        // link is an atomic create-if-absent operation. Unlike rename it cannot
+        // replace a config another process created while the wizard was running.
+        await link(temporaryPath, path);
+        await syncDirectoryBestEffort(dirname(path));
+    }
+    finally {
+        await handle?.close();
+        await rm(temporaryPath, { force: true });
+    }
+}
+async function removeCreatedConfigIfUnchanged(path, expectedIdentity, expectedContents) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.nlink !== 1 || !sameFileIdentity(opened, expectedIdentity))
+            return false;
+        if (await handle.readFile({ encoding: "utf8" }) !== expectedContents)
+            return false;
+        const named = await lstat(path);
+        if (!named.isFile() || named.isSymbolicLink() || named.nlink !== 1 || !sameFileIdentity(named, expectedIdentity)) {
+            return false;
+        }
+        await unlink(path);
+        await syncDirectoryBestEffort(dirname(path));
+        return true;
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function sameFileIdentity(value, expected) {
+    return value.dev === expected.dev && value.ino === expected.ino;
+}
+async function assertSnapshotUnchanged(path, reportedPath, expected, ownerUid) {
+    let current;
+    try {
+        current = await readSafeFile(path, basename(path) === ".gitignore" ? "unsafe-gitignore-path" : "unsafe-env-path", basename(path) === ".gitignore" ? "malformed-gitignore" : "malformed-env", ownerUid, [1], reportedPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            if (!expected.exists)
+                return;
+            throw new SecretEnvConcurrentModificationError(reportedPath);
+        }
+        throw error;
+    }
+    if (current.exists !== expected.exists)
+        throw new SecretEnvConcurrentModificationError(reportedPath);
+    if (!current.exists || !expected.exists)
+        return;
+    if (current.dev !== expected.dev ||
+        current.ino !== expected.ino ||
+        current.uid !== expected.uid ||
+        current.nlink !== expected.nlink ||
+        current.size !== expected.size ||
+        current.mtimeMs !== expected.mtimeMs ||
+        current.ctimeMs !== expected.ctimeMs ||
+        current.mode !== expected.mode ||
+        !current.contents.equals(expected.contents)) {
+        throw new SecretEnvConcurrentModificationError(reportedPath);
+    }
+}
+async function syncDirectoryBestEffort(path) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY);
+        await handle.sync();
+    }
+    catch {
+        // The file itself is already fsynced; some platforms/filesystems reject directory fsync.
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function isGitTracked(path) {
+    const directory = dirname(path);
+    const repository = await runGit(["-C", directory, "rev-parse", "--show-toplevel"]);
+    if (!repository.ok) {
+        if (await hasGitMetadata(directory)) {
+            throw new SecretEnvPersistenceRefusedError("git-safety-unavailable", `Automatic secret persistence could not verify git tracking for ${path}.`);
+        }
+        return false;
+    }
+    const root = repository.stdout.replace(/\r?\n$/u, "");
+    const canonicalPath = join(await realpath(directory), basename(path));
+    const tracked = await runGit(["-C", root, "ls-files", "--error-unmatch", "--", relative(root, canonicalPath)]);
+    if (tracked.ok)
+        return true;
+    if (Number(tracked.code) === 1)
+        return false;
+    throw new SecretEnvPersistenceRefusedError("git-safety-unavailable", `Automatic secret persistence could not verify git tracking for ${path}.`);
+}
+/** Recheck the complete durable dotenv guard without changing either file. */
+export async function verifySecretEnvPersistenceGuard(path) {
+    const target = await resolveSafeSecretEnvTarget(path);
+    const envSnapshot = await readSafeFile(target.path, "unsafe-env-path", "malformed-env", target.ownerUid);
+    if (!envSnapshot.exists || fileMode(envSnapshot) !== 0o600 || await isGitTracked(target.path)) {
+        return false;
+    }
+    const gitIgnorePath = join(dirname(target.path), ".gitignore");
+    const gitIgnoreSnapshot = await readSafeFile(gitIgnorePath, "unsafe-gitignore-path", "malformed-gitignore", target.ownerUid);
+    return gitIgnoreSnapshot.exists && ensureExactEnvIgnore(snapshotText(gitIgnoreSnapshot)) === snapshotText(gitIgnoreSnapshot);
+}
+function runGit(args) {
+    return new Promise((resolveResult) => {
+        execFile("git", [...args], { encoding: "utf8" }, (error, stdout) => {
+            if (error === null) {
+                resolveResult({ ok: true, stdout });
+                return;
+            }
+            const code = error.code;
+            resolveResult({ ok: false, stdout, ...(code === undefined ? {} : { code }) });
+        });
+    });
+}
+async function hasGitMetadata(start) {
+    let current = resolve(start);
+    while (true) {
+        try {
+            await lstat(join(current, ".git"));
+            return true;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return true;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
-function identityTemplate(dir, knowledgeFiles) {
+function identityTemplate(dir, agentName, purpose, knowledgeFiles) {
     const knowledgeSection = knowledgeFiles.length === 0
-        ? "This folder starts empty; describe the agent's purpose and boundaries here."
+        ? "No existing project knowledge files were detected. Add references to authoritative knowledge here when available."
         : [
             "This folder already carries knowledge the agent must read and respect:",
             "",
@@ -70,11 +1193,11 @@ function identityTemplate(dir, knowledgeFiles) {
         ].join("\n");
     return `# Identity
 
-You are the mono agent constructed in \`${basename(dir)}\`.
+You are ${agentName}, a mono agent constructed in \`${basename(dir)}\`.
 
 ## Role
 
-Describe what this agent is for in one or two sentences.
+${purpose}
 
 ## Knowledge
 
@@ -96,4 +1219,75 @@ async function pathExists(path) {
         return false;
     }
 }
+function scaffoldPathEscapesRoot(pathRelative) {
+    return pathRelative === ".." || pathRelative.startsWith(`..${sep}`) || isAbsolute(pathRelative);
+}
+/**
+ * Refuse generated scaffold artifacts whose parent chain escapes through a
+ * symlink. This protects ordinary and save-incomplete init alike; staging is a
+ * validation boundary, not authorization to weaken the eventual write path.
+ */
+async function ensureSafeScaffoldParent(root, filePath, createMissing) {
+    const pathRelative = relative(root, filePath);
+    if (pathRelative.length === 0 || scaffoldPathEscapesRoot(pathRelative)) {
+        throw new Error(`Refusing to create scaffold artifact outside the agent directory: ${filePath}`);
+    }
+    const parentRelative = dirname(pathRelative);
+    if (parentRelative === ".")
+        return;
+    let current = root;
+    for (const segment of parentRelative.split(sep).filter((part) => part.length > 0)) {
+        const next = join(current, segment);
+        let entry;
+        try {
+            entry = await lstat(next);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            if (!createMissing)
+                return;
+            try {
+                await mkdir(next);
+            }
+            catch (mkdirError) {
+                if (mkdirError.code !== "EEXIST")
+                    throw mkdirError;
+            }
+            entry = await lstat(next);
+        }
+        if (entry.isSymbolicLink()) {
+            throw new Error(`Refusing to create scaffold artifact through symbolic-link parent: ${next}`);
+        }
+        if (!entry.isDirectory()) {
+            throw new Error(`Refusing to create scaffold artifact through non-directory parent: ${next}`);
+        }
+        current = next;
+    }
+}
+async function assertSafeScaffoldTarget(path, label) {
+    try {
+        const entry = await lstat(path);
+        if (entry.isSymbolicLink()) {
+            throw new Error(`Refusing to use symbolic-link scaffold ${label}: ${path}`);
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+async function createSafeScaffoldDirectory(path) {
+    try {
+        await mkdir(path);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const entry = await lstat(path);
+    if (entry.isSymbolicLink() || !entry.isDirectory()) {
+        throw new Error(`Refusing non-directory scaffold working path: ${path}`);
+    }
+}
 //# sourceMappingURL=init.js.map