xcoder-dna 0.0.0-stage → 1.3.1

package/dist/updater/index.js

@@ -0,0 +1,120 @@
+/** Auto-Update Module — §3.5 of design-desktop-installer.md */
+import { createWriteStream, createReadStream } from "node:fs";
+import { unlink, mkdir } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+function getPlatformExtension() {
+    switch (process.platform) {
+        case "win32": return "exe";
+        case "darwin": return "dmg";
+        case "linux": return "deb";
+        default: return "tar.gz";
+    }
+}
+function getPlatformSuffix() {
+    const pmap = { win32: "win", darwin: "macos", linux: "linux" };
+    const arch = process.arch === "arm64" ? "arm64" : "x64";
+    return `${pmap[process.platform] || process.platform}-${arch}`;
+}
+function semverCompare(a, b) {
+    const pa = a.replace(/^v/, "").split(".").map(Number);
+    const pb = b.replace(/^v/, "").split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const da = pa[i] || 0;
+        const db = pb[i] || 0;
+        if (da !== db)
+            return da - db;
+    }
+    return 0;
+}
+async function sha256stream(filePath) {
+    const hash = createHash("sha256");
+    const stream = createReadStream(filePath);
+    for await (const chunk of stream) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
+function runProcess(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(cmd, args, { stdio: "inherit" });
+        proc.on("close", (code) => {
+            code === 0 ? resolve() : reject(new Error(`${cmd} exited ${code}`));
+        });
+    });
+}
+export async function checkForUpdate(opts) {
+    const defaultValue = {
+        updateAvailable: false, latestVersion: null, downloadUrl: null, releaseNotes: null,
+    };
+    try {
+        const url = `https://api.github.com/repos/${opts.repo}/releases/latest`;
+        const response = await fetch(url, {
+            headers: {
+                Accept: "application/vnd.github+json",
+                "User-Agent": `xcoder-updater/${opts.currentVersion}`,
+            },
+        });
+        if (!response.ok)
+            return defaultValue;
+        const release = (await response.json());
+        const latestVersion = release.tag_name.replace(/^v/, "");
+        if (semverCompare(latestVersion, opts.currentVersion) <= 0) {
+            return { ...defaultValue, latestVersion };
+        }
+        const platformSuffix = getPlatformSuffix();
+        const ext = getPlatformExtension();
+        const assetPattern = `xcoder-${latestVersion}-${platformSuffix}.${ext}`;
+        const asset = release.assets.find((a) => a.name === assetPattern);
+        if (!asset) {
+            return { ...defaultValue, latestVersion, releaseNotes: release.body };
+        }
+        return {
+            updateAvailable: true,
+            latestVersion,
+            downloadUrl: asset.browser_download_url,
+            releaseNotes: release.body,
+        };
+    }
+    catch {
+        return defaultValue;
+    }
+}
+export async function downloadAndApplyUpdate(downloadUrl, sha256Url) {
+    const tmpDir = path.join(os.tmpdir(), "xcoder-update");
+    await mkdir(tmpDir, { recursive: true });
+    const ext = getPlatformExtension();
+    const installerPath = path.join(tmpDir, `xcoder-update.${ext}`);
+    try {
+        const response = await fetch(downloadUrl);
+        if (!response.ok) {
+            throw new Error(`Download failed: ${response.status}`);
+        }
+        const fileStream = createWriteStream(installerPath);
+        await pipeline(response.body, fileStream);
+        const shaResponse = await fetch(sha256Url);
+        if (shaResponse.ok) {
+            const expectedHash = (await shaResponse.text()).trim().split(/\s+/)[0];
+            const actualHash = await sha256stream(installerPath);
+            if (expectedHash !== actualHash) {
+                throw new Error(`SHA256 mismatch`);
+            }
+        }
+        if (process.platform === "win32") {
+            await runProcess(installerPath, ["/S"]);
+        }
+        else if (process.platform === "darwin") {
+            console.log(`Update downloaded to ${installerPath}`);
+            console.log(`Please open the DMG and copy Xcoder SDLC.app to /Applications.`);
+        }
+        else {
+            await runProcess("sudo", ["dpkg", "-i", installerPath]);
+        }
+    }
+    finally {
+        await unlink(installerPath).catch(() => { });
+    }
+}

