@nanhara/hara 0.128.0 → 0.129.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.129.0 — 2026-07-20 — durable revisions and workspace recovery
+
+- Authenticated Serve clients can commit a user-selected file as a new immutable Artifact revision with
+  `artifact.commit`. Every write carries `baseRevisionId`; a stale editor receives the dedicated protocol
+  conflict code and cannot replace the current revision.
+- `artifact.revert` restores an earlier ancestor by creating another immutable revision rather than moving
+  the pointer backward or mutating history. The imported original and every prior revision remain unchanged.
+- Revision pointer updates now use a private-state compare-and-swap guard that also closes a cross-process
+  race. The authenticated host assigns the user actor, so a Desktop client cannot forge an Agent/migration
+  audit identity.
+- This slice does not yet export files or claim Office fidelity. ExportReceipt, validation reports, worker
+  identity, format-specific editing, and Panel v2 remain separate release gates.
+- Interactive launches from the home directory now offer an explicit, one-step switch to a recent or
+  registered project before provider and MCP startup. Hara never enumerates the home directory and never
+  changes workspace scope without confirmation.
+- Repeated protected-home failures are now grouped by semantic root cause across `ls`, `grep`, `glob`, and
+  other filesystem tools. A run stops after the bounded retry threshold with a focused recovery instruction
+  instead of trying different tools against the same boundary indefinitely.
+- Git plugin installation now rejects credential-bearing source URLs, bounds clone time, and safely
+  distinguishes missing Git, network, authentication/access, and private/not-found repository failures
+  without echoing URLs, tokens, or Git stderr.
+- Feishu WebSocket gateways now report connected, disconnected, and reconnected lifecycle events with
+  one-hour and 24-hour counters. Repeated disconnects raise rate-limited alerts, while terminal SDK recovery
+  failures stop the adapter after a safe drain so a process supervisor can restart it.
+- Upgrade with `npm i -g @nanhara/hara@0.129.0`.
+
 ## 0.128.0 — 2026-07-20 — local deliverable foundation
 
 - Hara Serve now provides the first `artifact/1` local runtime through authenticated

package/README.md

@@ -274,11 +274,13 @@ new execution. The `hara resume` launcher preserves terminal input in both npm/N
 installs.
 **Local deliverables**: Hara Serve 0.128 adds the first local `artifact/1` foundation for presentations,
 spreadsheets, and documents. An authenticated Desktop client can import, list, integrity-check, and inspect
-version history through `artifact.import|list|get|revisions`. Import makes an owner-only immutable copy under
-`~/.hara/artifacts`, never changes the selected file, and never stores its absolute source path. Relative,
-linked, protected, macro-enabled, type-confused, empty, and oversized inputs fail closed. This foundation
-does **not** render, edit, export, or execute imported content; those operations require a matching reviewed
-Office capability.
+version history through `artifact.import|list|get|revisions`. The next revision transaction slice also
+advertises `artifact.commit|revert`: every edit supplies the version it started from, a stale edit fails with
+an explicit conflict, and reverting creates a new immutable revision instead of rewriting history. Import and
+commit make owner-only copies under `~/.hara/artifacts`, never change the selected source file, and never store
+its absolute path. Relative, linked, protected, macro-enabled, type-confused, empty, and oversized inputs fail
+closed. The runtime does **not** yet render, format-edit, export, or execute imported content; those operations
+require matching reviewed Office capabilities and validation/export receipts.
 **MCP**: add an `mcpServers` map to global config (a reviewed project config additionally needs `HARA_TRUST_PROJECT_CONFIG=1` at launch). Hara starts with every configured server stopped and exposes only `mcp_connect`; when the current task first needs one server, the agent requests permission to connect that server and its tools appear on the next round as `mcp__<server>__<tool>`. Unrelated servers remain stopped. Configured MCP servers, like `external_agent`, are trusted host extensions outside Hara's protected-file boundary. Every interactive external-tool call requires confirmation (even in `full-auto`), and non-interactive runs disable them by default; reviewed automation can explicitly opt in before launch with `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. hara can also **be** an MCP server — `hara mcp` exposes its read/search tools (esp. **`codebase_search`**) over stdio so other clients (Claude Desktop, Cursor, another hara) can use them; read-only by default (`HARA_MCP_TOOLS` to override).
 **Vim mode**: `hara config set vimMode true` makes the prompt modal — Esc → normal, `i/a/A/I` insert, `h l 0 $ w b e` motions, `x D C dd cw p` edits. Off by default.
 **Scheduled tasks**: `hara cron add "0 9 * * 1-5" "<task>"` (or `"every 30m"`, `"in 2h"`) runs a task on a schedule — each run is a fresh hara session. `hara cron install` wires a per-minute tick into launchd/crontab (no daemon); `--org` routes through the role org. Manage with `hara cron list/run/enable/disable/remove/logs`. Every job has a 30-minute deadline and the whole sequential tick has a non-renewable 60-minute watchdog: a job timeout kills its process tree, records `timed out` + duration/error, then continues with the next due job; a tick timeout stops the remainder and releases the global lock. Add `--deliver feishu:<chatId>` (or Telegram/WeChat/webhook) for outcomes. `--deliver-mode always` preserves the existing every-run heartbeat, `on-output` sends only when redacted stdout is non-empty, and `on-error` sends only failed runs; `--alert-after N` remains independent and still raises the consecutive-failure 🚨 threshold alarm (default 3). Delivery intent is durable before transport, uses a stable idempotency key, and retries with bounded backoff on later ticks until confirmed. A failed channel cannot grow `jobs.json` forever: each job keeps at most 64 pending effects, reserves outcome/alert room before launch, and disables itself with a visible backlog error when full; restore delivery, let the queue drain, then re-enable it. Tune milliseconds with `HARA_CRON_JOB_TIMEOUT_MS` (hard max 24h) and `HARA_CRON_TICK_TIMEOUT_MS` (hard max 5h); scheduled jobs are also capped by the tick. After upgrading from a version whose tick is already stuck, terminate that specific legacy `hara cron tick` process tree once (or reboot); the next scheduler minute marks over-age state interrupted/disabled and recovers the lock without replaying a possibly orphaned task.

