@zq-silk/yui 0.15.8 → 0.15.9

package/dist/artifacts/managedGit.js

@@ -0,0 +1,332 @@
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+const executeFile = promisify(execFile);
+/**
+ * Hardened, isolated Git runner for per-Task artifact repositories.
+ *
+ * Artifact repositories are local-only working stores for product files
+ * (plans, prototypes, charts, reports). Their contents are DATA authored by
+ * agents and, indirectly, by product material — never trusted to configure or
+ * drive the Git process. Every managed invocation therefore runs with a
+ * scrubbed environment and a fixed set of hardening options that:
+ *
+ *   - block ALL network/file transports (`protocol.allow=never`, and an
+ *     explicit `protocol.file.allow=never`), so no `fetch`/`clone`/`push`
+ *     can move bytes even if a rogue remote is configured;
+ *   - disable hooks (`core.hooksPath` → null device) so a committed hook
+ *     script can never execute;
+ *   - refuse to read user/system config or attributes
+ *     (`GIT_CONFIG_GLOBAL`/`GIT_CONFIG_SYSTEM` → null device,
+ *     `GIT_CONFIG_NOSYSTEM`, `GIT_ATTR_NOSYSTEM`), so external filters,
+ *     signing programs, pagers and editors cannot be injected;
+ *   - never prompt (`GIT_TERMINAL_PROMPT=0`, askpass disabled) and fail
+ *     closed on any transport helper (`GIT_SSH_COMMAND=false`);
+ *   - pin a fixed committer/author identity so commits succeed without
+ *     inheriting ambient user config.
+ *
+ * The runner also refuses caller-supplied `-c`/`-C`/`--exec`/`--upload-pack`/
+ * `--receive-pack` arguments: hardening flags are prepended here and callers
+ * pass only fixed subcommands with data after `--`, so there is no channel to
+ * pass through options that could re-enable transport or run a program.
+ */
+const NULL_DEVICE = process.platform === "win32" ? "NUL" : "/dev/null";
+/**
+ * Fixed option flags prepended to every managed invocation. These are applied
+ * before the subcommand and can never be overridden by repository-local config,
+ * because global/system config is disabled and no caller `-c` is accepted.
+ */
+const HARDENING_FLAGS = Object.freeze([
+    // Identity — commits succeed without ambient user config.
+    "-c", "user.name=Yui",
+    "-c", "user.email=yui@local",
+    // Transport — nothing may move over the network or the filesystem.
+    "-c", "protocol.allow=never",
+    "-c", "protocol.file.allow=never",
+    // Hooks / filters / external programs — no committed script may execute.
+    "-c", `core.hooksPath=${NULL_DEVICE}`,
+    "-c", "core.fsmonitor=false",
+    "-c", "core.pager=cat",
+    "-c", "core.editor=false",
+    // Signing — never shell out to a signing program.
+    "-c", "commit.gpgsign=false",
+    "-c", "tag.gpgsign=false",
+    // Determinism / quiet.
+    "-c", "core.autocrlf=false",
+    "-c", "gc.auto=0",
+    "-c", "advice.detachedHead=false"
+]);
+/** Arguments a caller may never pass: they could re-enable transport or run a program. */
+const FORBIDDEN_ARGUMENTS = Object.freeze([
+    "-c", "-C", "--exec-path", "--upload-pack", "--receive-pack", "--exec"
+]);
+/** Raised when a managed Git command exits non-zero. Carries the exact stderr. */
+export class ManagedGitError extends Error {
+    stderr;
+    args;
+    constructor(args, stderr, cause) {
+        super(stderr.length === 0 ? "Managed git command failed." : `Managed git command failed: ${stderr}`, { cause });
+        this.name = "ManagedGitError";
+        this.stderr = stderr;
+        this.args = args;
+    }
+}
+/** Build the scrubbed environment for a managed Git process. Never inherits ambient Git config. */
+function managedGitEnvironment() {
+    return {
+        // A minimal, deterministic PATH so `git` (and only trusted helpers) resolve.
+        PATH: process.env.PATH ?? "/usr/bin:/bin",
+        LANG: "C.UTF-8",
+        LC_ALL: "C.UTF-8",
+        // A neutral HOME keeps any accidental lookup inside a controlled area; config
+        // lookups are already redirected to the null device below.
+        HOME: process.platform === "win32" ? (process.env.USERPROFILE ?? "") : "/nonexistent",
+        GIT_CONFIG_NOSYSTEM: "1",
+        GIT_CONFIG_GLOBAL: NULL_DEVICE,
+        GIT_CONFIG_SYSTEM: NULL_DEVICE,
+        GIT_ATTR_NOSYSTEM: "1",
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_ASKPASS: "",
+        SSH_ASKPASS: "",
+        GIT_SSH_COMMAND: "false",
+        GIT_PROTOCOL_FROM_USER: "0",
+        GIT_OPTIONAL_LOCKS: "0",
+        // Every pathspec is a literal path, never a glob. A file legitimately named
+        // `*.md` or `a?.md` must commit exactly itself and never sweep in undeclared
+        // sibling changes; this makes `add`/`diff`/`commit --only` scope uniformly
+        // and can never re-enable transport or run a program.
+        GIT_LITERAL_PATHSPECS: "1",
+        GIT_PAGER: "cat",
+        GIT_EDITOR: "false",
+        // Fixed identity as a second guarantee alongside the -c flags.
+        GIT_AUTHOR_NAME: "Yui",
+        GIT_AUTHOR_EMAIL: "yui@local",
+        GIT_COMMITTER_NAME: "Yui",
+        GIT_COMMITTER_EMAIL: "yui@local"
+    };
+}
+function assertSafeArguments(args) {
+    for (const arg of args) {
+        if (typeof arg !== "string")
+            throw new Error("Managed git argument must be a string.");
+        if (arg.includes("\0"))
+            throw new Error("Managed git argument contains a NUL byte.");
+        if (FORBIDDEN_ARGUMENTS.includes(arg)) {
+            throw new Error(`Managed git argument is not permitted: ${arg}.`);
+        }
+    }
+}
+/**
+ * Core managed invocation. `-C repoPath` and the hardening flags are supplied
+ * here; `args` carries only the subcommand and its data. Returns raw stdout and
+ * stderr buffers; throws {@link ManagedGitError} on non-zero exit.
+ */
+async function spawnManagedGit(repoPath, args, options) {
+    assertSafeArguments(args);
+    try {
+        const result = await executeFile("git", [...HARDENING_FLAGS, "-C", repoPath, ...args], {
+            encoding: "buffer",
+            env: managedGitEnvironment(),
+            maxBuffer: options?.maxBuffer ?? 16 * 1024 * 1024,
+            timeout: options?.timeoutMs ?? 30_000,
+            windowsHide: true
+        });
+        return { stdout: result.stdout, stderr: result.stderr };
+    }
+    catch (error) {
+        const stderr = readErrorStream(error);
+        throw new ManagedGitError([...args], stderr, error);
+    }
+}
+function readErrorStream(error) {
+    if (typeof error === "object" && error !== null && "stderr" in error) {
+        const stderr = error.stderr;
+        if (Buffer.isBuffer(stderr))
+            return stderr.toString("utf8").trim();
+        if (typeof stderr === "string")
+            return stderr.trim();
+    }
+    return "";
+}
+/** Run a managed Git command and return trimmed UTF-8 stdout. Throws on failure. */
+export async function managedGit(repoPath, args, options) {
+    const { stdout } = await spawnManagedGit(repoPath, args, options);
+    return stdout.toString("utf8");
+}
+/** Run a managed Git command and return raw stdout bytes (for reading blob content). Throws on failure. */
+export async function managedGitBuffer(repoPath, args, options) {
+    const { stdout } = await spawnManagedGit(repoPath, args, options);
+    return stdout;
+}
+/** Run a managed Git command purely for its exit status; never throws on non-zero. */
+export async function managedGitSucceeds(repoPath, args, options) {
+    try {
+        await spawnManagedGit(repoPath, args, options);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof ManagedGitError)
+            return false;
+        throw error;
+    }
+}
+/** Validate and normalize a Git object id from managed output (40- or 64-hex). */
+export function requireCommitId(value) {
+    const commit = value.trim();
+    if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u.test(commit)) {
+        throw new Error("Managed git returned an invalid commit id.");
+    }
+    return commit;
+}
+/**
+ * Repo-local config keys that can make Git execute an EXTERNAL PROGRAM during an
+ * ordinary `add`/`diff`/`commit`/`show` — the vector env-scrubbing does not close.
+ *
+ * Disabling global/system config (see {@link managedGitEnvironment}) stops
+ * ambient filters/hooks, but a repository's OWN `.git/config` is always read, and
+ * a `[filter "x"] clean = <cmd>` there (paired with a worktree `.gitattributes`
+ * `* filter=x`) runs `<cmd>` on `git add`. Some keys (`core.pager`, hooks, signing)
+ * are already forced to safe values by the `-c` {@link HARDENING_FLAGS}, but an
+ * arbitrarily NAMED filter/alias/tool driver cannot be overridden by a fixed `-c`.
+ *
+ * Yui configures NONE of these on a managed artifact repository, so any that
+ * appear in repo-local config are external tampering. We DETECT and STOP (like an
+ * unexpected remote); we never silently delete the config or try to out-configure
+ * an arbitrary command. Keys are matched case-insensitively (Git config is).
+ *
+ * The direct scan sees only repo-local keys, so it also rejects the config
+ * INCLUSION entry points (`include.*`, `includeIf.*`, `extensions.worktreeConfig`)
+ * that could otherwise hide any of the below in a file this scan never opens —
+ * see {@link isExternalProgramConfigKey}.
+ */
+const EXTERNAL_PROGRAM_CONFIG_SUFFIXES = Object.freeze([
+    ".clean", ".smudge", ".process", // filter.<name>.*
+    ".command", ".textconv", ".cmd", // diff/difftool/mergetool.<name>.*
+    ".driver", // merge.<name>.driver
+    ".helper" // credential[.<url>].helper
+]);
+const EXTERNAL_PROGRAM_CONFIG_PREFIXES = Object.freeze([
+    "filter.", "alias.", "difftool.", "mergetool.", "pager.",
+    "sendemail.", "instaweb.", "guitool.", "credential.", "url.",
+    "browser.", "man.", "hooks."
+]);
+const EXTERNAL_PROGRAM_CONFIG_KEYS = new Set([
+    "diff.external",
+    "core.pager", "core.editor", "core.sshcommand", "core.askpass",
+    "core.gitproxy", "core.fsmonitor", "core.hookspath", "core.alternaterefscommand",
+    "gpg.program", "gpg.openpgp.program", "gpg.x509.program", "gpg.ssh.program",
+    "sequence.editor", "uploadpack.packobjectshook",
+    "web.browser", "help.browser"
+]);
+/**
+ * Config keys that IMPORT or ENABLE another config scope. `git config --local
+ * --list -z` lists these keys but does NOT expand them, so a `filter.*.clean`
+ * hidden inside an included file (or the per-worktree config) is invisible to
+ * the direct external-program scan above — yet an ordinary `git add`/`status`
+ * DOES follow includes and would run that hidden filter. A managed artifact
+ * repository never needs an include or a per-worktree config, so we reject the
+ * ENTRY POINT itself rather than parsing the (arbitrary, possibly nested)
+ * included files: `include.path`, any `includeIf.<condition>.path`, and the
+ * `extensions.worktreeConfig` switch that activates `.git/config.worktree`.
+ * Keys are already lower-cased by Git config.
+ */
+const CONFIG_INCLUSION_CONFIG_PREFIXES = Object.freeze([
+    "include.", "includeif."
+]);
+const CONFIG_INCLUSION_CONFIG_KEYS = new Set([
+    "extensions.worktreeconfig"
+]);
+function isExternalProgramConfigKey(key) {
+    if (EXTERNAL_PROGRAM_CONFIG_KEYS.has(key))
+        return true;
+    for (const prefix of EXTERNAL_PROGRAM_CONFIG_PREFIXES)
+        if (key.startsWith(prefix))
+            return true;
+    for (const suffix of EXTERNAL_PROGRAM_CONFIG_SUFFIXES)
+        if (key.endsWith(suffix))
+            return true;
+    // A config-inclusion / alternate-scope entry point can smuggle any of the
+    // above in a file this direct scan never opens; reject the entry point itself.
+    if (CONFIG_INCLUSION_CONFIG_KEYS.has(key))
+        return true;
+    for (const prefix of CONFIG_INCLUSION_CONFIG_PREFIXES)
+        if (key.startsWith(prefix))
+            return true;
+    return false;
+}
+/**
+ * Given the raw stdout of `git config --local --list -z` (records of the form
+ * `key\nvalue\0`, keys already lower-cased by Git), return the sorted, de-duped
+ * list of repo-local keys that can execute an external program. Empty means the
+ * repository's own config is within the managed boundary.
+ *
+ * PURE: no I/O. Callers (sync migration and async runtime) read the config with
+ * their own managed runner and pass the bytes here, so the security policy lives
+ * in exactly one testable place. Reading `--local` deliberately excludes the
+ * command-line `-c` hardening flags (which are safe and not persisted) and the
+ * null-device'd global/system config; it sees only what is written in the repo.
+ */
+export function externalProgramConfigViolations(localConfigListZ) {
+    const offending = new Set();
+    for (const record of localConfigListZ.split("\0")) {
+        if (record.length === 0)
+            continue;
+        const newline = record.indexOf("\n");
+        const key = (newline < 0 ? record : record.slice(0, newline)).toLowerCase();
+        if (isExternalProgramConfigKey(key))
+            offending.add(key);
+    }
+    return [...offending].sort();
+}
+/**
+ * SYNCHRONOUS managed invocation, used ONLY where an async runner is
+ * structurally impossible: a storage `migrateData(db)` step runs inside
+ * `db.transaction(...)`, which better-sqlite3 requires to be synchronous, yet
+ * the 18->19 migration must build per-Task artifact repositories on disk. This
+ * shares the SAME hardening as {@link spawnManagedGit} — identical argument
+ * refusal, identical scrubbed environment, identical prepended flags — so the
+ * synchronous path never weakens the trust boundary. It is not exported for
+ * ordinary runtime use; the async runner remains the only production write path.
+ */
+function spawnManagedGitSync(repoPath, args, options) {
+    assertSafeArguments(args);
+    const env = managedGitEnvironment();
+    if (options?.commitDates !== undefined) {
+        // Deterministic history: fixed author/committer dates make a rebuild of the
+        // same source data reproduce the same commit ids. This only sets metadata.
+        env.GIT_AUTHOR_DATE = options.commitDates.author;
+        env.GIT_COMMITTER_DATE = options.commitDates.committer;
+    }
+    try {
+        const stdout = execFileSync("git", [...HARDENING_FLAGS, "-C", repoPath, ...args], {
+            encoding: "buffer",
+            env,
+            maxBuffer: options?.maxBuffer ?? 16 * 1024 * 1024,
+            timeout: options?.timeoutMs ?? 30_000,
+            windowsHide: true
+        });
+        return { stdout: stdout, stderr: Buffer.alloc(0) };
+    }
+    catch (error) {
+        throw new ManagedGitError([...args], readErrorStream(error), error);
+    }
+}
+/** Synchronous counterpart to {@link managedGit}; returns trimmed UTF-8 stdout. */
+export function managedGitSync(repoPath, args, options) {
+    return spawnManagedGitSync(repoPath, args, options).stdout.toString("utf8");
+}
+/** Synchronous counterpart to {@link managedGitBuffer}; returns raw stdout bytes. */
+export function managedGitSyncBuffer(repoPath, args, options) {
+    return spawnManagedGitSync(repoPath, args, options).stdout;
+}
+/** Synchronous counterpart to {@link managedGitSucceeds}; never throws on non-zero exit. */
+export function managedGitSyncSucceeds(repoPath, args, options) {
+    try {
+        spawnManagedGitSync(repoPath, args, options);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof ManagedGitError)
+            return false;
+        throw error;
+    }
+}

