@nanhara/hara 0.128.0 → 0.130.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.130.0 — 2026-07-20 — ordered task-state delivery
+
+- Typed `event.task_state` notifications now carry a server-stream identity and a positive,
+  monotonically increasing sequence. Desktop and other authenticated Serve clients can reject
+  duplicated or stale lifecycle transitions instead of letting a late event overwrite the current
+  task, approval, checkpoint, or completion state.
+- Ordering spans every session and every resume within one `hara serve` process. A server restart
+  creates a new stream identity, so clients can accept the fresh sequence without confusing it with
+  an older connection.
+- Conversation streaming remains independent from execution state, and task event payloads retain
+  the same redacted ambient-data boundary. Existing protocol-v1 clients remain compatible because
+  the ordering fields are additive.
+- Upgrade with `npm i -g @nanhara/hara@0.130.0`.
+
+## 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();