package/dist/agent/loop.js

@@ -9,7 +9,7 @@ import { runHooks } from "../hooks.js";
 import { mapLimit, maxParallel } from "../concurrency.js";
 import { decideCommand, isReadOnlyCommand, loadPermissionRules, splitCompound, } from "../security/permissions.js";
 import { classifyRisk, guardianVeto, guardianEnabled, newBreaker, recordBlock } from "../security/guardian.js";
-import { keyOf, looksFailed, recordCall } from "./repeat-guard.js";
+import { failureIdentity, looksFailed, recordCall } from "./repeat-guard.js";
 import { agentMaxRounds, agentRunTimeoutMs, formatAgentDuration } from "./limits.js";
 import { subdirHint } from "../context/subdir-hints.js";
 import { classifyError, failoverAction, errorHint } from "./failover.js";
@@ -405,7 +405,7 @@ function hardStop(opts, life, kind, detail) {
         ? `⏸ agent run paused: active-execution deadline ${formatAgentDuration(life.timeoutMs)} reached after ${life.rounds} round(s). Waiting for your answers did not consume this budget. No further model or tool calls will start in this turn. Session-backed work keeps its task and checklist checkpoint; type \`/continue\` to resume in a fresh bounded turn. Only for intentionally long single turns, use \`hara config set runTimeoutMs 45m\` (maximum 2h).`
         : kind === "max_rounds"
             ? `⛔ agent run stopped: ${life.maxRounds}-round safety limit reached after ${formatAgentDuration(elapsedMs)}. This usually means the model is looping. Increase it with \`hara config set maxAgentRounds <n>\` (maximum 256) only if the extra rounds are intentional.`
-            : `⛔ agent run stopped: the same failing ${detail?.tool ?? "tool"} call repeated ${detail?.count ?? REPEATED_FAILURE_LIMIT} times. Change the approach or fix the reported cause before retrying.`;
+            : `⛔ agent run stopped: the same failing ${detail?.label ?? "tool call"} repeated ${detail?.count ?? REPEATED_FAILURE_LIMIT} times. Change the approach or fix the reported cause before retrying.`;
     const event = { kind, message, elapsedMs, rounds: life.rounds, timeoutMs: life.timeoutMs, maxRounds: life.maxRounds };
     if (!life.limitAnnounced) {
         life.limitAnnounced = true;
@@ -944,16 +944,16 @@ async function runAgentInner(history, opts, life) {
         let repeatHalt = null;
         const noteCall = (name, input, content, isError = false) => {
             const note = recordCall(name, input, content, isError, ctx.todoScope);
-            const key = keyOf(name, input);
+            const identity = failureIdentity(name, input, content, isError);
             if (isError || looksFailed(content, name)) {
-                const count = (life.failedCalls.get(key) ?? 0) + 1;
+                const count = (life.failedCalls.get(identity.key) ?? 0) + 1;
                 // This is a *consecutive no-progress* streak, not a lifetime counter for the call. A different
                 // failure is a changed attempt; keep only that new streak instead of letting an old failure
                 // silently accumulate across intervening work.
                 life.failedCalls.clear();
-                life.failedCalls.set(key, count);
+                life.failedCalls.set(identity.key, count);
                 if (count >= REPEATED_FAILURE_LIMIT && !repeatHalt)
-                    repeatHalt = { tool: name, count };
+                    repeatHalt = { label: identity.label, count };
             }
             else {
                 // Any successful action is progress (in particular edit/exec calls that may have fixed the

package/dist/agent/repeat-guard.js

@@ -8,6 +8,7 @@
 // sessions in one process, so streaks are keyed by the same run scope as todo/reminder state.
 const DEFAULT_SCOPE = "default";
 const seenByScope = new Map();
+const HOME_WORKSPACE_BOUNDARY_KEY = "root-cause:home-workspace-boundary";
 function scopedSeen(scope) {
     const key = scope?.trim() || DEFAULT_SCOPE;
     const seen = seenByScope.get(key) ?? new Map();
@@ -68,23 +69,52 @@ export function looksFailed(content, name) {
     }
     return false;
 }
+/** Several different filesystem tools can hit the same protected Home-workspace boundary. Treating each
+ * tool name/argument tuple as a fresh idea lets a model spin through grep → glob → ls even though the
+ * root cause cannot change inside that run. Only Hara's own stable boundary diagnostics are coalesced. */
+function isHomeWorkspaceBoundaryFailure(content) {
+    return (/will not recursively scan the home directory\b/i.test(content)
+        || /will not enumerate or recursively scan directories while Hara is rooted at the home directory\b/i.test(content)
+        || /workspace that is the home directory or contains it\b/i.test(content));
+}
+/** Stable identity used by both the warning note and the run-level hard breaker. */
+export function failureIdentity(name, input, content, isError = false) {
+    const failed = isError || looksFailed(content, name);
+    if (failed && isHomeWorkspaceBoundaryFailure(content)) {
+        return {
+            key: HOME_WORKSPACE_BOUNDARY_KEY,
+            label: "Home workspace boundary",
+            semantic: true,
+        };
+    }
+    return {
+        key: keyOf(name, input),
+        label: `${name} call`,
+        semantic: false,
+    };
+}
 /** Record a completed call; returns a warning to APPEND to the tool result when the same call has now
  *  failed >=2x in a row (empty string otherwise). Pure aside from the session-scoped map. */
 export function recordCall(name, input, content, isError = false, scope) {
-    const k = keyOf(name, input);
     const failed = isError || looksFailed(content, name);
+    const identity = failureIdentity(name, input, content, isError);
     const seen = scopedSeen(scope);
     if (!failed) {
         seen.clear(); // any success is progress; a later failure starts a fresh no-progress streak
         return "";
     }
-    const s = seen.get(k) ?? { fails: 0 };
+    const s = seen.get(identity.key) ?? { fails: 0 };
     s.fails++;
     // "In a row" is literal: a different failed call is a changed attempt and breaks the old streak.
     seen.clear();
-    seen.set(k, s);
+    seen.set(identity.key, s);
     if (s.fails < 2)
         return "";
+    if (identity.semantic) {
+        return (`\n\n⟳ hara: the same ${identity.label} has now blocked ${s.fails} consecutive tool calls — ` +
+            "another filesystem/search tool cannot bypass it. Ask the user to switch with `/cd <project>` " +
+            "or stop this run; do not probe another directory tool from Home.");
+    }
     return (`\n\n⟳ hara: this exact ${name} call has now FAILED ${s.fails}× with identical arguments — ` +
         `repeating it unchanged will fail again. Read the error above, change something (arguments / approach / tool), ` +
         `or step back and re-plan; if you're out of ideas, ask the user and say what you tried.`);

package/dist/artifacts/store.js

@@ -4,7 +4,7 @@ import { basename, extname, isAbsolute, join, resolve } from "node:path";
 import { openVerifiedRegularFileNoFollow, verifyOpenedRegularFileSync, } from "../fs-read.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
 import { optionalPosixOpenFlag } from "../fs-open-flags.js";
-import { bindPrivateHaraStateFile, ensurePrivateStateSubdirectory, readPrivateStateFileSnapshotSync, writePrivateStateBytesOnceSync, writePrivateStateFileSync, } from "../security/private-state.js";
+import { bindPrivateHaraStateFile, ensurePrivateStateSubdirectory, PrivateStateConflictError, readPrivateStateFileSnapshotSync, writePrivateStateBytesOnceSync, writePrivateStateFileSync, } from "../security/private-state.js";
 export const ARTIFACT_PROTOCOL_VERSION = "artifact/1";
 export const MAX_ARTIFACT_IMPORT_BYTES = 64 * 1024 * 1024;
 const MAX_ARTIFACTS = 10_000;
@@ -169,6 +169,51 @@ function checkedRevisionId(value) {
     }
     return value;
 }
+function checkedInputRevisionId(value, field) {
+    if (typeof value !== "string" || !REVISION_ID.test(value)) {
+        throw storeError("ARTIFACT_INVALID_INPUT", `${field} is not a valid opaque Revision id`);
+    }
+    return value;
+}
+function checkedActor(value) {
+    if (value === undefined)
+        return "user";
+    if (value !== "user" && value !== "agent" && value !== "migration") {
+        throw storeError("ARTIFACT_INVALID_INPUT", "actor must be user, agent, or migration");
+    }
+    return value;
+}
+function checkedTaskRunId(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string"
+        || value.length < 1
+        || value.length > 256
+        || /[\u0000-\u001f\u007f]/.test(value))
+        throw storeError("ARTIFACT_INVALID_INPUT", "taskRunId must be a safe string of at most 256 characters");
+    return value;
+}
+function normalizeArtifactPath(value) {
+    if (typeof value !== "string" || value.length < 1 || value.length > 1_024 || value.includes("\0")) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "changedPaths entries must be non-empty relative paths");
+    }
+    if (value.startsWith("/") || value.startsWith("\\") || /^[A-Za-z]:/.test(value) || value.includes("\\")) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "changedPaths entries must use relative forward-slash paths");
+    }
+    const segments = value.split("/");
+    if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "changedPaths contains an unsafe path segment");
+    }
+    return segments.join("/");
+}
+function checkedChangedPaths(value) {
+    if (value === undefined)
+        return ["content"];
+    if (!Array.isArray(value) || value.length < 1 || value.length > 10_000) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "changedPaths must contain 1 to 10000 relative paths");
+    }
+    return [...new Set(value.map(normalizeArtifactPath))];
+}
 function childDirectory(parent, name, notFoundMessage) {
     verifyDirectory(parent);
     const path = join(parent.path, name);
@@ -191,6 +236,24 @@ function childDirectory(parent, name, notFoundMessage) {
 function artifactDirectory(home, artifactId) {
     return childDirectory(artifactRoot(home), checkedArtifactId(artifactId), `no artifact ${artifactId}`);
 }
+function readArtifactMetadata(directory) {
+    verifyDirectory(directory);
+    const snapshot = readPrivateStateFileSnapshotSync(join(directory.path, "metadata.json"), JSON_LIMIT);
+    if (!snapshot)
+        throw storeError("ARTIFACT_CORRUPT", "artifact metadata is missing");
+    let value;
+    try {
+        value = JSON.parse(snapshot.text);
+    }
+    catch (error) {
+        throw storeError("ARTIFACT_CORRUPT", "artifact metadata is not valid JSON", error);
+    }
+    if (!isArtifactRecord(value) || value.artifactId !== basename(directory.path)) {
+        throw storeError("ARTIFACT_CORRUPT", "artifact metadata does not match its directory");
+    }
+    verifyDirectory(directory);
+    return { artifact: value, text: snapshot.text };
+}
 function revisionDirectory(artifact, revisionId) {
     const revisions = childDirectory(artifact, "revisions", "artifact revisions are missing");
     return childDirectory(revisions, checkedRevisionId(revisionId), `no revision ${revisionId}`);
@@ -240,25 +303,67 @@ function inspectContent(revision, content, verifyDigest) {
     }
     verifyDirectory(revision);
 }
-function readArtifactDetailsFromDirectory(directory, verifyDigest) {
-    verifyDirectory(directory);
-    const artifactValue = parseJsonFile(join(directory.path, "metadata.json"));
-    if (!isArtifactRecord(artifactValue) || artifactValue.artifactId !== basename(directory.path)) {
-        throw storeError("ARTIFACT_CORRUPT", "artifact metadata does not match its directory");
+function readContentBytes(revision, content) {
+    verifyDirectory(revision);
+    const path = join(revision.path, content.contentRef);
+    const before = lstatSync(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1) {
+        throw storeError("ARTIFACT_CORRUPT", "artifact content is not an immutable regular file");
     }
-    const currentRevisionId = checkedRevisionId(artifactValue.currentRevisionId);
-    const revisionDir = revisionDirectory(directory, currentRevisionId);
+    const fd = openSync(path, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK") | optionalPosixOpenFlag("O_NOFOLLOW"));
+    try {
+        const opened = fstatSync(fd);
+        if (!opened.isFile()
+            || opened.nlink !== 1
+            || !sameOpenedFileIdentity(before, opened)
+            || opened.size !== content.byteSize
+            || (process.platform !== "win32" && (opened.mode & 0o777) !== 0o600))
+            throw storeError("ARTIFACT_CORRUPT", "artifact content identity or size does not match its receipt");
+        const bytes = Buffer.allocUnsafe(content.byteSize);
+        let position = 0;
+        while (position < bytes.length) {
+            const read = readSync(fd, bytes, position, bytes.length - position, position);
+            if (!read)
+                throw storeError("ARTIFACT_CORRUPT", "artifact content ended before its recorded size");
+            position += read;
+        }
+        if (createHash("sha256").update(bytes).digest("hex") !== content.sha256) {
+            throw storeError("ARTIFACT_CORRUPT", "artifact content digest does not match its receipt");
+        }
+        const after = fstatSync(fd);
+        const linked = lstatSync(path);
+        if (!sameOpenedFileIdentity(opened, after)
+            || opened.size !== after.size
+            || opened.mtimeMs !== after.mtimeMs
+            || opened.ctimeMs !== after.ctimeMs
+            || !sameOpenedFileIdentity(after, linked))
+            throw storeError("ARTIFACT_CORRUPT", "artifact content changed while it was read");
+        verifyDirectory(revision);
+        return bytes;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readRevisionDetails(artifact, revisionId, verifyDigest) {
+    const revisionDir = revisionDirectory(artifact, revisionId);
     const revisionValue = parseJsonFile(join(revisionDir.path, "revision.json"));
     const contentValue = parseJsonFile(join(revisionDir.path, "content.json"));
     if (!isRevision(revisionValue)
-        || revisionValue.revisionId !== currentRevisionId
-        || revisionValue.artifactId !== artifactValue.artifactId)
-        throw storeError("ARTIFACT_CORRUPT", "current revision metadata does not match its Artifact");
+        || revisionValue.revisionId !== revisionId
+        || revisionValue.artifactId !== basename(artifact.path))
+        throw storeError("ARTIFACT_CORRUPT", "revision metadata does not match its Artifact");
     if (!isContentInfo(contentValue)
         || contentValue.contentRef !== revisionValue.contentRef
         || contentValue.sha256 !== revisionValue.contentDigest)
-        throw storeError("ARTIFACT_CORRUPT", "current revision content receipt is inconsistent");
+        throw storeError("ARTIFACT_CORRUPT", "revision content receipt is inconsistent");
     inspectContent(revisionDir, contentValue, verifyDigest);
+    return { revision: revisionValue, content: contentValue };
+}
+function readArtifactDetailsFromDirectory(directory, verifyDigest) {
+    const { artifact: artifactValue } = readArtifactMetadata(directory);
+    const currentRevisionId = checkedRevisionId(artifactValue.currentRevisionId);
+    const { revision: revisionValue, content: contentValue } = readRevisionDetails(directory, currentRevisionId, verifyDigest);
     verifyDirectory(directory);
     return { artifact: artifactValue, currentRevision: revisionValue, content: contentValue };
 }
@@ -275,6 +380,29 @@ function titleFor(sourcePath, extension, requested, kind) {
     }
     return title;
 }
+function sourceFormat(sourcePathInput, claimedKind) {
+    if (typeof sourcePathInput !== "string"
+        || !sourcePathInput
+        || sourcePathInput.length > 4_096) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "sourcePath must be a non-empty path of at most 4096 characters");
+    }
+    if (!isAbsolute(sourcePathInput)) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "sourcePath must be an absolute path selected by the user");
+    }
+    const sourcePath = resolve(sourcePathInput);
+    const extension = extname(sourcePath).toLowerCase();
+    if (MACRO_FORMATS.has(extension)) {
+        throw storeError("ARTIFACT_SOURCE_REJECTED", "macro-enabled Office files are not supported; save a macro-free copy before using it as an Artifact revision");
+    }
+    const format = FORMATS.get(extension);
+    if (!format) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "supported files are PPT/PPTX/ODP, XLS/XLSX/CSV/ODS, DOC/DOCX/ODT/RTF, Markdown, and text");
+    }
+    if (claimedKind !== undefined && claimedKind !== format.kind) {
+        throw storeError("ARTIFACT_INVALID_INPUT", `the selected file is ${format.kind}, not ${claimedKind}`);
+    }
+    return { sourcePath, extension, format };
+}
 async function readImportSource(sourcePath) {
     let verified;
     try {
@@ -390,24 +518,6 @@ function activateStaging(root, staging, artifactId) {
     syncDirectory(root.path);
 }
 export async function importArtifact(home, input) {
-    if (typeof input.sourcePath !== "string" || !input.sourcePath || input.sourcePath.length > 4_096) {
-        throw storeError("ARTIFACT_INVALID_INPUT", "sourcePath must be a non-empty path of at most 4096 characters");
-    }
-    if (!isAbsolute(input.sourcePath)) {
-        throw storeError("ARTIFACT_INVALID_INPUT", "sourcePath must be an absolute path selected by the user");
-    }
-    const sourcePath = resolve(input.sourcePath);
-    const extension = extname(sourcePath).toLowerCase();
-    if (MACRO_FORMATS.has(extension)) {
-        throw storeError("ARTIFACT_SOURCE_REJECTED", "macro-enabled Office files are not supported; save a macro-free copy before importing");
-    }
-    const format = FORMATS.get(extension);
-    if (!format) {
-        throw storeError("ARTIFACT_INVALID_INPUT", "supported files are PPT/PPTX/ODP, XLS/XLSX/CSV/ODS, DOC/DOCX/ODT/RTF, Markdown, and text");
-    }
-    if (input.kind !== undefined && input.kind !== format.kind) {
-        throw storeError("ARTIFACT_INVALID_INPUT", `the selected file is ${format.kind}, not ${input.kind}`);
-    }
     if (input.kind !== undefined
         && input.kind !== "presentation"
         && input.kind !== "spreadsheet"
@@ -416,6 +526,7 @@ export async function importArtifact(home, input) {
     if (input.title !== undefined && typeof input.title !== "string") {
         throw storeError("ARTIFACT_INVALID_INPUT", "title must be a string");
     }
+    const { sourcePath, extension, format } = sourceFormat(input.sourcePath, input.kind);
     const bytes = await readImportSource(sourcePath);
     verifyClaimedFormat(extension, bytes);
     const sha256 = createHash("sha256").update(bytes).digest("hex");
@@ -461,6 +572,157 @@ export async function importArtifact(home, input) {
     activateStaging(root, staging, artifactId);
     return getArtifact(home, artifactId, false);
 }
+function activateRevisionStaging(artifact, staging, revisionId) {
+    const revisions = childDirectory(artifact, "revisions", "artifact revisions are missing");
+    verifyDirectory(staging);
+    const destination = join(revisions.path, revisionId);
+    try {
+        lstatSync(destination);
+        throw storeError("ARTIFACT_CORRUPT", "a Revision id collision occurred; retry the commit");
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+    renameSync(staging.path, destination);
+    const activated = lstatSync(destination);
+    if (!activated.isDirectory()
+        || activated.isSymbolicLink()
+        || activated.dev !== staging.dev
+        || activated.ino !== staging.ino
+        || realpathSync.native(destination) !== destination)
+        throw storeError("ARTIFACT_CORRUPT", "Revision activation changed the staged directory identity");
+    verifyDirectory(revisions);
+    syncDirectory(revisions.path);
+}
+function commitPreparedRevision(home, input) {
+    const artifact = artifactDirectory(home, input.artifactId);
+    const metadata = readArtifactMetadata(artifact);
+    if (metadata.artifact.currentRevisionId !== input.baseRevisionId) {
+        throw storeError("ARTIFACT_CONFLICT", "the Artifact changed after this edit started; reopen the latest version and apply the change again");
+    }
+    readRevisionDetails(artifact, metadata.artifact.currentRevisionId, true);
+    const format = FORMATS.get(input.extension);
+    if (!format || format.kind !== metadata.artifact.kind || format.mediaType !== input.mediaType) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "the committed file kind does not match the Artifact");
+    }
+    if (input.bytes.byteLength < 1 || input.bytes.byteLength > MAX_ARTIFACT_IMPORT_BYTES) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "revision content size is outside the supported range");
+    }
+    verifyClaimedFormat(input.extension, input.bytes);
+    const revisions = childDirectory(artifact, "revisions", "artifact revisions are missing");
+    if (readdirSync(revisions.path).length >= MAX_REVISIONS) {
+        throw storeError("ARTIFACT_TOO_LARGE", `artifact has reached the ${MAX_REVISIONS} revision limit`);
+    }
+    const revisionId = newOpaqueId("rev");
+    const sha256 = createHash("sha256").update(input.bytes).digest("hex");
+    const contentRef = `content${input.extension}`;
+    const revision = {
+        revisionId,
+        artifactId: metadata.artifact.artifactId,
+        parentRevisionId: input.baseRevisionId,
+        baseRevisionId: input.baseRevisionId,
+        actor: input.actor,
+        ...(input.taskRunId ? { taskRunId: input.taskRunId } : {}),
+        contentRef,
+        assetRefs: [],
+        contentDigest: sha256,
+        changedPaths: input.changedPaths,
+        createdAt: new Date().toISOString(),
+    };
+    const content = {
+        contentRef,
+        extension: input.extension,
+        mediaType: input.mediaType,
+        byteSize: input.bytes.byteLength,
+        sha256,
+    };
+    const stagingName = `.staging-${revisionId}-${randomUUID().replaceAll("-", "")}`;
+    const staging = ensurePrivateStateSubdirectory(home, [".hara", "artifacts", metadata.artifact.artifactId, stagingName]);
+    writePrivateStateBytesOnceSync(bindPrivateHaraStateFile(home, ["artifacts", metadata.artifact.artifactId, stagingName], contentRef), input.bytes);
+    writePrivateStateFileSync(bindPrivateHaraStateFile(home, ["artifacts", metadata.artifact.artifactId, stagingName], "content.json"), `${JSON.stringify(content, null, 2)}\n`);
+    writePrivateStateFileSync(bindPrivateHaraStateFile(home, ["artifacts", metadata.artifact.artifactId, stagingName], "revision.json"), `${JSON.stringify(revision, null, 2)}\n`);
+    activateRevisionStaging(artifact, staging, revisionId);
+    const updated = {
+        ...metadata.artifact,
+        currentRevisionId: revisionId,
+    };
+    try {
+        writePrivateStateFileSync(bindPrivateHaraStateFile(home, ["artifacts", metadata.artifact.artifactId], "metadata.json"), `${JSON.stringify(updated, null, 2)}\n`, { expectedText: metadata.text });
+    }
+    catch (error) {
+        if (error instanceof PrivateStateConflictError) {
+            throw storeError("ARTIFACT_CONFLICT", "the Artifact changed while this revision was committing; reopen the latest version", error);
+        }
+        throw error;
+    }
+    return getArtifact(home, metadata.artifact.artifactId);
+}
+export async function commitArtifact(home, input) {
+    const artifactId = checkedArtifactId(input.artifactId);
+    const baseRevisionId = checkedInputRevisionId(input.baseRevisionId, "baseRevisionId");
+    const actor = checkedActor(input.actor);
+    const taskRunId = checkedTaskRunId(input.taskRunId);
+    const changedPaths = checkedChangedPaths(input.changedPaths);
+    const before = getArtifact(home, artifactId);
+    if (before.artifact.currentRevisionId !== baseRevisionId) {
+        throw storeError("ARTIFACT_CONFLICT", "the Artifact changed after this edit started; reopen the latest version and apply the change again");
+    }
+    const { sourcePath, extension, format } = sourceFormat(input.sourcePath, before.artifact.kind);
+    const bytes = await readImportSource(sourcePath);
+    verifyClaimedFormat(extension, bytes);
+    return commitPreparedRevision(home, {
+        artifactId,
+        baseRevisionId,
+        extension,
+        mediaType: format.mediaType,
+        bytes,
+        actor,
+        ...(taskRunId ? { taskRunId } : {}),
+        changedPaths,
+    });
+}
+export function revertArtifact(home, input) {
+    const artifactId = checkedArtifactId(input.artifactId);
+    const baseRevisionId = checkedInputRevisionId(input.baseRevisionId, "baseRevisionId");
+    const targetRevisionId = checkedInputRevisionId(input.targetRevisionId, "targetRevisionId");
+    const actor = checkedActor(input.actor);
+    const taskRunId = checkedTaskRunId(input.taskRunId);
+    if (baseRevisionId === targetRevisionId) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "targetRevisionId is already the current revision");
+    }
+    const artifact = artifactDirectory(home, artifactId);
+    const current = readArtifactMetadata(artifact).artifact;
+    if (current.currentRevisionId !== baseRevisionId) {
+        throw storeError("ARTIFACT_CONFLICT", "the Artifact changed after this revert started; reopen the latest version");
+    }
+    const history = listArtifactRevisions(home, artifactId);
+    const byId = new Map(history.map((revision) => [revision.revisionId, revision]));
+    let cursor = byId.get(baseRevisionId);
+    let targetIsAncestor = false;
+    for (let count = 0; cursor && count <= history.length; count++) {
+        if (cursor.revisionId === targetRevisionId) {
+            targetIsAncestor = true;
+            break;
+        }
+        cursor = cursor.parentRevisionId ? byId.get(cursor.parentRevisionId) : undefined;
+    }
+    if (!targetIsAncestor) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "targetRevisionId is not an ancestor of the current revision");
+    }
+    const target = readRevisionDetails(artifact, targetRevisionId, true);
+    const bytes = readContentBytes(revisionDirectory(artifact, targetRevisionId), target.content);
+    return commitPreparedRevision(home, {
+        artifactId,
+        baseRevisionId,
+        extension: target.content.extension,
+        mediaType: target.content.mediaType,
+        bytes,
+        actor,
+        ...(taskRunId ? { taskRunId } : {}),
+        changedPaths: ["content"],
+    });
+}
 export function getArtifact(home, artifactId, verifyDigest = true) {
     return readArtifactDetailsFromDirectory(artifactDirectory(home, artifactId), verifyDigest);
 }

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