package/dist/artifacts/taskArtifactRepository.js

@@ -0,0 +1,277 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { ManagedGitError, externalProgramConfigViolations, managedGit, managedGitBuffer, managedGitSucceeds, requireCommitId } from "./managedGit.js";
+import { acquireArtifactCommitLock } from "./artifactCommitLock.js";
+import { resolveContainedArtifactPath, safeRelativeArtifactPath, taskArtifactRepoPath } from "./artifactPaths.js";
+/**
+ * Per-Task local-only Git artifact repository.
+ *
+ * This is the authority for a Task's file/directory artifacts: complete plans,
+ * prototypes, charts, reports and other multi-file material. It is a plain
+ * local Git repository under `<YUI_HOME>/task-artifacts/<task-id>/` with:
+ *
+ *   - NO remote of any kind (network or file). A remote appearing in the repo
+ *     is treated as an external violation: {@link assertNoRemote} reports it and
+ *     stops managed writes; the configuration is never silently removed.
+ *   - a hardened, isolated Git subprocess (see {@link managedGit}) that cannot
+ *     reach the network, run hooks/filters, or read ambient user/system config.
+ *   - fixed committer identity and an empty root commit, so HEAD always exists
+ *     and per-path scoped commits work uniformly from the first real save.
+ *
+ * Save model (§3.4): write file(s) → validate scope → local commit → saved.
+ * A successful commit IS the save; there is no DB round-trip on the write path.
+ * Uncommitted changes are work-in-progress. A commit failure preserves the
+ * files exactly and surfaces the precise error — nothing is reset or cleaned.
+ * One meaningful update is one commit. A short per-Task lock plus an
+ * expected-HEAD check make concurrent saves safe; a conflict STOPS (no
+ * overwrite, no auto-merge). Branches/PRs/rebase are never exposed.
+ *
+ * Artifacts are savable from the Draft stage: this store depends only on the
+ * Home, never on an active delivery workspace or Project checkout.
+ */
+/** The single managed branch. Never surfaced to callers as a Git concept. */
+const ARTIFACT_BRANCH = "main";
+/** Upper bound for a single artifact file, mirroring the immutable-artifact cap. */
+const MAX_ARTIFACT_BYTES = 8 * 1024 * 1024;
+/** Raised when an artifact repository has a remote configured — an external violation. */
+export class ArtifactRemoteViolationError extends Error {
+    taskId;
+    remotes;
+    constructor(taskId, remotes) {
+        super(`Artifact repository for ${taskId} has an external remote configured (${remotes.join(", ")}); ` +
+            `managed writes are stopped. Remove the remote manually to resume.`);
+        this.name = "ArtifactRemoteViolationError";
+        this.taskId = taskId;
+        this.remotes = [...remotes];
+    }
+}
+/**
+ * Raised when an artifact repository's OWN config declares a filter/alias/tool
+ * that would run an external program during add/diff/commit. Env-scrubbing hides
+ * ambient config, but a repo's `.git/config` is always read; Yui configures none
+ * of these, so any that appear are external tampering. Like a remote: report and
+ * STOP managed writes, never silently delete the config.
+ */
+export class ArtifactManagedConfigViolationError extends Error {
+    taskId;
+    keys;
+    constructor(taskId, keys) {
+        super(`Artifact repository for ${taskId} has repo-local Git config that can run external ` +
+            `programs (${keys.join(", ")}); managed writes are stopped. Remove it manually to resume.`);
+        this.name = "ArtifactManagedConfigViolationError";
+        this.taskId = taskId;
+        this.keys = [...keys];
+    }
+}
+/** Raised when a save's expected HEAD no longer matches — a concurrent update won. */
+export class ArtifactHeadConflictError extends Error {
+    taskId;
+    expectedHead;
+    actualHead;
+    retryable = true;
+    constructor(taskId, expectedHead, actualHead) {
+        super(`Artifact repository for ${taskId} advanced since it was read ` +
+            `(expected ${expectedHead}, found ${actualHead}); no changes were made. Re-read and retry.`);
+        this.name = "ArtifactHeadConflictError";
+        this.taskId = taskId;
+        this.expectedHead = expectedHead;
+        this.actualHead = actualHead;
+    }
+}
+/**
+ * Open (not necessarily create) the artifact repository for a Task. The repo
+ * path is derived directly from the Home; call {@link TaskArtifactRepository.ensure}
+ * before the first save. `home` MUST be the resolved YUI_HOME
+ * (e.g. `store.rootDirectory()`), so ownership is derived from the Task, never
+ * from ambient state.
+ */
+export function openTaskArtifactRepository(home, taskId) {
+    const repoPath = taskArtifactRepoPath(home, taskId);
+    const exists = () => existsSync(join(repoPath, ".git"));
+    const head = async () => {
+        if (!exists())
+            return null;
+        return currentHead(repoPath);
+    };
+    const ensure = async () => {
+        if (exists()) {
+            await assertNoRemote(taskId, repoPath);
+            return;
+        }
+        await mkdir(repoPath, { recursive: true, mode: 0o700 });
+        await managedGit(repoPath, ["init", "-b", ARTIFACT_BRANCH]);
+        // An empty root commit guarantees HEAD exists, so scoped per-path commits
+        // and expected-HEAD checks work uniformly from the very first save.
+        await managedGit(repoPath, ["commit", "--allow-empty", "-m", "init artifact repo"]);
+        await assertNoRemote(taskId, repoPath);
+    };
+    const save = async (input) => {
+        if (input.files.length === 0) {
+            throw new Error("An artifact save must include at least one file.");
+        }
+        // Validate the whole request up front (fail-fast): a caller error must never
+        // leave half-written files behind. Only genuine Git failures after this
+        // point exercise the preserve-on-failure path.
+        const message = requireMessage(input.message);
+        const prepared = input.files.map((file) => {
+            const relativePath = safeRelativeArtifactPath(file.relativePath);
+            if (!Buffer.isBuffer(file.bytes)) {
+                throw new Error(`Artifact ${relativePath} bytes must be a Buffer.`);
+            }
+            if (file.bytes.byteLength > MAX_ARTIFACT_BYTES) {
+                throw new Error(`Artifact ${relativePath} exceeds the ${MAX_ARTIFACT_BYTES}-byte limit.`);
+            }
+            return { relativePath, bytes: file.bytes };
+        });
+        // Reject duplicate targets in one save — ambiguous intent.
+        const seen = new Set();
+        for (const file of prepared) {
+            if (seen.has(file.relativePath)) {
+                throw new Error(`Artifact ${file.relativePath} appears more than once in one save.`);
+            }
+            seen.add(file.relativePath);
+        }
+        await ensure();
+        const release = acquireArtifactCommitLock(home, taskId);
+        try {
+            await assertNoRemote(taskId, repoPath);
+            // Expected-HEAD check under the lock: a conflict stops without writing.
+            if (input.expectedHead !== undefined) {
+                const actual = await currentHead(repoPath);
+                if (actual !== input.expectedHead) {
+                    throw new ArtifactHeadConflictError(taskId, input.expectedHead, actual);
+                }
+            }
+            // Write files first. A commit failure below preserves exactly these bytes;
+            // nothing is reset or cleaned, so a caller can inspect and retry.
+            for (const file of prepared) {
+                const absolute = await resolveContainedArtifactPath(repoPath, file.relativePath);
+                await mkdir(dirname(absolute), { recursive: true, mode: 0o700 });
+                await writeFile(absolute, file.bytes, { mode: 0o600 });
+            }
+            const pathspecs = prepared.map((file) => file.relativePath);
+            // Stage exactly the saved paths so new files become known to Git...
+            await managedGit(repoPath, ["add", "--", ...pathspecs]);
+            // ...but if nothing actually changed, do not create an empty commit.
+            const noChanges = await managedGitSucceeds(repoPath, [
+                "diff", "--cached", "--quiet", "--", ...pathspecs
+            ]);
+            if (noChanges) {
+                return { taskId, commit: await currentHead(repoPath), savedPaths: pathspecs };
+            }
+            // `--only <paths>` records exactly these paths; any other WIP stays WIP.
+            await managedGit(repoPath, ["commit", "--only", "-m", message, "--", ...pathspecs]);
+            return { taskId, commit: await currentHead(repoPath), savedPaths: pathspecs };
+        }
+        finally {
+            release();
+        }
+    };
+    const read = async (relativePath, commit) => {
+        const safeRelative = safeRelativeArtifactPath(relativePath);
+        // A pinned commit reads frozen evidence; otherwise read the current HEAD.
+        // Both resolve `<commit>:<path>`, an OBJECT spec (never the working tree, so
+        // a read never follows a symlink or sees unrelated WIP).
+        const pinned = commit === undefined ? await currentHead(repoPath) : requireCommitId(commit);
+        const objectSpec = `${pinned}:${safeRelative}`;
+        // `<commit>:<path>` for a DIRECTORY resolves to a tree, and `git show` would
+        // print a tree listing rather than fail — silently returning directory
+        // metadata as if it were file bytes. Verify the object is a blob first, so a
+        // read only ever yields real file content.
+        const objectType = (await managedGit(repoPath, ["cat-file", "-t", objectSpec]).catch((error) => {
+            if (error instanceof ManagedGitError) {
+                throw new Error(`Artifact ${safeRelative} is unavailable at ${pinned}.`, { cause: error });
+            }
+            throw error;
+        })).trim();
+        if (objectType !== "blob") {
+            throw new Error(`Artifact ${safeRelative} at ${pinned} is not a file (${objectType}).`);
+        }
+        const bytes = await managedGitBuffer(repoPath, ["cat-file", "blob", objectSpec], {
+            maxBuffer: MAX_ARTIFACT_BYTES + 4096
+        }).catch((error) => {
+            if (error instanceof ManagedGitError) {
+                throw new Error(`Artifact ${safeRelative} is unavailable at ${pinned}.`, { cause: error });
+            }
+            throw error;
+        });
+        return {
+            relativePath: safeRelative,
+            commit: pinned,
+            bytes,
+            digest: createHash("sha256").update(bytes).digest("hex")
+        };
+    };
+    const list = async (commit) => {
+        if (!exists())
+            return [];
+        const pinned = commit === undefined ? await currentHead(repoPath) : requireCommitId(commit);
+        const output = await managedGit(repoPath, [
+            "ls-tree", "-r", "-z", "--long", "--full-tree", pinned
+        ]);
+        const entries = [];
+        for (const record of output.split("\0").filter(Boolean)) {
+            // Format: "<mode> <type> <object> <size>\t<path>"
+            const tab = record.indexOf("\t");
+            if (tab < 0)
+                continue;
+            const meta = record.slice(0, tab).split(/\s+/u);
+            const path = record.slice(tab + 1);
+            const size = Number.parseInt(meta[3] ?? "", 10);
+            if (path === ".gitignore")
+                continue;
+            entries.push({ relativePath: path, size: Number.isFinite(size) ? size : 0 });
+        }
+        return entries;
+    };
+    const workingChanges = async () => {
+        if (!exists())
+            return [];
+        const output = await managedGit(repoPath, [
+            "status", "--porcelain=v1", "--untracked-files=all", "-z"
+        ]);
+        // Porcelain v1 -z records: "XY <path>\0" (rename adds a second \0 field).
+        const changes = [];
+        for (const record of output.split("\0").filter(Boolean)) {
+            const path = record.slice(3);
+            if (path.length > 0)
+                changes.push(path);
+        }
+        return changes;
+    };
+    return { taskId, repoPath, ensure, exists, head, save, read, list, workingChanges };
+}
+async function currentHead(repoPath) {
+    return requireCommitId(await managedGit(repoPath, ["rev-parse", "HEAD^{commit}"]));
+}
+/**
+ * Verify the repository is within the managed boundary before a write: NO remote
+ * (network or file sync) AND no repo-local config that can execute an external
+ * program on add/diff/commit. Both are external violations — we report and stop,
+ * never silently remove them.
+ */
+async function assertNoRemote(taskId, repoPath) {
+    const output = await managedGit(repoPath, ["remote"]);
+    const remotes = output.split("\n").map((line) => line.trim()).filter(Boolean);
+    if (remotes.length > 0) {
+        throw new ArtifactRemoteViolationError(taskId, remotes);
+    }
+    // A repo's own `.git/config` is read even with global/system config disabled,
+    // so a committed `.gitattributes` filter paired with a repo-local
+    // `filter.<n>.clean = <cmd>` would run `<cmd>` on `git add`. Detect and stop.
+    const configListZ = await managedGit(repoPath, ["config", "--local", "--list", "-z"]);
+    const violations = externalProgramConfigViolations(configListZ);
+    if (violations.length > 0) {
+        throw new ArtifactManagedConfigViolationError(taskId, violations);
+    }
+}
+function requireMessage(message) {
+    const trimmed = typeof message === "string" ? message.trim() : "";
+    if (trimmed.length === 0)
+        throw new Error("An artifact save requires a commit message.");
+    if (trimmed.startsWith("-"))
+        throw new Error("An artifact commit message may not begin with a dash.");
+    return trimmed;
+}

