@nanhara/hara 0.127.2 → 0.128.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.128.0 — 2026-07-20 — local deliverable foundation
+
+- Hara Serve now provides the first `artifact/1` local runtime through authenticated
+  `artifact.import`, `artifact.list`, `artifact.get`, and `artifact.revisions` methods. Presentations,
+  spreadsheets, and documents receive opaque Artifact/revision identities and a stable content receipt.
+- Import is copy-on-write and leaves the selected file untouched. The private store rejects relative paths,
+  symbolic links, hard links, protected credential/configuration files, macro-enabled Office extensions,
+  type-confused Office packages, empty files, and files over 64 MiB; activation and immutable binary writes
+  are crash-safe, owner-only, and digest-verified.
+- Local metadata never retains the selected absolute path. Corrupt entries remain hidden without hiding
+  healthy work, and unexpected filesystem failures cross the Desktop RPC boundary as path-free errors.
+- This release intentionally stores and verifies deliverables but does not render, edit, export, or execute
+  them. Those actions remain gated on a matching reviewed Office capability in the next vertical slices.
+- Upgrade with `npm i -g @nanhara/hara@0.128.0`.
+
 ## 0.127.2 — 2026-07-20 — quiet scheduled monitoring
 
 - Cron delivery now supports `--deliver-mode always|on-output|on-error`. Existing jobs retain the

package/README.md

@@ -272,6 +272,13 @@ Type-ahead Enter steers the exact live turn; `/next <message>` queues a separate
 clients use `session.steer` with `expectedTurnId` (durable before ACK) and may pass `newTask: true` to force a
 new execution. The `hara resume` launcher preserves terminal input in both npm/Node and standalone-binary
 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.
 **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/artifacts/store.js