package/dist/util/banner.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Write the full banner to stdout as one buffered frame.
+ *
+ * Unconditional — performs no gating (use maybePrintBanner for that). The
+ * content is a compile-time constant: no env var, path, model name, session id
+ * or other runtime data is ever interpolated, so terminal escape injection via
+ * this surface is structurally impossible.
+ */
+export declare function printBanner(): void;
+/**
+ * Whether the banner may be shown for this invocation.
+ *
+ * Pure predicate — no writes, no memoisation, safe to call repeatedly. Gate
+ * order is fixed and first hit wins; every ambiguity resolves to "no banner"
+ * because a false positive corrupts piped or machine-parseable output while a
+ * false negative costs one cosmetic line.
+ */
+export declare function isBannerEnabled(argv?: readonly string[]): boolean;
+/**
+ * Gated banner emission, at most once per process.
+ *
+ * @param argv token list inspected for suppressing flags; defaults to process.argv.
+ * @returns true if this call wrote a banner; false if suppressed or already printed.
+ */
+export declare function maybePrintBanner(argv?: readonly string[]): boolean;

package/dist/util/banner.js

@@ -0,0 +1,140 @@
+// xcoder:version 2 | xcoder:task task-46e4c0 | xcoder:updated 2026-10-25T16:36:43.632Z | xcoder:subtask code-st-1329b0
+// banner.ts — the Xcoder SDLC ASCII banner.
+//
+// Render manually with: npx tsx src/util/banner.ts
+//
+// This module is side-effect free at import time. Entry points call
+// maybePrintBanner() so the banner is gated (interactive stdout, --json,
+// --help/--version, --no-color, XCODER_NO_BANNER) and emitted at most once
+// per process.
+import { pathToFileURL } from "node:url";
+import { isInteractiveStdout } from "./tty.js";
+const FONT = {
+    X: ["██╗  ██╗", "╚██╗██╔╝", " ╚███╔╝ ", " ██╔██╗ ", "██╔╝ ██╗", "╚═╝  ╚═╝"],
+    C: [" ██████╗", "██╔════╝", "██║     ", "██║     ", "╚██████╗", " ╚═════╝"],
+    O: [" ██████╗ ", "██╔═══██╗", "██║   ██║", "██║   ██║", "╚██████╔╝", " ╚═════╝ "],
+    D: ["██████╗ ", "██╔══██╗", "██║  ██║", "██║  ██║", "██████╔╝", "╚═════╝ "],
+    E: ["███████╗", "██╔════╝", "█████╗  ", "██╔══╝  ", "███████╗", "╚══════╝"],
+    R: ["██████╗ ", "██╔══██╗", "██████╔╝", "██╔══██╗", "██║  ██║", "╚═╝  ╚═╝"],
+    S: ["███████╗", "██╔════╝", "███████╗", "╚════██║", "███████║", "╚══════╝"],
+    L: ["██╗     ", "██║     ", "██║     ", "██║     ", "███████╗", "╚══════╝"],
+    " ": ["    ", "    ", "    ", "    ", "    ", "    "],
+};
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const rgb = (r, g, b) => `\x1b[38;2;${r};${g};${b}m`;
+// Linear gradient between two RGB colors
+function lerp(a, b, t) {
+    return a.map((v, i) => Math.round(v + (b[i] - v) * t));
+}
+function render(text) {
+    const rows = Array(6).fill("");
+    for (const ch of text.toUpperCase()) {
+        const glyph = FONT[ch] ?? FONT[" "];
+        const width = Math.max(...glyph.map((l) => l.length));
+        glyph.forEach((line, i) => (rows[i] += line.padEnd(width)));
+    }
+    return rows;
+}
+function gradient(line, from, to) {
+    const chars = [...line];
+    return (chars
+        .map((c, i) => {
+        if (c === " ")
+            return c;
+        const [r, g, b] = lerp(from, to, i / Math.max(chars.length - 1, 1));
+        return `${rgb(r, g, b)}${c}`;
+    })
+        .join("") + RESET);
+}
+function center(text, width) {
+    const visible = text.replace(/\x1b\[[0-9;]*m/g, "");
+    const pad = Math.max(0, Math.floor((width - visible.length) / 2));
+    return " ".repeat(pad) + text;
+}
+/**
+ * Write the full banner to stdout as one buffered frame.
+ *
+ * Unconditional — performs no gating (use maybePrintBanner for that). The
+ * content is a compile-time constant: no env var, path, model name, session id
+ * or other runtime data is ever interpolated, so terminal escape injection via
+ * this surface is structurally impossible.
+ */
+export function printBanner() {
+    const cyan = [0, 229, 255];
+    const violet = [168, 85, 247];
+    const xcoder = render("XCODER");
+    const sdlc = render("SDLC");
+    const width = Math.max(...xcoder.map((l) => l.length), ...sdlc.map((l) => l.length));
+    const rule = rgb(...violet) + "═".repeat(width) + RESET;
+    const lines = ["", rule, ""];
+    for (const line of xcoder)
+        lines.push(gradient(line, cyan, violet));
+    lines.push("");
+    for (const line of sdlc)
+        lines.push(gradient(line, violet, cyan));
+    lines.push("", rule);
+    lines.push(center(`${BOLD}${rgb(0, 229, 255)}By Neural Node Labs${RESET}`, width));
+    lines.push(center(`${DIM}Sir John Nueva${RESET}`, width));
+    lines.push("");
+    // One write: cannot interleave with an ora spinner and is trivially testable.
+    process.stdout.write(lines.join("\n") + "\n");
+}
+/**
+ * Exact-token match (`--flag` or `--flag=value`), so a positional value that
+ * happens to contain a flag spelling cannot suppress the banner.
+ */
+function hasFlag(argv, ...names) {
+    return argv.some((arg) => names.includes(arg.split("=", 1)[0]));
+}
+/**
+ * Whether the banner may be shown for this invocation.
+ *
+ * Pure predicate — no writes, no memoisation, safe to call repeatedly. Gate
+ * order is fixed and first hit wins; every ambiguity resolves to "no banner"
+ * because a false positive corrupts piped or machine-parseable output while a
+ * false negative costs one cosmetic line.
+ */
+export function isBannerEnabled(argv = process.argv) {
+    // 1. Explicit operator opt-out wins over everything. Unset, empty, "0" and
+    //    "false" (case-insensitive) mean "not opted out"; any other value means
+    //    disabled — an operator should not have to guess a spelling.
+    const optOut = process.env.XCODER_NO_BANNER;
+    if (optOut !== undefined) {
+        const value = optOut.toLowerCase();
+        if (value !== "" && value !== "0" && value !== "false")
+            return false;
+    }
+    // 2. Machine-readable output must stay parseable (worker writes JSON to stdout).
+    if (hasFlag(argv, "--json"))
+        return false;
+    // 3. Help and version text is asserted verbatim.
+    if (hasFlag(argv, "--help", "-h", "--version", "-V"))
+        return false;
+    // 4. Read argv because `--no-color` only lands in process.env after parse.
+    if (hasFlag(argv, "--no-color"))
+        return false;
+    // 5. Pipes, redirection, CI and NO_COLOR.
+    return isInteractiveStdout();
+}
+let alreadyPrinted = false;
+/**
+ * Gated banner emission, at most once per process.
+ *
+ * @param argv token list inspected for suppressing flags; defaults to process.argv.
+ * @returns true if this call wrote a banner; false if suppressed or already printed.
+ */
+export function maybePrintBanner(argv = process.argv) {
+    if (alreadyPrinted)
+        return false;
+    if (!isBannerEnabled(argv))
+        return false;
+    printBanner();
+    alreadyPrinted = true;
+    return true;
+}
+// ESM self-run guard: `npx tsx src/util/banner.ts` must still render.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    printBanner();
+}