@@ -11,6 +11,12 @@ import { sameOpenedFileIdentity } from "../fs-identity.js";
 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");
 }
@@ -397,13 +403,16 @@ export function writePrivateStateBytesOnceSync(binding, bytes) {
  * 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;
@@ -438,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;
             }
         }
@@ -450,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;
@@ -462,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

@@ -29,6 +29,10 @@
 //   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}
@@ -52,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. */

package/dist/serve/server.js

@@ -37,7 +37,7 @@ import { readModelContextFileSync } from "../fs-read.js";
 import { optionalPosixOpenFlag } from "../fs-open-flags.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
 import { redactSensitiveText, redactSensitiveValue } from "../security/secrets.js";
-import { ArtifactStoreError, getArtifact, importArtifact, listArtifactRevisions, listArtifacts, } from "../artifacts/store.js";
+import { ArtifactStoreError, commitArtifact, getArtifact, importArtifact, listArtifactRevisions, listArtifacts, revertArtifact, } from "../artifacts/store.js";
 import { consumePendingTaskSteering, createTaskExecution, continueTaskExecution, finishTaskExecution, newSteerInteraction, newTurnInteraction, recordTaskSteering, requestsTaskContinuation, taskExecutionContext, } from "../session/task.js";
 const APPROVAL_TIMEOUT_MS = 300_000; // an unanswered approval denies after 5 min (never hangs a turn)
 const COMPACT_TIMEOUT_MS = 60_000;