@@ -0,0 +1,530 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readSync, readdirSync, realpathSync, renameSync, } from "node:fs";
+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";
+export const ARTIFACT_PROTOCOL_VERSION = "artifact/1";
+export const MAX_ARTIFACT_IMPORT_BYTES = 64 * 1024 * 1024;
+const MAX_ARTIFACTS = 10_000;
+const MAX_REVISIONS = 10_000;
+const JSON_LIMIT = 512 * 1024;
+const ARTIFACT_ID = /^art_[a-f0-9]{32}$/;
+const REVISION_ID = /^rev_[a-f0-9]{32}$/;
+const SAFE_CONTENT_REF = /^content\.[a-z0-9]{1,12}$/;
+export class ArtifactStoreError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "ArtifactStoreError";
+    }
+}
+const FORMATS = new Map([
+    [".pptx", { kind: "presentation", mediaType: "application/vnd.openxmlformats-officedocument.presentationml.presentation" }],
+    [".ppt", { kind: "presentation", mediaType: "application/vnd.ms-powerpoint" }],
+    [".odp", { kind: "presentation", mediaType: "application/vnd.oasis.opendocument.presentation" }],
+    [".xlsx", { kind: "spreadsheet", mediaType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" }],
+    [".xls", { kind: "spreadsheet", mediaType: "application/vnd.ms-excel" }],
+    [".csv", { kind: "spreadsheet", mediaType: "text/csv" }],
+    [".ods", { kind: "spreadsheet", mediaType: "application/vnd.oasis.opendocument.spreadsheet" }],
+    [".docx", { kind: "document", mediaType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document" }],
+    [".doc", { kind: "document", mediaType: "application/msword" }],
+    [".md", { kind: "document", mediaType: "text/markdown" }],
+    [".txt", { kind: "document", mediaType: "text/plain" }],
+    [".rtf", { kind: "document", mediaType: "application/rtf" }],
+    [".odt", { kind: "document", mediaType: "application/vnd.oasis.opendocument.text" }],
+]);
+const MACRO_FORMATS = new Set([".pptm", ".ppsm", ".xlsm", ".xltm", ".docm", ".dotm"]);
+const ZIP_FORMATS = new Set([".pptx", ".odp", ".xlsx", ".ods", ".docx", ".odt"]);
+const COMPOUND_FORMATS = new Set([".ppt", ".xls", ".doc"]);
+const newOpaqueId = (prefix) => `${prefix}_${randomUUID().replaceAll("-", "")}`;
+const storeError = (code, message, cause) => new ArtifactStoreError(code, message, cause === undefined ? undefined : { cause });
+function verifyDirectory(identity) {
+    const info = lstatSync(identity.path);
+    if (!info.isDirectory()
+        || info.isSymbolicLink()
+        || info.dev !== identity.dev
+        || info.ino !== identity.ino
+        || realpathSync.native(identity.path) !== identity.path)
+        throw storeError("ARTIFACT_CORRUPT", "private artifact directory identity changed");
+}
+function artifactRoot(home) {
+    return ensurePrivateStateSubdirectory(home, [".hara", "artifacts"]);
+}
+function parseJsonFile(path) {
+    const snapshot = readPrivateStateFileSnapshotSync(path, JSON_LIMIT);
+    if (!snapshot)
+        throw storeError("ARTIFACT_CORRUPT", "artifact metadata is missing");
+    try {
+        return JSON.parse(snapshot.text);
+    }
+    catch (error) {
+        throw storeError("ARTIFACT_CORRUPT", "artifact metadata is not valid JSON", error);
+    }
+}
+function plainRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function exactKeys(value, required, optional) {
+    const allowed = new Set([...required, ...optional]);
+    return required.every((key) => Object.hasOwn(value, key))
+        && Object.keys(value).every((key) => allowed.has(key));
+}
+function isArtifactLockRef(value) {
+    if (!plainRecord(value) || !exactKeys(value, ["id", "version", "sha256"], []))
+        return false;
+    return typeof value.id === "string"
+        && value.id.length >= 1
+        && value.id.length <= 256
+        && typeof value.version === "string"
+        && value.version.length >= 1
+        && value.version.length <= 128
+        && typeof value.sha256 === "string"
+        && /^[a-f0-9]{64}$/.test(value.sha256);
+}
+function isArtifactRecord(value) {
+    if (!plainRecord(value) || !exactKeys(value, ["protocol", "artifactId", "kind", "title", "currentRevisionId"], ["origin", "dataResidency", "capabilityLock", "templateLock"]))
+        return false;
+    return value.protocol === ARTIFACT_PROTOCOL_VERSION
+        && typeof value.artifactId === "string"
+        && ARTIFACT_ID.test(value.artifactId)
+        && (value.kind === "presentation" || value.kind === "spreadsheet" || value.kind === "document")
+        && typeof value.title === "string"
+        && value.title.length >= 1
+        && value.title.length <= 1_024
+        && typeof value.currentRevisionId === "string"
+        && REVISION_ID.test(value.currentRevisionId)
+        && (value.origin === undefined || (typeof value.origin === "string" && value.origin.length <= 256))
+        && (value.dataResidency === undefined
+            || value.dataResidency === "local"
+            || value.dataResidency === "cn"
+            || value.dataResidency === "global")
+        && (value.capabilityLock === undefined || isArtifactLockRef(value.capabilityLock))
+        && (value.templateLock === undefined || isArtifactLockRef(value.templateLock));
+}
+function isRevision(value) {
+    if (!plainRecord(value) || !exactKeys(value, [
+        "revisionId",
+        "artifactId",
+        "baseRevisionId",
+        "actor",
+        "contentRef",
+        "assetRefs",
+        "contentDigest",
+        "changedPaths",
+        "createdAt",
+    ], ["parentRevisionId", "taskRunId"]))
+        return false;
+    return typeof value.revisionId === "string"
+        && REVISION_ID.test(value.revisionId)
+        && typeof value.artifactId === "string"
+        && ARTIFACT_ID.test(value.artifactId)
+        && typeof value.baseRevisionId === "string"
+        && REVISION_ID.test(value.baseRevisionId)
+        && (value.parentRevisionId === undefined
+            || (typeof value.parentRevisionId === "string" && REVISION_ID.test(value.parentRevisionId)))
+        && (value.actor === "user" || value.actor === "agent" || value.actor === "migration")
+        && (value.taskRunId === undefined || (typeof value.taskRunId === "string" && value.taskRunId.length > 0))
+        && typeof value.contentRef === "string"
+        && SAFE_CONTENT_REF.test(value.contentRef)
+        && Array.isArray(value.assetRefs)
+        && value.assetRefs.length <= 10_000
+        && value.assetRefs.every((entry) => typeof entry === "string" && entry.length > 0)
+        && typeof value.contentDigest === "string"
+        && /^[a-f0-9]{64}$/.test(value.contentDigest)
+        && Array.isArray(value.changedPaths)
+        && value.changedPaths.length <= 10_000
+        && value.changedPaths.every((entry) => typeof entry === "string" && entry.length > 0)
+        && typeof value.createdAt === "string"
+        && Number.isFinite(Date.parse(value.createdAt));
+}
+function isContentInfo(value) {
+    if (!plainRecord(value) || !exactKeys(value, ["contentRef", "extension", "mediaType", "byteSize", "sha256"], []))
+        return false;
+    return typeof value.contentRef === "string"
+        && SAFE_CONTENT_REF.test(value.contentRef)
+        && typeof value.extension === "string"
+        && /^\.[a-z0-9]{1,12}$/.test(value.extension)
+        && value.contentRef === `content${value.extension}`
+        && typeof value.mediaType === "string"
+        && value.mediaType.length > 0
+        && typeof value.byteSize === "number"
+        && Number.isSafeInteger(value.byteSize)
+        && value.byteSize >= 0
+        && value.byteSize <= MAX_ARTIFACT_IMPORT_BYTES
+        && typeof value.sha256 === "string"
+        && /^[a-f0-9]{64}$/.test(value.sha256);
+}
+function checkedArtifactId(value) {
+    if (!ARTIFACT_ID.test(value)) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "artifactId is not a valid opaque Artifact id");
+    }
+    return value;
+}
+function checkedRevisionId(value) {
+    if (!REVISION_ID.test(value)) {
+        throw storeError("ARTIFACT_CORRUPT", "revision id is invalid");
+    }
+    return value;
+}
+function childDirectory(parent, name, notFoundMessage) {
+    verifyDirectory(parent);
+    const path = join(parent.path, name);
+    let info;
+    try {
+        info = lstatSync(path);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            throw storeError("ARTIFACT_NOT_FOUND", notFoundMessage);
+        throw error;
+    }
+    if (!info.isDirectory()
+        || info.isSymbolicLink()
+        || realpathSync.native(path) !== path)
+        throw storeError("ARTIFACT_CORRUPT", "artifact directory is not a canonical private directory");
+    verifyDirectory(parent);
+    return { path, dev: info.dev, ino: info.ino };
+}
+function artifactDirectory(home, artifactId) {
+    return childDirectory(artifactRoot(home), checkedArtifactId(artifactId), `no artifact ${artifactId}`);
+}
+function revisionDirectory(artifact, revisionId) {
+    const revisions = childDirectory(artifact, "revisions", "artifact revisions are missing");
+    return childDirectory(revisions, checkedRevisionId(revisionId), `no revision ${revisionId}`);
+}
+function inspectContent(revision, content, verifyDigest) {
+    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 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");
+        if (verifyDigest) {
+            const hash = createHash("sha256");
+            const chunk = Buffer.allocUnsafe(64 * 1024);
+            let position = 0;
+            for (;;) {
+                const read = readSync(fd, chunk, 0, chunk.length, position);
+                if (!read)
+                    break;
+                hash.update(chunk.subarray(0, read));
+                position += read;
+            }
+            if (hash.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 inspected");
+    }
+    finally {
+        closeSync(fd);
+    }
+    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");
+    }
+    const currentRevisionId = checkedRevisionId(artifactValue.currentRevisionId);
+    const revisionDir = revisionDirectory(directory, currentRevisionId);
+    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");
+    if (!isContentInfo(contentValue)
+        || contentValue.contentRef !== revisionValue.contentRef
+        || contentValue.sha256 !== revisionValue.contentDigest)
+        throw storeError("ARTIFACT_CORRUPT", "current revision content receipt is inconsistent");
+    inspectContent(revisionDir, contentValue, verifyDigest);
+    verifyDirectory(directory);
+    return { artifact: artifactValue, currentRevision: revisionValue, content: contentValue };
+}
+function titleFor(sourcePath, extension, requested, kind) {
+    const raw = requested ?? basename(sourcePath, extension);
+    const cleaned = raw
+        .normalize("NFC")
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    const title = cleaned || `Untitled ${kind}`;
+    if (title.length > 1_024) {
+        throw storeError("ARTIFACT_INVALID_INPUT", "artifact title must be at most 1024 characters");
+    }
+    return title;
+}
+async function readImportSource(sourcePath) {
+    let verified;
+    try {
+        verified = await openVerifiedRegularFileNoFollow(sourcePath, {
+            action: "import as an Artifact",
+            rejectHardLinks: true,
+            protectSensitive: true,
+        });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            throw storeError("ARTIFACT_SOURCE_REJECTED", "the selected source file no longer exists", error);
+        }
+        if (error?.code === "HARA_PROTECTED_CONTEXT_FILE") {
+            throw storeError("ARTIFACT_SOURCE_REJECTED", "protected credential/configuration files cannot be imported", error);
+        }
+        if (error?.code === "HARA_HARD_LINKED_FILE") {
+            throw storeError("ARTIFACT_SOURCE_REJECTED", "hard-linked source files cannot be imported safely", error);
+        }
+        if (error?.code === "HARA_NOT_REGULAR_FILE" || error?.code === "ELOOP") {
+            throw storeError("ARTIFACT_SOURCE_REJECTED", "the selected source must be a regular file, not a link or device", error);
+        }
+        throw error;
+    }
+    try {
+        const { handle, info } = verified;
+        if (info.size > MAX_ARTIFACT_IMPORT_BYTES) {
+            throw storeError("ARTIFACT_TOO_LARGE", `the selected file exceeds the ${MAX_ARTIFACT_IMPORT_BYTES / (1024 * 1024)} MiB import limit`);
+        }
+        if (info.size === 0) {
+            throw storeError("ARTIFACT_INVALID_INPUT", "an empty file cannot be imported as an Artifact");
+        }
+        const bytes = Buffer.allocUnsafe(info.size);
+        let position = 0;
+        while (position < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, position, bytes.length - position, position);
+            if (!bytesRead) {
+                throw storeError("ARTIFACT_SOURCE_REJECTED", "the selected file changed while it was being imported");
+            }
+            position += bytesRead;
+        }
+        const after = await handle.stat();
+        verifyOpenedRegularFileSync(sourcePath, after, {
+            action: "import as an Artifact",
+            rejectHardLinks: true,
+            protectSensitive: true,
+        });
+        if (after.dev !== info.dev
+            || after.ino !== info.ino
+            || after.size !== info.size
+            || after.mtimeMs !== info.mtimeMs
+            || after.ctimeMs !== info.ctimeMs)
+            throw storeError("ARTIFACT_SOURCE_REJECTED", "the selected file changed while it was being imported");
+        return bytes;
+    }
+    finally {
+        await verified.handle.close().catch(() => { });
+    }
+}
+function verifyClaimedFormat(extension, bytes) {
+    const startsWith = (signature) => bytes.length >= signature.length
+        && signature.every((value, index) => bytes[index] === value);
+    if (ZIP_FORMATS.has(extension) && !startsWith([0x50, 0x4b, 0x03, 0x04])) {
+        throw storeError("ARTIFACT_SOURCE_REJECTED", "the selected Office file does not match its extension; save an unencrypted, macro-free copy and try again");
+    }
+    if (COMPOUND_FORMATS.has(extension)
+        && !startsWith([0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1])) {
+        throw storeError("ARTIFACT_SOURCE_REJECTED", "the selected legacy Office file does not match its extension");
+    }
+    if (extension === ".rtf"
+        && !bytes.subarray(0, Math.min(bytes.length, 32)).toString("utf8").replace(/^\uFEFF/, "").startsWith("{\\rtf")) {
+        throw storeError("ARTIFACT_SOURCE_REJECTED", "the selected RTF file does not match its extension");
+    }
+}
+function syncDirectory(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY
+            | optionalPosixOpenFlag("O_NONBLOCK")
+            | optionalPosixOpenFlag("O_NOFOLLOW")
+            | optionalPosixOpenFlag("O_DIRECTORY"));
+        fsyncSync(fd);
+    }
+    catch {
+        /* Directory fsync is not portable; every staged file is still fsync'd before activation. */
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function activateStaging(root, staging, artifactId) {
+    verifyDirectory(root);
+    verifyDirectory(staging);
+    const destination = join(root.path, artifactId);
+    try {
+        lstatSync(destination);
+        throw storeError("ARTIFACT_CORRUPT", "an Artifact id collision occurred; retry the import");
+    }
+    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", "Artifact activation changed the staged directory identity");
+    verifyDirectory(root);
+    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"
+        && input.kind !== "document")
+        throw storeError("ARTIFACT_INVALID_INPUT", "kind must be presentation, spreadsheet, or document");
+    if (input.title !== undefined && typeof input.title !== "string") {
+        throw storeError("ARTIFACT_INVALID_INPUT", "title must be a string");
+    }
+    const bytes = await readImportSource(sourcePath);
+    verifyClaimedFormat(extension, bytes);
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    const artifactId = newOpaqueId("art");
+    const revisionId = newOpaqueId("rev");
+    const now = new Date().toISOString();
+    const contentRef = `content${extension}`;
+    const artifact = {
+        protocol: ARTIFACT_PROTOCOL_VERSION,
+        artifactId,
+        kind: format.kind,
+        title: titleFor(sourcePath, extension, input.title, format.kind),
+        currentRevisionId: revisionId,
+        origin: "local-import",
+        dataResidency: "local",
+    };
+    const revision = {
+        revisionId,
+        artifactId,
+        baseRevisionId: revisionId,
+        actor: "user",
+        contentRef,
+        assetRefs: [],
+        contentDigest: sha256,
+        changedPaths: ["content"],
+        createdAt: now,
+    };
+    const content = {
+        contentRef,
+        extension,
+        mediaType: format.mediaType,
+        byteSize: bytes.byteLength,
+        sha256,
+    };
+    const root = artifactRoot(home);
+    const stagingName = `.staging-${artifactId}-${randomUUID().replaceAll("-", "")}`;
+    const staging = ensurePrivateStateSubdirectory(home, [".hara", "artifacts", stagingName]);
+    ensurePrivateStateSubdirectory(home, [".hara", "artifacts", stagingName, "revisions", revisionId]);
+    writePrivateStateBytesOnceSync(bindPrivateHaraStateFile(home, ["artifacts", stagingName, "revisions", revisionId], contentRef), bytes);
+    writePrivateStateFileSync(bindPrivateHaraStateFile(home, ["artifacts", stagingName, "revisions", revisionId], "content.json"), `${JSON.stringify(content, null, 2)}\n`);
+    writePrivateStateFileSync(bindPrivateHaraStateFile(home, ["artifacts", stagingName, "revisions", revisionId], "revision.json"), `${JSON.stringify(revision, null, 2)}\n`);
+    writePrivateStateFileSync(bindPrivateHaraStateFile(home, ["artifacts", stagingName], "metadata.json"), `${JSON.stringify(artifact, null, 2)}\n`);
+    activateStaging(root, staging, artifactId);
+    return getArtifact(home, artifactId, false);
+}
+export function getArtifact(home, artifactId, verifyDigest = true) {
+    return readArtifactDetailsFromDirectory(artifactDirectory(home, artifactId), verifyDigest);
+}
+export function listArtifacts(home) {
+    const root = artifactRoot(home);
+    verifyDirectory(root);
+    const entries = readdirSync(root.path, { withFileTypes: true });
+    const candidates = entries.filter((entry) => !entry.name.startsWith("."));
+    const artifacts = [];
+    let invalid = 0;
+    for (const entry of candidates.slice(0, MAX_ARTIFACTS)) {
+        if (!entry.isDirectory() || !ARTIFACT_ID.test(entry.name)) {
+            invalid += 1;
+            continue;
+        }
+        try {
+            const directory = childDirectory(root, entry.name, `no artifact ${entry.name}`);
+            const details = readArtifactDetailsFromDirectory(directory, false);
+            artifacts.push({
+                artifactId: details.artifact.artifactId,
+                kind: details.artifact.kind,
+                title: details.artifact.title,
+                currentRevisionId: details.artifact.currentRevisionId,
+                updatedAt: details.currentRevision.createdAt,
+                extension: details.content.extension,
+                mediaType: details.content.mediaType,
+                byteSize: details.content.byteSize,
+            });
+        }
+        catch {
+            invalid += 1;
+        }
+    }
+    verifyDirectory(root);
+    artifacts.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.artifactId.localeCompare(b.artifactId));
+    return {
+        artifacts,
+        invalid,
+        truncated: candidates.length > MAX_ARTIFACTS,
+    };
+}
+export function listArtifactRevisions(home, artifactId) {
+    const artifact = artifactDirectory(home, artifactId);
+    const metadata = parseJsonFile(join(artifact.path, "metadata.json"));
+    if (!isArtifactRecord(metadata) || metadata.artifactId !== artifactId) {
+        throw storeError("ARTIFACT_CORRUPT", "artifact metadata does not match its directory");
+    }
+    const revisions = childDirectory(artifact, "revisions", "artifact revisions are missing");
+    const entries = readdirSync(revisions.path, { withFileTypes: true });
+    if (entries.length > MAX_REVISIONS) {
+        throw storeError("ARTIFACT_CORRUPT", `artifact has more than ${MAX_REVISIONS} revisions`);
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !REVISION_ID.test(entry.name)) {
+            throw storeError("ARTIFACT_CORRUPT", "artifact contains an invalid revision entry");
+        }
+        const directory = childDirectory(revisions, entry.name, `no revision ${entry.name}`);
+        const value = parseJsonFile(join(directory.path, "revision.json"));
+        if (!isRevision(value) || value.revisionId !== entry.name || value.artifactId !== artifactId) {
+            throw storeError("ARTIFACT_CORRUPT", "revision metadata does not match its directory");
+        }
+        out.push(value);
+    }
+    verifyDirectory(revisions);
+    return out.sort((a, b) => b.createdAt.localeCompare(a.createdAt) || a.revisionId.localeCompare(b.revisionId));
+}

