@tea-agent/loop-agent 0.35.0-beta.2 → 0.35.1-beta.0

package/dist/commands/init-upgrade.js

@@ -46,6 +46,60 @@ function isHomeFingerprint(value) {
         keys[1] === "sha256" &&
         isSha256(value.sha256));
 }
+/**
+ * Shape guard for the controller-owned gitignore migration assessment.
+ * `assessGitignoreMigration` is the single schema fact source; status/report
+ * reads fail closed on any shape that the writer could not have produced
+ * (AC-005). `queryError` may be absent and arrays may be empty; extra keys are
+ * tolerated for forward compatibility.
+ */
+function isGitignoreMigrationAssessment(value) {
+    if (!isRecord(value))
+        return false;
+    const assessment = value;
+    if (assessment.schemaVersion !== 1)
+        return false;
+    if (typeof assessment.managedBlockRefreshed !== "boolean")
+        return false;
+    if (typeof assessment.needsAgentsReview !== "boolean")
+        return false;
+    if (!isRecord(assessment.git))
+        return false;
+    const git = assessment.git;
+    if (typeof git.isRepo !== "boolean")
+        return false;
+    if (git.queryError !== undefined && typeof git.queryError !== "string") {
+        return false;
+    }
+    if (!Array.isArray(assessment.harnessTracked) ||
+        !assessment.harnessTracked.every((entry) => typeof entry === "string")) {
+        return false;
+    }
+    if (!Array.isArray(assessment.agentsTracked) ||
+        !assessment.agentsTracked.every((entry) => typeof entry === "string")) {
+        return false;
+    }
+    if (!Array.isArray(assessment.stagedRisk) ||
+        !assessment.stagedRisk.every((entry) => typeof entry === "string")) {
+        return false;
+    }
+    if (!Array.isArray(assessment.followUp) ||
+        !assessment.followUp.every((entry) => typeof entry === "string")) {
+        return false;
+    }
+    if (!Array.isArray(assessment.recommendedCommands))
+        return false;
+    for (const entry of assessment.recommendedCommands) {
+        if (!isRecord(entry))
+            return false;
+        if (typeof entry.command !== "string" || typeof entry.note !== "string") {
+            return false;
+        }
+    }
+    return (assessment.status === "clean" ||
+        assessment.status === "recommended" ||
+        assessment.status === "blocked");
+}
 function cloneJson(value) {
     return JSON.parse(JSON.stringify(value));
 }
@@ -171,6 +225,143 @@ function assertTerminalCoherence(state) {
         throw new Error("invalid init upgrade status/phase coherence");
     }
 }