@@ -46,12 +46,18 @@ const SOCKET_CLOSE_GRACE_MS = 250;
 const DISCOVERY_LOCK_WAIT_MS = 2_000;
 const artifactRpcError = (id, error, action) => {
     if (error instanceof ArtifactStoreError) {
-        const code = error.code === "ARTIFACT_CORRUPT" ? ERR.INTERNAL : ERR.PARAMS;
+        const code = error.code === "ARTIFACT_CORRUPT"
+            ? ERR.INTERNAL
+            : error.code === "ARTIFACT_CONFLICT"
+                ? ERR.CONFLICT
+                : ERR.PARAMS;
         return rpcError(id, code, error.message);
     }
-    return rpcError(id, ERR.INTERNAL, action === "import"
-        ? "Artifact import failed safely; the source file was not modified"
-        : `Artifact ${action} failed safely; local Artifact data was not changed`);
+    return rpcError(id, ERR.INTERNAL, action === "import" || action === "commit"
+        ? `Artifact ${action} failed safely; the source file was not modified`
+        : action === "revert"
+            ? "Artifact revert failed safely; no current revision was replaced"
+            : `Artifact ${action} failed safely; local Artifact data was not changed`);
 };
 const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const isPidAlive = (pid) => {
@@ -742,7 +748,8 @@ export async function startServe(opts, deps) {
                             "approval.reply", "plugins.list", "plugins.set", "skills.list", "models.list", "files.search", "project.panels",
                             "settings.providers.list", "settings.providers.test", "settings.providers.save",
                             "automation.list", "automation.add", "automation.toggle", "automation.delete",
-                            "artifact.import", "artifact.list", "artifact.get", "artifact.revisions",
+                            "artifact.import", "artifact.commit", "artifact.revert",
+                            "artifact.list", "artifact.get", "artifact.revisions",
                             "tasks.list", "approvals.list", "approvals.resolve",
                         ];
                         const runtime = runtimeInfo();
@@ -1162,6 +1169,63 @@ export async function startServe(opts, deps) {
                                 return reply(artifactRpcError(id, error, "import"));
                             }
                         }
