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

package/bin/loop-agent.js

@@ -1,21 +1,21 @@
-#!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const cliEntry = join(packageRoot, "dist", "cli.js");
-
-if (!existsSync(cliEntry)) {
-  console.error(
-    `loop-agent: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
-  );
-  process.exit(1);
-}
-
-try {
-  await import(pathToFileURL(cliEntry).href);
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-}
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const cliEntry = join(packageRoot, "dist", "cli.js");
+
+if (!existsSync(cliEntry)) {
+  console.error(
+    `loop-agent: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
+  );
+  process.exit(1);
+}
+
+try {
+  await import(pathToFileURL(cliEntry).href);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/dist/application/task-lifecycle/advance.js

@@ -1031,6 +1031,7 @@ export async function advanceTaskLifecycle(input) {
                     cwd: input.repoRoot,
                     initOnly: false,
                     dryRun: false,
+                    ...(input.observer ? { observer: input.observer } : {}),
                     ...(input.maxConcurrent !== undefined
                         ? { maxConcurrent: input.maxConcurrent }
                         : {}),

package/dist/commands/cursor-prompt.js

@@ -141,7 +141,7 @@ async function runCursorPromptBatch(task, cwd, model, timeoutMs) {
 }
 async function runCursorPromptStreaming(task, cwd, model, timeoutMs) {
     const startedAt = Date.now();
-    process.stderr.write(`[cursor-prompt] streaming (model=${model}, cwd=${cwd})
+    process.stderr.write(`[cursor-prompt] streaming (model=${model}, cwd=${cwd})
 `);
     const runDir = (await computeRunDir(cwd, task)) ?? undefined;
     const result = await executeCursorPromptStream({
@@ -164,15 +164,15 @@ async function runCursorPromptStreaming(task, cwd, model, timeoutMs) {
     });
     const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1);
     if (result.ok) {
-        process.stderr.write(`
-[cursor-prompt] done in ${elapsed}s, status=${result.status}
+        process.stderr.write(`
+[cursor-prompt] done in ${elapsed}s, status=${result.status}
 `);
     }
     else {
         const stderr = result.stderr || "(no output)";
-        process.stderr.write(`
-[cursor-prompt] FAILED in ${elapsed}s (${result.failureCategory}):
-${stderr}
+        process.stderr.write(`
+[cursor-prompt] FAILED in ${elapsed}s (${result.failureCategory}):
+${stderr}
 `);
         process.exit(1);
     }

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