@nanhara/hara 0.127.2 → 0.129.0

package/dist/context/workspace-scope.js

@@ -56,6 +56,29 @@ export function homeWorkspaceGuidance(cwd) {
         "Ask the user to switch with `/cd /path/to/project`, run `cd /path/to/project`, or launch with " +
         "`hara --cwd /path/to/project` for project work. Only explicitly named single-file reads remain available.");
 }
+/** Pick the first existing project directory from an already-authorized candidate list. This deliberately
+ * does not enumerate Home: callers supply recent-session or registered-project paths, and the user still
+ * confirms the handoff before Hara changes process.cwd(). */
+export function suggestedProjectWorkspace(candidates, home = effectiveHomeDir()) {
+    const seen = new Set();
+    for (const candidate of candidates) {
+        if (typeof candidate !== "string" || !candidate.trim())
+            continue;
+        try {
+            const target = realpathSync.native(resolve(candidate));
+            if (seen.has(target))
+                continue;
+            seen.add(target);
+            if (!statSync(target).isDirectory() || isUnsafeProjectWorkspace(target, home))
+                continue;
+            return target;
+        }
+        catch {
+            // Stale session/project registrations are ordinary; skip them without weakening the boundary.
+        }
+    }
+    return undefined;
+}
 /** Resolve an explicit interactive workspace handoff without accepting Home/ancestor scopes. */
 export function resolveWorkspaceSwitch(input, currentCwd, home = effectiveHomeDir()) {
     let requested = input.trim();

package/dist/gateway/feishu.js

@@ -12,6 +12,60 @@ const lark = (larkNs.default ?? larkNs);
 import { chunkText, outboundTransferTimeoutMs, PerChatOutboundLane, withOutboundDeadline, } from "./telegram.js";
 import { InboundMediaBudget, cleanupTransientMedia, savePrivateResponse } from "./media.js";
 import { GatewayEventSpool, gatewayRuntimeScope } from "./runtime-state.js";
+import { redactKnownSecrets } from "../security/secrets.js";
+const FEISHU_WS_HOUR_MS = 60 * 60_000;
+const FEISHU_WS_DAY_MS = 24 * FEISHU_WS_HOUR_MS;
+const FEISHU_WS_HOURLY_ALERT = 5;
+const FEISHU_WS_DAILY_ALERT = 25;
+/** Process-local WS lifecycle accounting. PM2/systemd retains the structured log across restarts; keeping
+ * raw connection history out of Hara state avoids another privacy-sensitive durable file. */
+export class FeishuWsHealthMonitor {
+    now;
+    connectedAt;
+    disconnectedAt;
+    disconnects = [];
+    total = 0;
+    lastAlertAt = Number.NEGATIVE_INFINITY;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    ready() {
+        this.connectedAt = this.now();
+        this.disconnectedAt = undefined;
+    }
+    disconnect() {
+        const at = this.now();
+        this.disconnects = this.disconnects.filter((value) => at - value <= FEISHU_WS_DAY_MS);
+        this.disconnects.push(at);
+        this.total += 1;
+        const hourCount = this.disconnects.filter((value) => at - value <= FEISHU_WS_HOUR_MS).length;
+        const dayCount = this.disconnects.length;
+        const connectedForMs = this.connectedAt === undefined ? undefined : Math.max(0, at - this.connectedAt);
+        this.connectedAt = undefined;
+        this.disconnectedAt = at;
+        const unhealthy = hourCount >= FEISHU_WS_HOURLY_ALERT || dayCount >= FEISHU_WS_DAILY_ALERT;
+        const alert = unhealthy && at - this.lastAlertAt >= FEISHU_WS_HOUR_MS;
+        if (alert)
+            this.lastAlertAt = at;
+        return { total: this.total, hourCount, dayCount, connectedForMs, alert };
+    }
+    reconnected() {
+        const at = this.now();
+        const disconnectedForMs = this.disconnectedAt === undefined ? undefined : Math.max(0, at - this.disconnectedAt);
+        this.connectedAt = at;
+        this.disconnectedAt = undefined;
+        return disconnectedForMs;
+    }
+}
+function wsDuration(ms) {
+    if (ms === undefined)
+        return "unknown";
+    if (ms < 60_000)
+        return `${Math.max(0, Math.round(ms / 1_000))}s`;
+    if (ms < 60 * 60_000)
+        return `${Math.round(ms / 60_000)}m`;
+    return `${Math.round(ms / (60 * 60_000))}h`;
+}
 /** Normalize a Feishu message's parsed content by type → text + any media keys (pure; download done by caller). */
 export function parseFeishuContent(messageType, content) {
     if (messageType === "text")
@@ -178,6 +232,8 @@ export function feishuAdapter(appId, appSecret) {
     // gateway go deaf. Turning it on means: no inbound frame within pingTimeout seconds of a ping → presumed dead
     // → reconnect. handshakeTimeoutMs stops a stuck DNS/proxy handshake from hanging. Lifecycle logs give
     // visibility so a reconnect is observable instead of a mystery silence.
+    const wsHealth = new FeishuWsHealthMonitor();
+    let failActiveStart;
     const wsClient = new lark.WSClient({
         appId,
         appSecret,
@@ -185,9 +241,29 @@ export function feishuAdapter(appId, appSecret) {
         autoReconnect: true,
         wsConfig: { pingTimeout: 10 },
         handshakeTimeoutMs: 15_000,
-        onReconnecting: () => console.error("hara feishu: ⟳ ws reconnecting…"),
-        onReconnected: () => console.error("hara feishu: ✓ ws reconnected"),
-        onError: (err) => console.error(`hara feishu: ws error — ${err?.message ?? err}`),
+        onReady: () => {
+            wsHealth.ready();
+            console.error("hara feishu: ✓ ws connected");
+        },
+        onReconnecting: () => {
+            const health = wsHealth.disconnect();
+            console.error(`hara feishu: ws disconnected #${health.total} · ${health.hourCount}/1h · ${health.dayCount}/24h · ` +
+                `previous connection ${wsDuration(health.connectedForMs)} · auto-reconnecting (SDK does not expose close code/reason)`);
+            if (health.alert) {
+                console.error("hara feishu: ALERT WebSocket disconnect frequency is unhealthy; check duplicate bot instances, host network/proxy, " +
+                    "and adjacent SDK error/watchdog logs. Automatic reconnect remains active.");
+            }
+        },
+        onReconnected: () => {
+            console.error(`hara feishu: ✓ ws reconnected after ${wsDuration(wsHealth.reconnected())}`);
+        },
+        onError: (err) => {
+            const safe = redactKnownSecrets(String(err?.message ?? err), [appId, appSecret]).text
+                .replace(/\s+/gu, " ")
+                .slice(0, 300);
+            console.error(`hara feishu: ALERT ws reconnect entered terminal failure — ${safe || "unknown SDK error"}`);
+            failActiveStart?.(new Error("Feishu WebSocket entered terminal failure; inspect the redacted gateway log"));
+        },
     });
     // Generated SDK methods discard unknown request options before they reach axios, so passing `signal` there
     // is not cooperative cancellation. REST and media use native fetch instead; the SDK remains responsible for
@@ -385,22 +461,31 @@ export function feishuAdapter(appId, appSecret) {
             });
         },
         async start(onMessage, signal, shouldDownload) {
+            const runAbort = new AbortController();
+            const relayAbort = () => {
+                runAbort.abort(signal.reason instanceof Error ? signal.reason : new Error("Feishu gateway cancelled"));
+            };
+            if (signal.aborted)
+                relayAbort();
+            else
+                signal.addEventListener("abort", relayAbort, { once: true });
+            const runSignal = runAbort.signal;
             const spool = await GatewayEventSpool.open(gatewayRuntimeScope("feishu-inbound", appId));
             const locallyCompleted = new Set();
             const cleanupFailures = new Map();
             const retryStateFailures = new Map();
             const postAckCleanups = new Map();
             const runWorker = async () => {
-                while (!signal.aborted) {
+                while (!runSignal.aborted) {
                     const item = await spool.nextReady();
                     if (!item) {
-                        await waitForFeishuWork(250, signal);
+                        await waitForFeishuWork(250, runSignal);
                         continue;
                     }
                     try {
                         if (!locallyCompleted.has(item.id)) {
-                            const m = await toInbound(downloadResource, item.payload, await ensureBotOpenId(signal), signal, shouldDownload);
-                            if (signal.aborted) {
+                            const m = await toInbound(downloadResource, item.payload, await ensureBotOpenId(runSignal), runSignal, shouldDownload);
+                            if (runSignal.aborted) {
                                 await spool.release(item.id);
                                 return;
                             }
@@ -409,7 +494,7 @@ export function feishuAdapter(appId, appSecret) {
                                 if (cleanup)
                                     postAckCleanups.set(item.id, cleanup);
                             }
-                            if (signal.aborted) {
+                            if (runSignal.aborted) {
                                 await spool.release(item.id);
                                 return;
                             }
@@ -433,7 +518,7 @@ export function feishuAdapter(appId, appSecret) {
                         }
                     }
                     catch {
-                        if (signal.aborted) {
+                        if (runSignal.aborted) {
                             await spool.release(item.id);
                             return;
                         }
@@ -449,7 +534,7 @@ export function feishuAdapter(appId, appSecret) {
                                 console.error("hara feishu: ALERT durable spool cleanup suspended after 5 failures; the completed item is retained for startup recovery");
                                 return; // keep the in-memory lease: no busy loop and no agent replay in this process
                             }
-                            await waitForFeishuWork(Math.min(30_000, 2_000 * (2 ** (failures - 1))), signal);
+                            await waitForFeishuWork(Math.min(30_000, 2_000 * (2 ** (failures - 1))), runSignal);
                             await spool.release(item.id);
                             continue;
                         }
@@ -476,7 +561,7 @@ export function feishuAdapter(appId, appSecret) {
                                 console.error("hara feishu: ALERT durable spool retry-state persistence suspended after 5 failures; event retained for startup recovery");
                                 return;
                             }
-                            await waitForFeishuWork(Math.min(30_000, 2_000 * (2 ** (failures - 1))), signal);
+                            await waitForFeishuWork(Math.min(30_000, 2_000 * (2 ** (failures - 1))), runSignal);
                             await spool.release(item.id);
                         }
                     }
@@ -492,43 +577,59 @@ export function feishuAdapter(appId, appSecret) {
                 "im.message.receive_v1": async (data) => {
                     // Feishu requires a long-connection callback within three seconds. Durably enqueue first, then ACK;
                     // workers run the potentially minutes-long agent task independently and survive process restarts.
-                    if (signal.aborted)
+                    if (runSignal.aborted)
                         throw new Error("Feishu gateway cancelled");
                     const write = spool.enqueue(feishuEventSpoolId(data), data);
                     persistenceWrites.add(write);
                     void write.then(() => persistenceWrites.delete(write), () => persistenceWrites.delete(write));
                     try {
-                        await withOutboundDeadline("Feishu event persistence", signal, 2_500, async () => write);
+                        await withOutboundDeadline("Feishu event persistence", runSignal, 2_500, async () => write);
                     }
                     catch (error) {
-                        if (!signal.aborted) {
+                        if (!runSignal.aborted) {
                             console.error(`hara feishu: ALERT event could not be durably queued before ACK — ${error instanceof Error ? error.message : String(error)}`);
                         }
                         throw error;
                     }
                 },
             });
-            wsClient.start({ eventDispatcher }); // runs its own background long-connection (auto-reconnect + watchdog)
-            // Keep the adapter alive until the gateway aborts, then CLOSE the WSClient so its socket + timers release
-            // the event loop and the process actually exits on SIGTERM (previously the live connection pinned the
-            // loop, so only kill -9 worked — and a hard kill leaves a dirty disconnect that Feishu can throttle).
-            await new Promise((resolve) => {
-                if (signal.aborted)
+            const terminalFailure = new Promise((_resolve, reject) => {
+                failActiveStart = (error) => {
+                    reject(error);
+                    runAbort.abort(error);
+                };
+            });
+            const stopped = new Promise((resolve) => {
+                if (runSignal.aborted)
                     return resolve();
-                signal.addEventListener("abort", () => resolve(), { once: true });
+                runSignal.addEventListener("abort", () => resolve(), { once: true });
             });
             try {
-                wsClient.close();
+                // The SDK owns ordinary reconnect/backoff. A terminal callback is different: keeping this process alive
+                // but deaf defeats PM2/systemd recovery, so reject start after draining the durable inbound workers.
+                void Promise.resolve(wsClient.start({ eventDispatcher })).catch((error) => {
+                    const safe = redactKnownSecrets(String(error instanceof Error ? error.message : error), [appId, appSecret]).text;
+                    failActiveStart?.(new Error(`Feishu WebSocket start failed: ${safe.slice(0, 300)}`));
+                });
+                await Promise.race([stopped, terminalFailure]);
             }
-            catch {
-                /* best-effort clean shutdown */
+            finally {
+                failActiveStart = undefined;
+                runAbort.abort(new Error("Feishu gateway stopped"));
+                signal.removeEventListener("abort", relayAbort);
+                try {
+                    wsClient.close();
+                }
+                catch {
+                    /* best-effort clean shutdown */
+                }
+                // Do not release the gateway instance lease while an old worker or an ACK-persistence write can still
+                // mutate the spool. A replacement process must never race this process's final CAS write or run the same
+                // durable item concurrently.
+                while (persistenceWrites.size)
+                    await Promise.allSettled([...persistenceWrites]);
+                await workersSettled;
             }
-            // Do not release the gateway instance lease while an old worker or an ACK-persistence write can still
-            // mutate the spool. A replacement process must never race this process's final CAS write or run the same
-            // durable item concurrently.
-            while (persistenceWrites.size)
-                await Promise.allSettled([...persistenceWrites]);
-            await workersSettled;
         },
     };
 }

package/dist/index.js

@@ -71,7 +71,7 @@ function renderBgJobs() {
 }
 import { qwenDeviceLogin, loadQwenToken } from "./providers/qwen-oauth.js";
 import { loadAgentContext, hasAgentsMd, INIT_PROMPT, findProjectRoot } from "./context/agents-md.js";
-import { homeWorkspaceActionError, isUnsafeProjectWorkspace, resolveWorkspaceSwitch, } from "./context/workspace-scope.js";
+import { homeWorkspaceActionError, isUnsafeProjectWorkspace, resolveWorkspaceSwitch, suggestedProjectWorkspace, } from "./context/workspace-scope.js";
 import { getEmbedder } from "./search/embed.js";
 import { collectRepoChunksAsync, collectDirChunksAsync, buildIndex, indexPath, indexExists } from "./search/semindex.js";
 import { searchHybrid } from "./search/hybrid.js";
@@ -3001,6 +3001,66 @@ program.action(async (opts) => {
     // hook above — see setFlagOverride() + resolveActive() in profile.ts. activeId() / loadActiveProfile()
     // pick it up automatically. `HARA_PROFILE` env still works as a transient override (one slot lower
     // in the priority chain than --profile).
+    // An interactive launch from Home gets an explicit, pre-provider handoff. Candidate discovery is limited
+    // to paths the user already established through interactive sessions/project registration; Hara never
+    // enumerates Home and never silently promotes a readable child into the workspace.
+    if (!opts.print
+        && !opts.cwd
+        && !opts.resume
+        && stdin.isTTY
+        && stdout.isTTY
+        && isUnsafeProjectWorkspace(process.cwd())) {
+        let candidate;
+        try {
+            const recent = listSessions()
+                .filter((session) => session.source === undefined || session.source === "interactive")
+                .map((session) => session.cwd);
+            candidate = suggestedProjectWorkspace([
+                ...recent,
+                ...loadProjects().map((project) => project.path),
+            ]);
+        }
+        catch {
+            // A damaged optional history/registry must not weaken the Home boundary or block startup.
+        }
+        const startupUsesTui = process.env.HARA_TUI !== "0";
+        if (candidate && startupUsesTui) {
+            // A readline question before Ink mounts leaves stdin unreadable on some terminals. The small Ink
+            // confirmation unmounts cleanly and is the same handoff used by the first-run AGENTS.md prompt.
+            if (await askConfirm(`Home is protected as personal-data scope. Switch to recent project ${displaySessionCwd(candidate)}?`)) {
+                process.chdir(candidate);
+            }
+        }
+        else if (!candidate && startupUsesTui) {
+            out(c.yellow("Home is protected as personal-data scope; no recent project is available to offer safely. ")
+                + c.dim("Start with `hara --cwd /path/to/project`, or use `/cd /path/to/project` after startup.\n"));
+        }
+        else {
+            const rl = createInterface({ input: stdin, output: stdout });
+            try {
+                if (candidate) {
+                    const answer = (await rl.question(c.yellow(`Home is protected as personal-data scope. Switch to recent project ${displaySessionCwd(candidate)}? `)
+                        + c.dim("[Y/n] "))).trim().toLowerCase();
+                    if (answer === "" || answer === "y" || answer === "yes")
+                        process.chdir(candidate);
+                }
+                else {
+                    const answer = (await rl.question(c.yellow("Home is protected as personal-data scope. Enter a project directory to switch now")
+                        + c.dim(" (leave empty to stay at Home): "))).trim();
+                    if (answer) {
+                        const switched = resolveWorkspaceSwitch(answer, process.cwd());
+                        if (switched.ok)
+                            process.chdir(switched.cwd);
+                        else
+                            out(c.red(`(${switched.error})\n`));
+                    }
+                }
+            }
+            finally {
+                rl.close();
+            }
+        }
+    }
     // Resolve addressable headless roles BEFORE loading config/provider/MCP. A qualified project role is
     // an execution-home selection, so every downstream route (credentials, model, AGENTS.md, tools) must be
     // constructed from that home rather than from the shell directory that happened to launch hara.

package/dist/plugins/plugins.js

@@ -281,8 +281,77 @@ function validGitSource(source) {
     if (!/^(?:https:\/\/|ssh:\/\/|git@)[^\s\0]+$/u.test(url)) {
         throw new Error("git source must use an https://, ssh://, or git@ URL");
     }
+    if (url.startsWith("https://") || url.startsWith("ssh://")) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new Error("git source contains an invalid URL");
+        }
+        const secretAuthority = url.startsWith("https://")
+            ? Boolean(parsed.username || parsed.password)
+            : Boolean(parsed.password);
+        if (secretAuthority || parsed.search || parsed.hash) {
+            throw new Error("git source must not embed credentials or query/fragment secrets; configure a Git credential helper or SSH key instead");
+        }
+    }
     return url;
 }
+/** Turn git's often credential-bearing stderr into a bounded, actionable diagnosis. Never echo the URL,
+ * stderr, usernames, tokens, credential-helper output, or the original command line. */
+export function pluginGitCloneFailure(kind, error) {
+    const value = error;
+    const stderr = Buffer.isBuffer(value?.stderr)
+        ? value.stderr.toString("utf8")
+        : typeof value?.stderr === "string"
+            ? value.stderr
+            : "";
+    const diagnostic = stderr.toLowerCase();
+    const label = kind === "github" ? "GitHub plugin repository" : "plugin Git repository";
+    if (value?.code === "ENOENT") {
+        return `Could not clone the ${label}: Git is not installed or is not available on PATH. Install Git, then retry.`;
+    }
+    if (value?.code === "ETIMEDOUT"
+        || value?.signal === "SIGTERM"
+        || value?.killed === true
+        || /timed out|connection timed out/u.test(diagnostic)) {
+        return `Could not clone the ${label}: the network operation exceeded Hara's 2-minute limit. Check connectivity/proxy settings, then retry.`;
+    }
+    if (/could not resolve host|failed to connect|connection refused|network is unreachable|connection reset/u.test(diagnostic)) {
+        return `Could not clone the ${label}: Git could not reach the remote host. Check DNS, network, VPN, and Git proxy settings, then retry.`;
+    }
+    if (/authentication failed|permission denied|access denied|could not read username|terminal prompts disabled|publickey|http basic/u.test(diagnostic)) {
+        return (`Could not clone the ${label}: authentication or repository access was denied. ` +
+            (kind === "github"
+                ? "For a private repository, authenticate GitHub (`gh auth login` then `gh auth setup-git`) or use `git:git@github.com:owner/repository.git` with a working SSH key. "
+                : "Configure credentials for that Git host or use an SSH URL backed by a working key. ") +
+            "Do not put a token in the plugin URL.");
+    }
+    if (/repository not found|not found|could not read from remote repository/u.test(diagnostic)) {
+        return (`Could not clone the ${label}: it does not exist or the current Git identity cannot access it. ` +
+            (kind === "github"
+                ? "Check owner/repository spelling; for a private repository run `gh auth login` and `gh auth setup-git`, or use a working SSH URL. "
+                : "Check the repository URL and credentials. ") +
+            "Do not put a token in the plugin URL.");
+    }
+    return (`Could not clone the ${label}. Run an equivalent \`git clone\` yourself to diagnose the remote, ` +
+        "then retry Hara after Git credentials/network access work. No remote stderr was shown because it may contain credentials.");
+}
+function clonePluginRepository(url, staging, kind) {
+    try {
+        execFileSync("git", ["clone", "--depth", "1", url, staging], {
+            encoding: "utf8",
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+            maxBuffer: 256 * 1024,
+            stdio: ["ignore", "ignore", "pipe"],
+            timeout: 2 * 60_000,
+        });
+    }
+    catch (error) {
+        throw new Error(pluginGitCloneFailure(kind, error));
+    }
+}
 function populateStaging(source, staging) {
     if (source.startsWith("file:")) {
         const requested = resolve(source.slice("file:".length));
@@ -301,10 +370,10 @@ function populateStaging(source, staging) {
         const repo = source.slice("github:".length);
         if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u.test(repo))
             throw new Error("github source must be owner/repository");
-        execFileSync("git", ["clone", "--depth", "1", `https://github.com/${repo}.git`, staging], { stdio: "ignore" });
+        clonePluginRepository(`https://github.com/${repo}.git`, staging, "github");
     }
     else if (source.startsWith("git:")) {
-        execFileSync("git", ["clone", "--depth", "1", validGitSource(source), staging], { stdio: "ignore" });
+        clonePluginRepository(validGitSource(source), staging, "git");
     }
     else {
         throw new Error("source must be file:<path>, github:<owner/repo>, or git:<url>");

package/dist/security/private-state.js

@@ -8,9 +8,15 @@ import { basename, dirname, join, resolve } from "node:path";
 import { FileReadLimitError, MAX_EDIT_READ_BYTES, decodeUtf8Strict, openVerifiedRegularFileNoFollow, verifyOpenedRegularFileSync, } from "../fs-read.js";
 import { optionalPosixOpenFlag } from "../fs-open-flags.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
-const PRIVATE_TREES = new Set(["sessions", "checkpoints", "index", "gateway", "cron", "weixin", "tool-results", "plugin-receipts"]);
+const PRIVATE_TREES = new Set(["sessions", "checkpoints", "index", "gateway", "cron", "weixin", "tool-results", "plugin-receipts", "artifacts"]);
 const tightenedHomes = new Set();
 const DEFAULT_MIGRATION_CAP = 50_000;
+export class PrivateStateConflictError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "PrivateStateConflictError";
+    }
+}
 function isMissing(error) {
     return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
 }
@@ -300,17 +306,113 @@ function syncPrivateDirectory(path) {
         /* Directory fsync is not portable; the staged file itself is always fsynced. */
     }
 }
+/**
+ * Crash-safe immutable binary creation below a bound private-state directory.
+ *
+ * Artifact revisions use this instead of the text replacement writer: revision content is immutable,
+ * may be a binary Office file, and must never replace an entry that appeared concurrently. The staged
+ * inode is fsync'd, hard-linked into place with create-if-absent semantics, and checked again after the
+ * temporary name is removed.
+ */
+export function writePrivateStateBytesOnceSync(binding, bytes) {
+    const { directory, path } = binding;
+    verifyPrivateDirectory(directory);
+    if (resolve(path) !== join(directory.path, checkedPrivateComponent(basename(path)))) {
+        throw new Error(`private Hara state file is outside '${directory.path}'`);
+    }
+    try {
+        lstatSync(path);
+        throw new Error(`private Hara state file already exists: '${path}'`);
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+    const temp = join(directory.path, `.hara-private-${process.pid}-${randomUUID()}.tmp`);
+    let fd;
+    let staged;
+    try {
+        fd = openSync(temp, "wx", 0o600);
+        writeFileSync(fd, bytes);
+        try {
+            fchmodSync(fd, 0o600);
+        }
+        catch (error) {
+            if (process.platform !== "win32")
+                throw error;
+        }
+        fsyncSync(fd);
+        const stagedInfo = fstatSync(fd);
+        if (!stagedInfo.isFile() || stagedInfo.nlink !== 1) {
+            throw new Error("unsafe private Hara binary staging inode");
+        }
+        staged = {
+            dev: stagedInfo.dev,
+            ino: stagedInfo.ino,
+            mode: stagedInfo.mode & 0o777,
+            nlink: stagedInfo.nlink,
+        };
+        closeSync(fd);
+        fd = undefined;
+        verifyPrivateDirectory(directory);
+        try {
+            linkSync(temp, path);
+        }
+        catch (error) {
+            if (error?.code === "EEXIST") {
+                throw new Error(`private Hara state file changed before create: '${path}'`);
+            }
+            throw error;
+        }
+        const linkedStaged = { ...staged, nlink: staged.nlink + 1 };
+        if (!samePrivateFile(temp, linkedStaged) || !samePrivateFile(path, linkedStaged)) {
+            throw new Error(`private Hara binary staging identity changed during commit: '${path}'`
+                + `; expected=${JSON.stringify(linkedStaged)}`
+                + `; staging=${privateFileIdentitySummary(temp)}`
+                + `; target=${privateFileIdentitySummary(path)}`);
+        }
+        unlinkSync(temp);
+        const committed = lstatSync(path);
+        if (!committed.isFile()
+            || committed.isSymbolicLink()
+            || !sameOpenedFileIdentity(committed, staged)
+            || committed.nlink !== 1
+            || (process.platform !== "win32" && (committed.mode & 0o777) !== 0o600))
+            throw new Error(`private Hara state file changed during commit: '${path}'`);
+        verifyPrivateDirectory(directory);
+        syncPrivateDirectory(directory.path);
+    }
+    finally {
+        if (fd !== undefined)
+            try {
+                closeSync(fd);
+            }
+            catch { /* preserve original error */ }
+        if (staged) {
+            try {
+                if (samePrivateFile(temp, staged))
+                    unlinkSync(temp);
+            }
+            catch {
+                /* A changed entry is retained rather than unlinking an attacker-supplied replacement. */
+            }
+        }
+    }
+}
 /**
  * Crash-safe, no-follow, compare-and-swap replacement for one bound private state file. Existing entries
  * are move-claimed before verification so a concurrent alias/replacement is never overwritten silently.
  */
-export function writePrivateStateFileSync(binding, text) {
+export function writePrivateStateFileSync(binding, text, options = {}) {
     const { directory, path } = binding;
     verifyPrivateDirectory(directory);
     if (resolve(path) !== join(directory.path, checkedPrivateComponent(basename(path)))) {
         throw new Error(`private Hara state file is outside '${directory.path}'`);
     }
     const existing = readPrivateStateFileSnapshotSync(path);
+    if (options.expectedText !== undefined && existing?.text !== options.expectedText) {
+        throw new PrivateStateConflictError(`private Hara state file no longer matches the expected version: '${path}'`);
+    }
     verifyPrivateDirectory(directory);
     const temp = join(directory.path, `.hara-private-${process.pid}-${randomUUID()}.tmp`);
     let fd;
@@ -345,8 +447,9 @@ export function writePrivateStateFileSync(binding, text) {
                 linkSync(temp, path);
             }
             catch (error) {
-                if (error?.code === "EEXIST")
-                    throw new Error(`private Hara state file changed before create: '${path}'`);
+                if (error?.code === "EEXIST") {
+                    throw new PrivateStateConflictError(`private Hara state file changed before create: '${path}'`, { cause: error });
+                }
                 throw error;
             }
         }
@@ -357,8 +460,9 @@ export function writePrivateStateFileSync(binding, text) {
                 renameSync(path, claimed);
             }
             catch (error) {
-                if (error?.code === "ENOENT")
-                    throw new Error(`private Hara state file changed before replace: '${path}'`);
+                if (error?.code === "ENOENT") {
+                    throw new PrivateStateConflictError(`private Hara state file changed before replace: '${path}'`, { cause: error });
+                }
                 throw error;
             }
             let verifiedClaim = false;
@@ -369,8 +473,9 @@ export function writePrivateStateFileSync(binding, text) {
                     && claimedSnapshot.mode === existing.mode
                     && claimedSnapshot.nlink === existing.nlink
                     && claimedSnapshot.text === existing.text);
-                if (!verifiedClaim)
-                    throw new Error(`private Hara state file changed before replace: '${path}'`);
+                if (!verifiedClaim) {
+                    throw new PrivateStateConflictError(`private Hara state file changed before replace: '${path}'`);
+                }
             }
             catch (error) {
                 try {

package/dist/serve/protocol.js

@@ -28,6 +28,14 @@
 //                                                               → {id,name,schedule}
 //   automation.toggle {id,enabled}                → {id,enabled}
 //   automation.delete {id}                        → {id,deleted}
+//   artifact.import   {sourcePath,title?,kind?}    → {artifact,currentRevision,content}
+//   artifact.commit   {artifactId,baseRevisionId,sourcePath,taskRunId?,changedPaths?}
+//                                                   → {artifact,currentRevision,content}
+//   artifact.revert   {artifactId,baseRevisionId,targetRevisionId,taskRunId?}
+//                                                   → {artifact,currentRevision,content}
+//   artifact.list     {}                          → {artifacts,invalid,truncated}
+//   artifact.get      {artifactId}                → {artifact,currentRevision,content}
+//   artifact.revisions {artifactId}               → {artifactId,revisions}
 //   session.rename    {sessionId,title}           → {sessionId,title}
 //   session.archive   {sessionId,archived}        → {sessionId,archived}   (list hides archived unless {archived:true})
 //   session.set-model {sessionId,model?,effort?}  → {sessionId,model,effort} (next turn; refused mid-turn)
@@ -48,6 +56,7 @@ export const ERR = {
     BUSY: -32002, // requested operation conflicts with active server/session work
     NO_SESSION: -32003, // unknown/expired sessionId
     LOCKED: -32004, // session held by another live hara process (single-writer lock)
+    CONFLICT: -32005, // optimistic version/base no longer matches the current object
 };
 /** Parse one inbound text frame into a request. Returns {error} (never throws) on malformed input —
  *  the transport turns that into a PARSE/INVALID error response. */