+/** Read-only git query; never mutates the user index (no status refresh, no write). */
+function runGitQuery(cwd, args) {
+    return new Promise((resolve) => {
+        const child = spawn("git", ["-C", cwd, ...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
+        child.on("error", (error) => {
+            resolve({ ok: false, stdout: "", stderr: error.message });
+        });
+        child.on("close", (code) => {
+            resolve({
+                ok: code === 0,
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+            });
+        });
+    });
+}
+function splitNulPaths(output) {
+    return output.split("\0").filter((entry) => entry.length > 0);
+}
+/**
+ * Gitignore migration assessment (PRD 2026-08-13): inventories tracked
+ * `.harness/**` / `.agents/**` with read-only git queries after the managed
+ * block has converged, and recommends index-only untrack commands. The
+ * controller never mutates the user Git index and never deletes local files.
+ */
+export async function assessGitignoreMigration(repoRoot, input) {
+    const base = {
+        schemaVersion: 1,
+        managedBlockRefreshed: input.managedBlockRefreshed,
+        harnessTracked: [],
+        agentsTracked: [],
+        stagedRisk: [],
+        needsAgentsReview: false,
+        followUp: [
+            "run `git status --short` and confirm only the intended untrack changes",
+            "confirm the .harness/ and .agents/ directories still exist locally after untracking",
+            "run `loop-agent init doctor` to re-check the gitignore loop-agent block",
+        ],
+    };
+    const inside = await runGitQuery(repoRoot, ["rev-parse", "--is-inside-work-tree"]);
+    if (!inside.ok) {
+        return {
+            ...base,
+            git: {
+                isRepo: false,
+                queryError: inside.stderr.trim() || "not inside a Git work tree",
+            },
+            recommendedCommands: [],
+            status: "blocked",
+        };
+    }
+    const tracked = await runGitQuery(repoRoot, [
+        "ls-files",
+        "-z",
+        "--cached",
+        "--",
+        ".harness",
+        ".agents",
+    ]);
+    if (!tracked.ok) {
+        return {
+            ...base,
+            git: {
+                isRepo: true,
+                queryError: tracked.stderr.trim() || "git ls-files query failed",
+            },
+            recommendedCommands: [],
+            status: "blocked",
+        };
+    }
+    const staged = await runGitQuery(repoRoot, [
+        "diff",
+        "--cached",
+        "--name-only",
+        "-z",
+    ]);
+    if (!staged.ok) {
+        return {
+            ...base,
+            git: {
+                isRepo: true,
+                queryError: staged.stderr.trim() || "git diff --cached query failed",
+            },
+            recommendedCommands: [],
+            status: "blocked",
+        };
+    }
+    const trackedPaths = splitNulPaths(tracked.stdout);
+    const harnessTracked = trackedPaths.filter((entry) => entry.startsWith(".harness/"));
+    const agentsTracked = trackedPaths.filter((entry) => entry.startsWith(".agents/"));
+    const stagedRisk = splitNulPaths(staged.stdout);
+    const needsAgentsReview = agentsTracked.length > 0;
+    if (stagedRisk.length > 0) {
+        // Fail closed: staged entries make any untrack advice ambiguous.
+        return {
+            ...base,
+            git: { isRepo: true },
+            harnessTracked,
+            agentsTracked,
+            stagedRisk,
+            needsAgentsReview,
+            recommendedCommands: [],
+            status: "blocked",
+        };
+    }
+    const recommendedCommands = [];
+    if (harnessTracked.length > 0) {
+        recommendedCommands.push({
+            command: "git rm -r --cached --ignore-unmatch .harness",
+            note: "untracks tracked .harness runtime facts; index-only, working-tree files are kept",
+        });
+    }
+    if (agentsTracked.length > 0) {
+        recommendedCommands.push({
+            command: "git rm -r --cached --ignore-unmatch .agents",
+            note: "untracks tracked .agents local skills; index-only, working-tree files are kept; review team-shareable customizations first",
+        });
+    }
+    return {
+        ...base,
+        git: { isRepo: true },
+        harnessTracked,
+        agentsTracked,
+        stagedRisk,
+        needsAgentsReview,
+        recommendedCommands,
+        status: harnessTracked.length > 0 || agentsTracked.length > 0
+            ? "recommended"
+            : "clean",
+    };
+}
 function runRoot(repoRoot) {
     return path.join(repoRoot, RUN_ROOT);
 }
@@ -240,6 +431,7 @@ async function writeControllerAnchor(input) {
         throw new Error("init upgrade controller authority anchor path escapes Git directory");
     }
     let authoritativeHomeFingerprint;
+    let authoritativeGitignoreMigrationSha256;
     if (input.initialize) {
         if (await exists(location.file)) {
             throw new Error("init upgrade controller authority anchor already exists");
@@ -252,6 +444,14 @@ async function writeControllerAnchor(input) {
     else {
         const current = await readControllerAnchor(location.repoRoot, input.state);
         authoritativeHomeFingerprint = current.homeFingerprint;
+        // Preserve the gitignore migration artifact binding across later
+        // mergeAuthority/completion writes; fail closed on a corrupt or
+        // non-SHA-256 binding instead of silently dropping or propagating it.
+        const digest = input.gitignoreMigrationSha256 ?? current.gitignoreMigrationSha256;
+        if (digest !== undefined && !isSha256(digest)) {
+            throw new Error("init upgrade controller authority gitignore migration digest binding is invalid");
+        }
+        authoritativeGitignoreMigrationSha256 = digest;
     }
     await writeJsonAtomic(location.file, {
         schemaVersion: 1,
@@ -259,6 +459,9 @@ async function writeControllerAnchor(input) {
         runId: input.state.runId,
         controllerIdentity: input.state.controllerIdentity,
         homeFingerprint: authoritativeHomeFingerprint,
+        ...(authoritativeGitignoreMigrationSha256 !== undefined
+            ? { gitignoreMigrationSha256: authoritativeGitignoreMigrationSha256 }
+            : {}),
         ...(input.mergeAuthority ? { mergeAuthority: input.mergeAuthority } : {}),
         ...(input.completion ? { completion: input.completion } : {}),
     });
@@ -451,7 +654,7 @@ async function saveState(directory, state) {
     state.updatedAt = new Date().toISOString();
     await writeJsonAtomic(path.join(directory, "state.json"), state);
 }
-function toResult(state, verification) {
+function toResult(state, verification, gitignoreMigration) {
     return {
         runId: state.runId,
         status: state.status,
@@ -462,9 +665,10 @@ function toResult(state, verification) {
         humanDecisions: state.humanDecisions,
         nextAction: state.nextAction,
         ...(verification ? { verification } : {}),
+        ...(gitignoreMigration ? { gitignoreMigration } : {}),
     };
 }
-function renderReport(state, verification) {
+function renderReport(state, verification, gitignoreMigration) {
     const lines = [
         "# loop-agent init upgrade report",
         "",
@@ -480,6 +684,47 @@ function renderReport(state, verification) {
         `- retired path actions: ${state.actionReceipts.filter((action) => action.type === "migrate-owned-file" || action.type === "remove-owned-file" || action.type === "remove-empty-directory").length}`,
         `- remaining model merge tasks: ${state.mergeTasks.length}`,
         `- remaining human decisions: ${state.humanDecisions.length}`,
+        `- gitignore migration assessment: \`.harness/init-upgrades/${state.runId}/gitignore-migration.json\` (index-only untrack guidance; the controller never modifies the Git index)`,
+        ...(gitignoreMigration
+            ? [
+                "",
+                "## Gitignore migration assessment",
+                "",
+                `- status: \`${gitignoreMigration.status}\``,
+                `- managed block refreshed: \`${gitignoreMigration.managedBlockRefreshed}\``,
+                `- tracked \`.harness\` inventory: ${gitignoreMigration.harnessTracked.length > 0
+                    ? gitignoreMigration.harnessTracked
+                        .map((entry) => `\`${entry}\``)
+                        .join(", ")
+                    : "(none)"}`,
+                `- tracked \`.agents\` inventory: ${gitignoreMigration.agentsTracked.length > 0
+                    ? gitignoreMigration.agentsTracked
+                        .map((entry) => `\`${entry}\``)
+                        .join(", ")
+                    : "(none)"}`,
+                ...(gitignoreMigration.stagedRisk.length > 0
+                    ? [
+                        `- staged risk: ${gitignoreMigration.stagedRisk
+                            .map((entry) => `\`${entry}\``)
+                            .join(", ")}`,
+                    ]
+                    : []),
+                ...(gitignoreMigration.git.queryError
+                    ? [
+                        `- git query blocker: \`${gitignoreMigration.git.queryError}\``,
+                    ]
+                    : []),
+                `- \`.agents\` review required: \`${gitignoreMigration.needsAgentsReview}\``,
+                "- recommended commands:",
+                ...(gitignoreMigration.recommendedCommands.length > 0
+                    ? gitignoreMigration.recommendedCommands.map((entry) => `  - \`${entry.command}\` — ${entry.note}`)
+                    : ["  - (none)"]),
+                "- follow-up:",
+                ...(gitignoreMigration.followUp.length > 0
+                    ? gitignoreMigration.followUp.map((entry) => `  - ${entry}`)
+                    : ["  - (none)"]),
+            ]
+            : []),
         "",
         "## Next action",
         "",
@@ -501,8 +746,8 @@ function renderReport(state, verification) {
     ];
     return `${lines.join("\n")}\n`;
 }
-async function writeReport(directory, state, verification) {
-    await writeFile(path.join(directory, "final-report.md"), renderReport(state, verification), "utf-8");
+async function writeReport(directory, state, verification, gitignoreMigration) {
+    await writeFile(path.join(directory, "final-report.md"), renderReport(state, verification, gitignoreMigration), "utf-8");
 }
 async function assertInactive(input) {
     let activity;
@@ -2303,14 +2548,62 @@ async function readValidatedStatusState(repoRoot, runId) {
             throw new Error("Controller identity drift detected for persisted init upgrade state");
         }
     }
-    return { state, directory };
+    return { state, directory, anchor };
+}
+/**
+ * Read-only projection of the controller-owned gitignore migration assessment
+ * for status/report reads. The artifact is written by executeUpgrade after the
+ * managed block has converged; a missing artifact is tolerated only while the
+ * run has not yet reached that write point (DISCOVER/VERSION_GATE). Every
+ * other missing, malformed, or shape-invalid artifact fails closed so
+ * status/report never trust mutable or incomplete content (AC-005).
+ */
+async function readGitignoreMigrationProjection(directory, state, gitignoreMigrationSha256) {
+    const file = path.join(directory, "gitignore-migration.json");
+    let rawBytes;
+    let raw;
+    try {
+        rawBytes = await readFile(file);
+        raw = rawBytes.toString("utf-8");
+    }
+    catch (error) {
+        const cause = error;
+        if (cause.code === "ENOENT") {
+            if (state.phase === "DISCOVER" || state.phase === "VERSION_GATE") {
+                return undefined;
+            }
+            throw new Error(`init upgrade integrity error: gitignore migration artifact is missing for run ${state.runId} (phase ${state.phase}); refusing to trust an incomplete run`);
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`init upgrade integrity error: gitignore migration artifact is malformed JSON for run ${state.runId} (${file})`);
+    }
+    if (!isGitignoreMigrationAssessment(parsed)) {
+        throw new Error(`init upgrade integrity error: gitignore migration artifact has an invalid shape for run ${state.runId} (${file})`);
+    }
+    // The artifact exists, so this run has generated an assessment; the
+    // controller authority binding must exist, be a legal SHA-256, and match
+    // the raw artifact bytes on disk (fail closed otherwise).
+    if (gitignoreMigrationSha256 === undefined || !isSha256(gitignoreMigrationSha256)) {
+        throw new Error(`init upgrade integrity error: gitignore migration artifact digest binding is missing or invalid for run ${state.runId}`);
+    }
+    if (sha256(rawBytes) !== gitignoreMigrationSha256) {
+        throw new Error(`init upgrade integrity error: gitignore migration artifact digest does not match the controller authority binding for run ${state.runId}`);
+    }
+    return parsed;
 }
 async function readStatusResult(repoRoot, runId) {
-    const { state } = await readValidatedStatusState(repoRoot, runId);
-    if (state.status !== "completed")
-        return toResult(state);
+    const { state, directory, anchor } = await readValidatedStatusState(repoRoot, runId);
+    if (state.status !== "completed") {
+        return toResult(state, undefined, await readGitignoreMigrationProjection(directory, state, anchor.gitignoreMigrationSha256));
+    }
     const authenticated = await readFreshCompletedVerification(repoRoot, state);
-    return toResult(state, authenticated.verification);
+    return toResult(state, authenticated.verification, await readGitignoreMigrationProjection(directory, state, anchor.gitignoreMigrationSha256));
 }
 async function executeUpgrade(directory, state, input) {
     const identity = await readIdentity();
@@ -2445,17 +2738,50 @@ async function executeUpgrade(directory, state, input) {
         }
     }
     state.humanDecisions = post.humanDecisions;
+    // Gitignore migration assessment: after the managed block has converged,
+    // inventory tracked .harness/.agents paths with read-only git queries and
+    // recommend index-only untrack commands. The controller never mutates the
+    // user Git index; suggested commands only change the index and keep the
+    // working tree intact.
+    const gitignoreMigration = await assessGitignoreMigration(state.repoRoot, {
+        managedBlockRefreshed: !post.deterministicActions.some((action) => action.type === "refresh-managed-block" &&
+            action.path === ".gitignore"),
+    });
+    await writeJsonAtomic(path.join(directory, "gitignore-migration.json"), gitignoreMigration);
+    // Bind the raw on-disk artifact bytes to the Git-dir controller authority
+    // before any needs-human-decision/model-merge/completed return; later
+    // mergeAuthority/completion anchor writes preserve this binding.
+    await writeControllerAnchor({
+        state,
+        gitignoreMigrationSha256: sha256(await readFile(path.join(directory, "gitignore-migration.json"))),
+    });
+    if (gitignoreMigration.status === "blocked" ||
+        gitignoreMigration.needsAgentsReview) {
+        // Route through the existing needs-human-decision pause: `.agents`
+        // tracked content must be reviewed (PRD §7) and staged blockers must be
+        // resolved before safe untrack guidance can be given (PRD §8).
+        post.humanDecisions.push(gitignoreMigration.status === "blocked"
+            ? {
+                path: ".harness/** (gitignore migration)",
+                reason: "staged changes or a failed git query block safe untrack guidance; resolve the blocker, then rerun the migration assessment",
+            }
+            : {
+                path: ".agents/** (gitignore migration)",
+                reason: "tracked .agents content may include team-shareable customizations; review before running the suggested untrack commands",
+            });
+    }
+    state.humanDecisions = post.humanDecisions;
     if (post.humanDecisions.length > 0) {
         state.mergeTasks = [];
         state.mergeGuard = undefined;
         state.status = "needs-human-decision";
         state.phase = "MODEL_MERGE";
         state.nextAction =
-            "Resolve the recorded destructive, credential, or ambiguous decisions; the controller will not overwrite uncertain user intent.";
+            "Resolve the recorded destructive, credential, or ambiguous decisions; the controller will not overwrite uncertain user intent. For gitignore migration: review tracked .agents customizations or resolve the staged blocker first, then rerun the assessment so index-only untrack commands can be recommended.";
         await writeJsonAtomic(path.join(directory, "merge-tasks.json"), state.mergeTasks);
         await saveState(directory, state);
-        await writeReport(directory, state);
-        return toResult(state);
+        await writeReport(directory, state, undefined, gitignoreMigration);
+        return toResult(state, undefined, gitignoreMigration);
     }
     if (post.modelMergeTasks.length > 0) {
         const activeTask = post.modelMergeTasks[0];
@@ -2487,8 +2813,8 @@ async function executeUpgrade(directory, state, input) {
         state.nextAction = `Complete only task ${activeTask.taskId} within allowedPaths=[${activeTask.allowedPaths.join(", ")}], then call init upgrade --continue. The controller will reject every other workspace change and all symlink/realpath escapes.`;
         await writeJsonAtomic(path.join(directory, "merge-tasks.json"), state.mergeTasks);
         await saveState(directory, state);
-        await writeReport(directory, state);
-        return toResult(state);
+        await writeReport(directory, state, undefined, gitignoreMigration);
+        return toResult(state, undefined, gitignoreMigration);
     }
     state.mergeTasks = [];
     state.mergeGuard = undefined;
@@ -2504,7 +2830,7 @@ async function executeUpgrade(directory, state, input) {
         state.nextAction =
             "Init upgrade completed; reload the host session so updated AGENTS, skills, and recovery extensions are discovered.";
         // The report is controller-produced before its exact bytes are anchored.
-        await writeReport(directory, state, verification);
+        await writeReport(directory, state, verification, gitignoreMigration);
         const finalReportSha256 = sha256(await readFile(path.join(directory, "final-report.md")));
         await writeControllerAnchor({
             state,
@@ -2529,8 +2855,8 @@ async function executeUpgrade(directory, state, input) {
             : "Verification failed. Inspect verification.json; repair only the controller-returned concrete merge path or address the reported external blocker, then use --continue.";
     }
     await saveState(directory, state);
-    await writeReport(directory, state, verification);
-    return toResult(state, verification);
+    await writeReport(directory, state, verification, gitignoreMigration);
+    return toResult(state, verification, gitignoreMigration);
 }
 export async function runInitUpgrade(input) {
     const repoRoot = path.resolve(input.repoRoot);
@@ -2541,14 +2867,20 @@ export async function runInitUpgrade(input) {
     if (mode === "status")
         return await readStatusResult(repoRoot, input.runId);
     if (mode === "report") {
-        const { state } = await readValidatedStatusState(repoRoot, input.runId);
+        const { state, directory, anchor } = await readValidatedStatusState(repoRoot, input.runId);
         if (state.status === "completed") {
             const authenticated = await readFreshCompletedVerification(repoRoot, state);
+            // Completed report bytes are anchored by finalReportSha256; still
+            // verify the gitignore migration artifact binding so shape-valid
+            // tampering fails closed here as well.
+            await readGitignoreMigrationProjection(directory, state, anchor.gitignoreMigrationSha256);
             return { markdown: authenticated.reportMarkdown };
         }
         // Non-completed reports are projections of the validated state, never an
         // unauthenticated read of a mutable run-local report file.
-        return { markdown: renderReport(state) };
+        return {
+            markdown: renderReport(state, undefined, await readGitignoreMigrationProjection(directory, state, anchor.gitignoreMigrationSha256)),
+        };
     }
     const runId = mode === "continue"
         ? input.runId

package/dist/commands/init.js

@@ -846,55 +846,19 @@ function mergeGitignoreManagedBlock(existing, block) {
         return `${block}\n`;
     return `${existing.trimEnd()}\n\n${block}\n`;
 }
-/** Shared ignore rules for loop-agent runtime facts; keep prompts/ and directory structure shareable. */
+/**
+ * Shared ignore rules for loop-agent runtime facts. The four directories are
+ * local, rebuildable runtime surface: every developer runs loop-agent init
+ * after cloning, so nothing inside them is team-shareable by default.
+ * `scripts/` and `ai_workspace/loop-agent/` stay on the shared commit surface.
+ */
 export function buildManagedGitignoreBlock() {
     return [
         GITIGNORE_BLOCK_START,
-        "# loop-agent runtime: ignore personal/session facts; keep prompts and directory placeholders shareable",
-        "",
-        "# tasks (source + runtime state per developer/session)",
-        ".harness/tasks/*",
-        "!.harness/tasks/.gitkeep",
-        "",
-        "# DAG runs",
-        ".harness/dag-runs/active/*",
-        "!.harness/dag-runs/active/.gitkeep",
-        ".harness/dag-runs/completed/*",
-        "!.harness/dag-runs/completed/.gitkeep",
-        ".harness/dag-runs/paused/*",
-        "!.harness/dag-runs/paused/.gitkeep",
-        "",
-        "# one-shot executor runs",
-        ".harness/runs/*",
-        "!.harness/runs/.gitkeep",
-        "!.harness/runs/active/",
-        "!.harness/runs/active/.gitkeep",
-        "!.harness/runs/completed/",
-        "!.harness/runs/completed/.gitkeep",
-        "!.harness/runs/failed/",
-        "!.harness/runs/failed/.gitkeep",
-        "",
-        "# session / cache / logs / recomputable surface state",
-        ".harness/live/",
-        ".harness/cache/",
-        ".harness/*.log",
-        ".harness/init-surface.json",
-        ".harness/init-upgrades/",
-        "",
-        "# Eval Lab runtime (candidates, campaigns, scorecards, dogfood scratch)",
-        ".harness/evaluation/",
-        "",
-        "# fullstack / worker dogfood evidence (local campaign scratch)",
-        ".harness/dogfood-evidence/",
-        "",
-        "# worker task pool",
-        ".harness/task-pool/*",
+        "# loop-agent runtime: local, rebuildable facts; do not ignore scripts/ or ai_workspace/loop-agent/",
+        ".harness/",
+        ".agents/",
         ".task-pool/",
-        "",
-        "# repo-local skill dependencies installed inside projected skills",
-        ".agents/skills/*/node_modules/",
-        "",
-        "# multi-worktree parallel mode",
         ".worktrees/",
         GITIGNORE_BLOCK_END,
     ].join("\n");
@@ -1087,26 +1051,8 @@ async function ensureHarnessDirs(repoRoot, written) {
         await mkdir(path.join(repoRoot, dir), { recursive: true });
         written.push(dir);
     }
-    const placeholders = [
-        ".harness/tasks/.gitkeep",
-        ".harness/dag-runs/active/.gitkeep",
-        ".harness/dag-runs/completed/.gitkeep",
-        ".harness/dag-runs/paused/.gitkeep",
-        ".harness/runs/.gitkeep",
-        ".harness/runs/active/.gitkeep",
-        ".harness/runs/completed/.gitkeep",
-        ".harness/runs/failed/.gitkeep",
-    ];
-    for (const relativePath of placeholders) {
-        const target = path.join(repoRoot, relativePath);
-        try {
-            await access(target);
-        }
-        catch {
-            await writeFile(target, "", "utf8");
-            written.push(relativePath);
-        }
-    }
+    // No .gitkeep placeholders: .harness/ is fully ignored by the managed
+    // gitignore block, and runtime dirs are recreated on demand by init/doctor.
 }
 async function writeCompatPrompts(input) {
     for (const [name, content] of Object.entries(COMPAT_PROMPTS)) {
@@ -2490,6 +2436,7 @@ export function buildInitInstructions(input) {
         "When the user says `loop-agent初始化更新`, `loop-agent 初始化更新`, `更新 loop-agent 初始化内容`, or an equivalent write request, run `loop-agent init upgrade --repo-root . --json` as the single controller-owned entry. Complete returned single-file allowedPaths merge tasks and call `--continue` until a stable terminal result; do not stop at check-update, needs-safe-update, needs-model-merge, or verification-pending.",
         "Explicit `检查初始化更新`, `初始化更新校验`, or `只检查，不要修改` stays strictly read-only: run only `loop-agent init check-update --repo-root . --markdown` and do not create an upgrade run.",
         "Upgrade manages project `.opencode/plugins/`, `.pi/extensions/`, and `.pi/settings.json` by nested merge. Pi must trust the project before loading these settings; do not read or write `~/.pi/agent/settings.json` by default.",
+        "The upgrade also writes a read-only gitignore migration assessment (`.harness/init-upgrades/<run-id>/gitignore-migration.json`): tracked `.harness/**` and `.agents/**` get index-only `git rm -r --cached --ignore-unmatch` guidance (working-tree files are kept). Pause for human review when `.agents` content is tracked or when staged changes / git query failures block safe guidance; never run git rm yourself.",
         "",
         "## Apply Defaults",
         "",
@@ -2505,7 +2452,7 @@ export function buildInitInstructions(input) {
         "- Enrich the root `README.md`: keep the deterministic project title and the loop-agent managed block intact, and fill the human-authored sections (项目概览, 技术栈与目录结构, 开发与验证) from the target project's actual files. The root README must serve both as a human-first project entry and as an agent work entry; replace the initialization-model supplement comments when the project files provide the information.",
         `- Populate \`${governanceRoot}/verification-matrix.md\` with the target project's actual quick, standard, and full verification commands derived from its real language and toolchain, keeping the governance rows intact.`,
         "- Project repo-local skills live in `.agents/skills/`. Do not create a root `skills/` directory in the target project; the package's bundled `skills/` remains the built-in fallback.",
-        "- Merge a loop-agent managed block into `.gitignore` that ignores harness runtime facts (tasks, dag-runs, runs, evaluation, dogfood-evidence, live, cache, init-surface.json, .harness/task-pool, legacy .task-pool residue) while keeping prompts and directory placeholders shareable.",
+        "- Merge a loop-agent managed block into `.gitignore` that ignores exactly the four local, rebuildable runtime directories (`.harness/`, `.agents/`, `.task-pool/`, `.worktrees/`) while keeping `scripts/` and `ai_workspace/loop-agent/` on the shared commit surface; keep all user rules outside the block untouched.",
         "- Do not copy examples by default; examples stay bundled in the tool and are available through `loop-agent examples`.",
         "- Add or update a loop-agent managed block in AGENTS.md.",
         "- The generated AGENTS.md must include documentation convergence and structured DAG write-boundary rules so target projects keep the same working discipline as this repository.",
@@ -3382,7 +3329,7 @@ export async function runInitDoctor(input) {
         ? await readFile(gitignorePath, "utf-8")
         : "";
     add("gitignore loop-agent block", gitignoreContent.includes(GITIGNORE_BLOCK_START) &&
-        gitignoreContent.includes(".harness/tasks/*"), ".gitignore managed runtime ignores");
+        gitignoreContent.includes(".harness/"), ".gitignore managed runtime ignores");
     const requiredScripts = Object.keys(INIT_SCRIPT_FILES);
     const missingScripts = [];
     for (const script of requiredScripts) {

package/dist/commands/loop-benchmark.js

@@ -37,17 +37,17 @@ export function parseLoopBenchmarkArgs(args) {
     return { json, markdown, outputPath };
 }
 export function printLoopBenchmarkUsage() {
-    console.log(`usage: loop-benchmark [options]
-
-Deterministic loop-agent loop benchmark baseline (no live Pi/Cursor calls).
-
-Options:
-  --json              Emit JSON (default when no format flag is set)
-  --markdown          Emit Markdown report
-  --output <path>     Write Markdown report to a repo-relative or absolute path
-  -h, --help          Show this help
-
-Control groups: single-repair, 3-pass-convergence, 3-pass-convergence+quota.
+    console.log(`usage: loop-benchmark [options]
+
+Deterministic loop-agent loop benchmark baseline (no live Pi/Cursor calls).
+
+Options:
+  --json              Emit JSON (default when no format flag is set)
+  --markdown          Emit Markdown report
+  --output <path>     Write Markdown report to a repo-relative or absolute path
+  -h, --help          Show this help
+
+Control groups: single-repair, 3-pass-convergence, 3-pass-convergence+quota.
 Recommendation never changes convergence.enabled default.`);
 }
 export async function runLoopBenchmark(repoRoot, rawArgs) {