package/dist/security/private-state.js

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

package/dist/serve/protocol.js

@@ -28,6 +28,10 @@
 //                                                               → {id,name,schedule}
 //   automation.toggle {id,enabled}                → {id,enabled}
 //   automation.delete {id}                        → {id,deleted}
+//   artifact.import   {sourcePath,title?,kind?}    → {artifact,currentRevision,content}
+//   artifact.list     {}                          → {artifacts,invalid,truncated}
+//   artifact.get      {artifactId}                → {artifact,currentRevision,content}
+//   artifact.revisions {artifactId}               → {artifactId,revisions}
 //   session.rename    {sessionId,title}           → {sessionId,title}
 //   session.archive   {sessionId,archived}        → {sessionId,archived}   (list hides archived unless {archived:true})
 //   session.set-model {sessionId,model?,effort?}  → {sessionId,model,effort} (next turn; refused mid-turn)

package/dist/serve/server.js

@@ -37,12 +37,22 @@ 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 { 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;
 const SHUTDOWN_GRACE_MS = 2_000;
 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;
+        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`);
+};
 const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const isPidAlive = (pid) => {
     if (!Number.isSafeInteger(pid) || pid <= 0)
@@ -349,6 +359,7 @@ export async function startServe(opts, deps) {
     };
     // Discovery file — the desktop shell reads this to find the running server (like a pid/port file).
     const discoveryDir = join(deps.discoveryHome ?? homedir(), ".hara");
+    const artifactHome = deps.artifactHome ?? homedir();
     const discoveryPath = join(discoveryDir, "serve.json");
     const discovery = { host: opts.host, port, token, pid: process.pid, version: deps.version, instanceId };
     if (!deps.quietDiscovery) {
@@ -731,6 +742,7 @@ 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",
                             "tasks.list", "approvals.list", "approvals.resolve",
                         ];
                         const runtime = runtimeInfo();
@@ -1126,6 +1138,61 @@ export async function startServe(opts, deps) {
                                 return reply(rpcError(id, ERR.PARAMS, `no job ${p.id}`));
                             return reply(rpcResult(id, { id: p.id, deleted: true }));
                         }
+                        case "artifact.import": {
+                            if (typeof p.sourcePath !== "string" || !p.sourcePath) {
+                                return reply(rpcError(id, ERR.PARAMS, "sourcePath required"));
+                            }
+                            if (p.kind !== undefined
+                                && p.kind !== "presentation"
+                                && p.kind !== "spreadsheet"
+                                && p.kind !== "document")
+                                return reply(rpcError(id, ERR.PARAMS, "kind must be presentation, spreadsheet, or document"));
+                            if (p.title !== undefined && typeof p.title !== "string") {
+                                return reply(rpcError(id, ERR.PARAMS, "title must be a string"));
+                            }
+                            try {
+                                const details = await importArtifact(artifactHome, {
+                                    sourcePath: p.sourcePath,
+                                    ...(p.title !== undefined ? { title: p.title } : {}),
+                                    ...(p.kind !== undefined ? { kind: p.kind } : {}),
+                                });
+                                return reply(rpcResult(id, details));
+                            }
+                            catch (error) {
+                                return reply(artifactRpcError(id, error, "import"));
+                            }
+                        }
+                        case "artifact.list": {
+                            try {
+                                return reply(rpcResult(id, listArtifacts(artifactHome)));
+                            }
+                            catch (error) {
+                                return reply(artifactRpcError(id, error, "list"));
+                            }
+                        }
+                        case "artifact.get": {
+                            if (typeof p.artifactId !== "string") {
+                                return reply(rpcError(id, ERR.PARAMS, "artifactId required"));
+                            }
+                            try {
+                                return reply(rpcResult(id, getArtifact(artifactHome, p.artifactId)));
+                            }
+                            catch (error) {
+                                return reply(artifactRpcError(id, error, "open"));
+                            }
+                        }
+                        case "artifact.revisions": {
+                            if (typeof p.artifactId !== "string") {
+                                return reply(rpcError(id, ERR.PARAMS, "artifactId required"));
+                            }
+                            try {
+                                const revisions = listArtifactRevisions(artifactHome, p.artifactId);
+                                return reply(rpcResult(id, { artifactId: p.artifactId, revisions }));
+                            }
+                            catch (error) {
+                                return reply(artifactRpcError(id, error, "list revisions"));
+                            }
+                        }
                         case "skills.list": {
                             const cwd = typeof p.cwd === "string" && p.cwd ? p.cwd : opts.cwd;
                             return reply(rpcResult(id, { skills: loadSkillIndex(cwd).map((s) => ({ id: s.id, description: s.description, source: s.source })) }));

package/package.json

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