package/dist/util/command-suggester.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Given an unknown command name and a list of known commands, return up to
+ * `maxSuggestions` (default 3) closest matches sorted by Levenshtein distance
+ * then alphabetically, filtered to a maximum distance of `threshold` (default 3).
+ */
+export declare function suggestCommands(unknown: string, known: string[], maxSuggestions?: number, threshold?: number): string[];

package/dist/util/command-suggester.js

@@ -0,0 +1,25 @@
+// xcoder:version 1 | xcoder:task task-c776f2 | xcoder:updated 2026-08-03T19:28:41.385Z | xcoder:subtask code-st-5c254e
+import { levenshtein } from "./levenshtein.js";
+/**
+ * Given an unknown command name and a list of known commands, return up to
+ * `maxSuggestions` (default 3) closest matches sorted by Levenshtein distance
+ * then alphabetically, filtered to a maximum distance of `threshold` (default 3).
+ */
+export function suggestCommands(unknown, known, maxSuggestions = 3, threshold = 3) {
+    const target = unknown.toLowerCase();
+    const candidates = [];
+    for (const cmd of known) {
+        const distance = levenshtein(target, cmd);
+        if (distance <= threshold) {
+            candidates.push({ name: cmd, distance });
+        }
+    }
+    // Sort by distance ascending, then alphabetically by command name
+    candidates.sort((a, b) => {
+        if (a.distance !== b.distance) {
+            return a.distance - b.distance;
+        }
+        return a.name.localeCompare(b.name);
+    });
+    return candidates.slice(0, maxSuggestions).map((c) => c.name);
+}