+                        case "artifact.commit": {
+                            if (typeof p.artifactId !== "string"
+                                || typeof p.baseRevisionId !== "string"
+                                || typeof p.sourcePath !== "string"
+                                || !p.sourcePath) {
+                                return reply(rpcError(id, ERR.PARAMS, "artifactId, baseRevisionId, and sourcePath required"));
+                            }
+                            if (p.actor !== undefined) {
+                                return reply(rpcError(id, ERR.PARAMS, "actor is assigned by the authenticated host"));
+                            }
+                            if (p.taskRunId !== undefined && typeof p.taskRunId !== "string") {
+                                return reply(rpcError(id, ERR.PARAMS, "taskRunId must be a string"));
+                            }
+                            if (p.changedPaths !== undefined && !Array.isArray(p.changedPaths)) {
+                                return reply(rpcError(id, ERR.PARAMS, "changedPaths must be an array"));
+                            }
+                            try {
+                                const details = await commitArtifact(artifactHome, {
+                                    artifactId: p.artifactId,
+                                    baseRevisionId: p.baseRevisionId,
+                                    sourcePath: p.sourcePath,
+                                    actor: "user",
+                                    ...(p.taskRunId !== undefined ? { taskRunId: p.taskRunId } : {}),
+                                    ...(p.changedPaths !== undefined ? { changedPaths: p.changedPaths } : {}),
+                                });
+                                return reply(rpcResult(id, details));
+                            }
+                            catch (error) {
+                                return reply(artifactRpcError(id, error, "commit"));
+                            }
+                        }
+                        case "artifact.revert": {
+                            if (typeof p.artifactId !== "string"
+                                || typeof p.baseRevisionId !== "string"
+                                || typeof p.targetRevisionId !== "string") {
+                                return reply(rpcError(id, ERR.PARAMS, "artifactId, baseRevisionId, and targetRevisionId required"));
+                            }
+                            if (p.actor !== undefined) {
+                                return reply(rpcError(id, ERR.PARAMS, "actor is assigned by the authenticated host"));
+                            }
+                            if (p.taskRunId !== undefined && typeof p.taskRunId !== "string") {
+                                return reply(rpcError(id, ERR.PARAMS, "taskRunId must be a string"));
+                            }
+                            try {
+                                const details = revertArtifact(artifactHome, {
+                                    artifactId: p.artifactId,
+                                    baseRevisionId: p.baseRevisionId,
+                                    targetRevisionId: p.targetRevisionId,
+                                    actor: "user",
+                                    ...(p.taskRunId !== undefined ? { taskRunId: p.taskRunId } : {}),
+                                });
+                                return reply(rpcResult(id, details));
+                            }
+                            catch (error) {
+                                return reply(artifactRpcError(id, error, "revert"));
+                            }
+                        }
                         case "artifact.list": {
                             try {
                                 return reply(rpcResult(id, listArtifacts(artifactHome)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.128.0",
+  "version": "0.129.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "runtime-bootstrap.cjs"