package/dist/cli/commandCatalog.js

@@ -380,12 +380,12 @@ const taskChildren = [
     { name: "show", summary: "Show a Task.", usage: "yui task show <id>" },
     {
         name: "artifact",
-        summary: "Save fixed Task results and read history without the original Runtime.",
-        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "save"] }],
+        summary: "Save Task files in local Git and read current or commit-pinned content.",
+        sections: [{ id: "manage", title: "Commands", entries: ["list", "read", "save"] }],
         children: [
             { name: "list", summary: "List saved Task artifacts.", usage: "yui task artifact list <task>" },
-            { name: "show", summary: "Read one saved artifact.", usage: "yui task artifact show <task> <artifact-id>" },
-            { name: "save", summary: "Save content, a version, receipt, or reference.", usage: "yui task artifact save <task> <artifact-json>" }
+            { name: "read", summary: "Read a file at HEAD or an exact commit.", usage: "yui task artifact read <task> <relative-path> [<commit>]" },
+            { name: "save", summary: "Save and locally commit one file.", usage: "yui task artifact save <task> <relative-path> <content> [--message <text>] [--expected-head <commit>]", options: ["--message", "--expected-head"] }
         ]
     },
     {
@@ -445,10 +445,11 @@ const taskChildren = [
             },
             {
                 name: "send",
-                summary: "Send a Task message.",
-                usage: "yui task message send <id> (<body>|--body-file <path|->) [--wake-policy leader|none] [--to <role> --work-item <id>|--review-round <id>]",
-                options: ["--body-file", "--wake-policy", "--to", "--work-item", "--review-round"],
+                summary: "Send a Task message. An unaddressed user/operator message carries a submission intent (record|discuss|develop) and an optional idempotency key.",
+                usage: "yui task message send <id> (<body>|--body-file <path|->) [--intent record|discuss|develop] [--request-id <key>] [--wake-policy leader|none] [--to <role> --work-item <id>|--review-round <id>]",
+                options: ["--body-file", "--intent", "--request-id", "--wake-policy", "--to", "--work-item", "--review-round"],
                 optionValues: {
+                    "--intent": ["record", "discuss", "develop"],
                     "--wake-policy": ["leader", "none"]
                 },
                 fileOptions: ["--body-file"]
@@ -1286,9 +1287,12 @@ export const ROOT_COMMAND = buildNode({
                 },
                 {
                     name: "submit",
-                    summary: "Submit work through the Operator.",
-                    usage: "yui operator submit (<body>|--body-file <path|->) [--task <id>]",
-                    options: ["--task", "--body-file"],
+                    summary: "Submit work through the Operator with a submission intent (record|discuss|develop); a task-less submit opens a Draft. An optional idempotency key makes a retry safe.",
+                    usage: "yui operator submit (<body>|--body-file <path|->) [--task <id>] [--intent record|discuss|develop] [--request-id <key>]",
+                    options: ["--task", "--body-file", "--intent", "--request-id"],
+                    optionValues: {
+                        "--intent": ["record", "discuss", "develop"]
+                    },
                     fileOptions: ["--body-file"]
                 }
             ]