package/dist/util/confirm-interrupt.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Display a Yes/No confirmation dialog using @clack/prompts.
+ *
+ * Callers are responsible for toggling raw mode on/off around the
+ * call — this utility assumes stdin is in cooked mode when called
+ * (Tradeoff 4: caller-owned lifecycle for clear ownership).
+ *
+ * @returns true if the user confirms Yes, false otherwise (including on cancel or error).
+ */
+export declare function confirmInterrupt(): Promise<boolean>;

package/dist/util/confirm-interrupt.js

@@ -0,0 +1,31 @@
+// xcoder:version 3 | xcoder:task task-0684a6 | xcoder:updated 2026-08-03T10:25:48.381Z | xcoder:subtask test-st-5ed700
+import * as clack from "@clack/prompts";
+/**
+ * Display a Yes/No confirmation dialog using @clack/prompts.
+ *
+ * Callers are responsible for toggling raw mode on/off around the
+ * call — this utility assumes stdin is in cooked mode when called
+ * (Tradeoff 4: caller-owned lifecycle for clear ownership).
+ *
+ * @returns true if the user confirms Yes, false otherwise (including on cancel or error).
+ */
+export async function confirmInterrupt() {
+    try {
+        const answer = await clack.confirm({
+            message: "Do you want to interrupt the current run?",
+            active: "Yes",
+            inactive: "No",
+            initialValue: false,
+        });
+        // clack.confirm returns boolean | symbol (for cancel)
+        if (clack.isCancel(answer)) {
+            return false;
+        }
+        // Coerce to strict boolean: true on Yes, false on anything else (No, null, undefined, etc.)
+        return Boolean(answer);
+    }
+    catch {
+        // If the prompt fails for any reason (e.g. non-TTY), default to not interrupting.
+        return false;
+    }
+}

package/dist/util/continue-trigger.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Matches the plain-language way people actually ask to keep going:
+ * "continue", "resume", "keep going", "carry on" — with or without more
+ * words after it ("continue on the UI", "continue write code"). This is
+ * what makes typing "continue" resume the actual unfinished task instead
+ * of Task Factory building a brand-new DAG from scratch and re-deriving
+ * requirements/design it already has — see `SdlcOrchestrator.resume()`.
+ * A referenced document supplies new task context and must go through
+ * normal task planning, even when the goal starts with "continue".
+ */
+export declare function isContinueTrigger(taskText: string): boolean;

package/dist/util/continue-trigger.js

@@ -0,0 +1,20 @@
+/**
+ * Matches the plain-language way people actually ask to keep going:
+ * "continue", "resume", "keep going", "carry on" — with or without more
+ * words after it ("continue on the UI", "continue write code"). This is
+ * what makes typing "continue" resume the actual unfinished task instead
+ * of Task Factory building a brand-new DAG from scratch and re-deriving
+ * requirements/design it already has — see `SdlcOrchestrator.resume()`.
+ * A referenced document supplies new task context and must go through
+ * normal task planning, even when the goal starts with "continue".
+ */
+export function isContinueTrigger(taskText) {
+    const text = taskText.trim();
+    if (!/^(continue|resume|keep going|carry on)\b/i.test(text))
+        return false;
+    // Anchor each whitespace-delimited token so a long non-path token is
+    // scanned once rather than retried at every character. Accept closing
+    // Markdown/quotation punctuation, but not suffixes such as .md.backup.
+    const referencesDocument = text.split(/\s+/).some((token) => /^\S+\.(?:md|mdx|txt|rst|pdf|docx?|ya?ml|json)["'`\])}>,;:.!?]*$/i.test(token));
+    return !referencesDocument;
+}

package/dist/util/env-info.d.ts

@@ -0,0 +1,18 @@
+export interface EnvironmentInfo {
+    platform: NodeJS.Platform;
+    isWindows: boolean;
+    shellHint: string;
+    pathSep: string;
+    release: string;
+}
+export declare function getEnvironmentInfo(): EnvironmentInfo;
+/**
+ * Injected into every Sub Agent's system prompt. This exists because a
+ * model that assumes `ls`, `grep`, `rm -rf`, `cat`, or unix path
+ * separators will happily emit a `run_command` action that fails outright
+ * on native Windows — and with no isolation around that failure, it looked
+ * like the agent "couldn't refactor" when it was actually just running the
+ * wrong shell dialect. Telling it up front, plus giving it glob/grep/edit
+ * tools that work identically on every platform, closes that gap.
+ */
+export declare function environmentPromptBlock(env: EnvironmentInfo): string;

package/dist/util/env-info.js

@@ -0,0 +1,37 @@
+import os from "node:os";
+export function getEnvironmentInfo() {
+    const platform = process.platform;
+    const isWindows = platform === "win32";
+    return {
+        platform,
+        isWindows,
+        pathSep: isWindows ? "\\" : "/",
+        release: os.release(),
+        shellHint: isWindows
+            ? "PowerShell or cmd.exe (unless run under WSL/Git Bash, in which case a real unix shell is available)"
+            : "a POSIX shell (bash/zsh/sh)",
+    };
+}
+/**
+ * Injected into every Sub Agent's system prompt. This exists because a
+ * model that assumes `ls`, `grep`, `rm -rf`, `cat`, or unix path
+ * separators will happily emit a `run_command` action that fails outright
+ * on native Windows — and with no isolation around that failure, it looked
+ * like the agent "couldn't refactor" when it was actually just running the
+ * wrong shell dialect. Telling it up front, plus giving it glob/grep/edit
+ * tools that work identically on every platform, closes that gap.
+ */
+export function environmentPromptBlock(env) {
+    const warning = env.isWindows
+        ? `You are running on Windows (${env.release}), most likely under ${env.shellHint}. ` +
+            `Unix-only commands (\`ls\`, \`grep\`, \`cat\`, \`rm -rf\`, \`&&\` chaining in cmd.exe, \`/\`-only paths) ` +
+            `may not exist or may behave differently here. Prefer the \`glob\`, \`grep\`, \`read_file\`, \`edit_file\`, ` +
+            `and \`write_file\` tools over shell equivalents for anything file-related — they work identically on every ` +
+            `platform. Only reach for \`run_command\` for things that genuinely need a real process (build/test/lint/` +
+            `type-check commands, git, package managers), and use PowerShell-compatible syntax when you do.`
+        : `You are running on ${env.platform} under ${env.shellHint}. Standard unix commands are available via ` +
+            `\`run_command\`, but still prefer \`glob\`/\`grep\`/\`read_file\`/\`edit_file\` over shelling out to ` +
+            `\`find\`/\`grep\`/\`cat\`/\`sed\` for file operations — they're faster, and their output is structured ` +
+            `instead of raw text you'd have to re-parse.`;
+    return `## Runtime environment\n${warning}`;
+}

package/dist/util/file-access-log.d.ts

@@ -0,0 +1,35 @@
+export type FileOp = "read" | "write" | "search" | "list" | "index" | "exec" | "git" | "skill" | "lesson";
+export interface FileAccess {
+    op: FileOp;
+    /** Workspace-relative path / glob (as the agent supplied it), or the command line. */
+    target: string;
+    kind: "path" | "glob" | "dir" | "cmd";
+}
+/** Strip obvious secrets before a command line is written to disk. */
+export declare function redactSecrets(text: string): string;
+/** Pure: map a tool name + input to the files/commands it touches. Never throws. */
+export declare function extractFileAccess(toolName: string, input: unknown): FileAccess[];
+/**
+ * Record one line per task run describing the index freshness gate.
+ *
+ * Reuses the existing `index` FileOp and the same log sink as every other
+ * tool call — the gate is observability, not a new datastore.
+ */
+export declare function logIndexRefresh(root: string, result: {
+    action: string;
+    reason: string;
+    counts?: {
+        added: number;
+        removed: number;
+        changed: number;
+    };
+    durationMs?: number;
+}, ctx?: {
+    taskId: string;
+    subtaskId: string;
+}): Promise<void>;
+/** Best-effort: write one `files.log` line per file/command the call touched. Never throws. */
+export declare function logFileAccess(root: string, toolName: string, input: unknown, ok: boolean, ctx?: {
+    taskId: string;
+    subtaskId: string;
+}): Promise<void>;

package/dist/util/file-access-log.js

@@ -0,0 +1,140 @@
+// xcoder:version 1 | xcoder:task task-e16f85 | xcoder:updated 2026-10-30T18:14:32.237Z | xcoder:subtask code-st-791be4
+// Describes which files / commands a tool call touches, for `files.log`.
+import { appendFiles } from "./logs.js";
+const MAX_CMD = 2000;
+/** Strip obvious secrets before a command line is written to disk. */
+export function redactSecrets(text) {
+    return text
+        .replace(/\b(?:sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/g, "[REDACTED]")
+        .replace(/(:\/\/[^\s:@/]+:)[^\s@/]+@/g, "$1[REDACTED]@")
+        .replace(/(authorization:\s*(?:bearer|basic)\s+)\S+/gi, "$1[REDACTED]")
+        .replace(/\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD)=)\S+/g, "$1[REDACTED]");
+}
+const str = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
+/** Pure: map a tool name + input to the files/commands it touches. Never throws. */
+export function extractFileAccess(toolName, input) {
+    const i = (input && typeof input === "object" ? input : {});
+    const out = [];
+    const path = (op, v, kind = "path") => {
+        const t = str(v);
+        if (t)
+            out.push({ op, target: t, kind });
+    };
+    switch (toolName) {
+        case "read_file":
+        case "read_outline":
+        case "read_full_file":
+        case "get_dependency_graph":
+        case "validate_file":
+            path("read", i.path);
+            break;
+        case "read_multiple_files":
+            if (Array.isArray(i.files))
+                for (const f of i.files)
+                    path("read", f?.path);
+            break;
+        case "write_file":
+        case "edit_file":
+        case "line_patch":
+        case "apply_unified_diff":
+        case "update_function":
+        case "rename_symbol":
+            path("write", i.path);
+            break;
+        case "sed_tool":
+            path("write", i.path);
+            path("write", i.glob, "glob");
+            break;
+        case "list_dir":
+            path("list", i.dir, "dir");
+            break;
+        case "glob":
+            path("search", i.pattern, "glob");
+            break;
+        case "grep":
+            path("search", i.pathGlob ?? "**/*", "glob");
+            break;
+        case "search_ast":
+            path("search", i.pathGlob ?? "**/*", "glob");
+            break;
+        case "search_workspace":
+        case "reindex_workspace":
+            out.push({ op: "index", target: ".", kind: "dir" });
+            break;
+        case "git_diff":
+        case "git_log":
+            out.push({ op: "git", target: str(i.path) ?? ".", kind: "path" });
+            break;
+        case "github_clone":
+            out.push({ op: "write", target: str(i.dir) ?? ".", kind: "dir" });
+            break;
+        case "github_commit":
+        case "github_push":
+            out.push({ op: "git", target: str(i.cwd) ?? ".", kind: "dir" });
+            break;
+        case "load_skill":
+            out.push({ op: "skill", target: str(i.role) ?? str(i.keyword) ?? "*", kind: "path" });
+            break;
+        case "record_lesson":
+            out.push({ op: "lesson", target: ".xcoder/lesson.md", kind: "path" });
+            break;
+        case "browse":
+            if (Array.isArray(i.steps)) {
+                for (const st of i.steps) {
+                    if (st?.op === "screenshot")
+                        out.push({ op: "write", target: str(st.path) ?? ".xcoder/screenshots", kind: str(st.path) ? "path" : "dir" });
+                }
+            }
+            break;
+        case "run_command":
+            path("exec", i.command, "cmd");
+            break;
+        case "schedule":
+            if (str(i.command))
+                path("exec", i.command, "cmd");
+            break;
+        default:
+            break;
+    }
+    return out;
+}
+function oneLine(s) {
+    return s.replace(/\r?\n/g, "\\n");
+}
+/**
+ * Record one line per task run describing the index freshness gate.
+ *
+ * Reuses the existing `index` FileOp and the same log sink as every other
+ * tool call — the gate is observability, not a new datastore.
+ */
+export async function logIndexRefresh(root, result, ctx) {
+    try {
+        const taskId = ctx?.taskId ?? "session";
+        const subtaskId = ctx?.subtaskId ?? "-";
+        const c = result.counts ?? { added: 0, removed: 0, changed: 0 };
+        const line = [
+            "tool=workspace_index op=index ok=true",
+            `dir=.,action=${result.action},reason=${result.reason}`,
+            `added=${c.added},removed=${c.removed},changed=${c.changed}`,
+            `durationMs=${result.durationMs ?? 0}`,
+        ].join(" ");
+        await appendFiles(root, taskId, subtaskId, oneLine(redactSecrets(line)));
+    }
+    catch {
+        // logging must never affect the task
+    }
+}
+/** Best-effort: write one `files.log` line per file/command the call touched. Never throws. */
+export async function logFileAccess(root, toolName, input, ok, ctx) {
+    try {
+        const taskId = ctx?.taskId ?? "session";
+        const subtaskId = ctx?.subtaskId ?? "-";
+        for (const a of extractFileAccess(toolName, input)) {
+            const field = a.kind === "cmd" ? `cmd=${oneLine(redactSecrets(a.target)).slice(0, MAX_CMD)}` : `${a.kind}=${oneLine(a.target)}`;
+            await appendFiles(root, taskId, subtaskId, `tool=${toolName} op=${a.op} ok=${ok} ${field}`);
+        }
+    }
+    catch {
+        // logging must never affect the tool call
+    }
+}