artifacty 0.13.0 → 0.14.0

package/docs/upgrade-backups.md

@@ -1,9 +1,54 @@
 # Upgrade Snapshots and Recovery
 
+English | [한국어](ko/upgrade-backups.md)
+
 Artifacty creates a local snapshot before it migrates an existing store to a newer schema. This snapshot is mandatory. If snapshot creation or verification fails, Artifacty stops before migration.
 
 Use upgrade snapshots to recover the original store state. Use `artifacty backup` and `artifacty export` for portable JSON backups and store transfers. These are separate backup systems. `artifacty restore <id>` restores an archived artifact; it does not restore a store snapshot.
 
+## Application Self-Update
+
+The application updater and schema migration snapshots serve different purposes. `artifacty update` without an artifact ID updates the application. `artifacty upgrade` is an alias. `artifacty update <id>` continues to update an artifact.
+
+### Check and select a release
+
+```bash
+artifacty update --check
+artifacty upgrade --check --target-version <version> --home /path/to/store
+```
+
+`--check` reports the release without changing the installation, service, or store. It works on other CLI platforms too and reports whether automatic installation is supported. It still needs network access to check the release. For the managed service, the updater compares the package version used by that service, not just the invoking CLI version. `--target-version` accepts an exact version. Without that option, the updater selects the latest release. `--home` selects the store to protect. Automatic downgrades are not supported. An explicitly selected older version is rejected; an older `latest` release leaves the newer installation unchanged.
+
+For installed versions before 0.14.0, bootstrap the updater with:
+
+```bash
+npx --yes artifacty@latest update --home /path/to/store && export PATH="$HOME/.local/bin:$PATH"
+```
+
+The command uses POSIX Linux shell syntax. After a successful update, it puts `~/.local/bin` first on `PATH` for the current session. For future sessions, add that directory to your shell's `PATH`.
+
+The `latest` tag must resolve to version 0.14.0 or newer to include the updater.
+
+### Automatic installation limits
+
+Automatic installation and restart support Linux with the systemd user service `com.artifacty.server`. Run the updater as the service's user. The unit must use the simple `ExecStart` form produced by Artifacty's installer and must explicitly pass `--home` for the selected store. Unsupported command expansion or quoting stops the update before service shutdown. Automatic updates reject root execution. Do not run the updater as root to replace a root-owned global package.
+
+The updater stages packages under `~/.local/share/artifacty/releases`. It changes the managed service's executable through a systemd drop-in and preserves its existing arguments and environment. User-owned launchers go under `~/.local/bin`. If that directory is not on `PATH`, add it before using those launchers. Existing unmanaged files in that directory are not overwritten. The existing root-owned global package remains unchanged. If `PATH` selects another command first, the result supplies an absolute `nextCommand`. The updater does not edit shell configuration.
+
+Automatic switching does not support macOS, Windows, foreground servers, detached background servers, or arbitrary service units. Use the manual installation and snapshot procedures for those environments.
+
+### Store protection and rollback
+
+Before updating, stop other HTTP servers and local MCP clients that use the same store. The updater manages the supported systemd service itself. It cannot identify every other process with an open store. The service is unavailable during the update. A store rollback discards writes made after the snapshot; do not keep other writers active during this procedure.
+
+For an active service, the updater checks current health before shutdown. If its bind address or IP policy prevents that check, it refuses the update before downtime. Unsupported service configurations also fail before shutdown.
+
+The updater installs and verifies the exact target package in its staging directory. It then stops the managed service and creates and verifies a snapshot before switching code. If the service was active, it restarts the service and checks its health and PID. An inactive service remains inactive. It preserves the previous code and service configuration for rollback. If switching or startup fails, it attempts to restore the changed code, service configuration, and store, then restart the previous service. If service stop fails, it does not restore a store while the service may still be writing to it. A restored store includes the snapshot's credentials and security state. Review any recovery error before allowing clients to reconnect.
+
+An abrupt process or host termination during the switch can leave `update.lock` or a stopped service. The next update reports the lock instead of retrying blindly. Preserve snapshots, staged releases, and recovery files. Inspect the service and recovery state before a manual retry. Automatic rollback handles caught failures; it does not guarantee recovery from power loss or forced process termination.
+
+Keep the snapshot and the update result until the restarted service works. If automatic rollback cannot finish, the updater reports an explicit error and preserves the `backupId`. Use that snapshot with the recovery procedures below. Do not delete recovery files or force an older build to open an unsupported schema.
+
 ## When Artifacty Creates a Snapshot
 
 - **Schema migration:** Artifacty always snapshots an existing store before migration. This includes a legacy `index.json` store. A new empty store needs no snapshot.

package/docs/writing-style.md

@@ -1,5 +1,7 @@
 # Documentation writing style
 
+English | [한국어](ko/writing-style.md)
+
 Artifacty uses an ASD-STE100-inspired style for English documentation. Korean documentation follows the same clarity principles with natural Korean phrasing. This is an editorial guide, not a claim of compliance with ASD-STE100.
 
 Apply the sentence and procedure rules consistently. Use technical vocabulary where it makes the meaning more precise. Keep introductions natural. The project's “75%” target describes this balance; it is not a compliance score.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifacty",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Local artifact exchange for heterogeneous LLM agents via HTTP and MCP.",
   "type": "module",
   "keywords": [
@@ -53,7 +53,12 @@
     "SECURITY.md",
     "THIRD_PARTY_NOTICES.md",
     "AGENTS.md",
-    "CLAUDE.md"
+    "CLAUDE.md",
+    "README.ko.md",
+    "SECURITY.ko.md",
+    "docs/README.md",
+    "docs/ko",
+    "docs/claude-artifact-formats.md"
   ],
   "engines": {
     "node": ">=22.12"

package/src/cli.js

@@ -33,6 +33,25 @@ async function main() {
     return;
   }
 
+  // Application updates must not initialize or migrate the live store first.
+  // Keep `update <id>` as the existing artifact-content command.
+  if ((command === "update" && options._.length === 0) || command === "upgrade") {
+    const allowed = new Set(["_", "home", "targetVersion", "check"]);
+    const unknown = Object.keys(options).filter((key) => !allowed.has(key));
+    if (options._.length || unknown.length) {
+      throw new Error("Usage: artifacty update [--check] [--target-version <version>] [--home <path>]. To update content, use artifacty update <id> --file <path>.");
+    }
+    const { updateApplication } = await import("./lib/self-update.js");
+    printJson(await updateApplication({
+      packageRoot: PACKAGE_ROOT,
+      home: options.home,
+      targetVersion: options.targetVersion,
+      check: Boolean(options.check),
+      onProgress: (message) => process.stderr.write(`artifacty update: ${message}\n`)
+    }));
+    return;
+  }
+
   // Recovery must work before loading storage or triggering a schema migration.
   if (command === "backups") {
     const { listUpgradeBackups, verifyUpgradeBackup, restoreUpgradeBackup } = await import("./lib/upgrade-backup.js");
@@ -898,7 +917,7 @@ function parseArgs(args) {
     }
 
     const key = arg.slice(2);
-    if (key === "raw" || key === "dry-run" || key === "trust" || key === "include-archived" || key === "allow-secrets" || key === "generate-token" || key === "detach" || key === "foreground" || key === "force" || key === "skip-mcp" || key === "mcp-http" || key === "no-password-reset" || key === "relations" || key === "structured" || key === "json" || key === "once" || key === "full" || key === "force-users" || key === "allow-purge" || key === "shared" || key === "embeddings") {
+    if (key === "check" || key === "raw" || key === "dry-run" || key === "trust" || key === "include-archived" || key === "allow-secrets" || key === "generate-token" || key === "detach" || key === "foreground" || key === "force" || key === "skip-mcp" || key === "mcp-http" || key === "no-password-reset" || key === "relations" || key === "structured" || key === "json" || key === "once" || key === "full" || key === "force-users" || key === "allow-purge" || key === "shared" || key === "embeddings") {
       options[toCamelCase(key)] = true;
       continue;
     }
@@ -991,6 +1010,8 @@ Usage:
   artifacty import --agent claude|codex|gemini|copilot|cursor|auto (--file <path> | --content <text>) [--title <title>] [--format html|markdown|text|json|code|svg|mermaid|react|notebook] [--tag tag]
   artifacty install claude|codex|gemini|copilot|cursor|all [--dry-run] [--config <path>] [--server-path <path>] [--url http://127.0.0.1:8787] [--mcp-url http://127.0.0.1:8787/mcp] [--api-token token] [--transport local|bridge] [--timeout 30000]
   artifacty check [--server-path <path>] [--timeout 5000]
+  artifacty update [--check] [--target-version <version>] [--home <path>]
+  artifacty upgrade [--check] [--target-version <version>] [--home <path>]
   artifacty update <id> (--file <path> | --content <text>) [--title <title>] [--format html|markdown|text|json|code|svg|mermaid|react|notebook] [--expected-version N] [--visibility private|team]
   artifacty samples install|remove
   artifacty archive <id>

package/src/lib/render.js

@@ -2845,9 +2845,13 @@ export function pageShell({ title, body, head = "", afterBody = "", locale = DEF
       margin-left: -20px;
     }
     .task-list-item label {
-      display: inline-flex;
-      align-items: baseline;
-      gap: 8px;
+      display: block;
+    }
+    .task-list-item input[type="checkbox"] {
+      width: auto;
+      min-height: 0;
+      padding: 0;
+      margin: 0 8px 0 0;
     }
     .artifact-mermaid-embed {
       margin: 16px 0;

package/src/lib/self-update.js

@@ -0,0 +1,339 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { access, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { createUpgradeBackup, verifyUpgradeBackup, restoreUpgradeBackup } from "./upgrade-backup.js";
+
+const execute = promisify(execFile);
+const UNIT = "com.artifacty.server.service";
+const LAUNCHER_MARK = "// artifacty-managed-launcher";
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const failure = (message, code = "SELF_UPDATE_FAILED") => Object.assign(new Error(message), { code });
+
+function compareVersions(left, right) {
+  const parse = (value) => { const [core, ...pre] = value.split("+")[0].split("-"); return { core: core.split(".").map(Number), pre: pre.join("-") }; };
+  const a = parse(left); const b = parse(right);
+  for (let index = 0; index < 3; index++) if (a.core[index] !== b.core[index]) return a.core[index] > b.core[index] ? 1 : -1;
+  if (!a.pre || !b.pre) return a.pre === b.pre ? 0 : !a.pre ? 1 : -1;
+  const ap = a.pre.split("."); const bp = b.pre.split(".");
+  for (let index = 0; index < Math.max(ap.length, bp.length); index++) {
+    if (ap[index] === bp[index]) continue;
+    if (ap[index] === undefined) return -1;
+    if (bp[index] === undefined) return 1;
+    const an = /^\d+$/.test(ap[index]); const bn = /^\d+$/.test(bp[index]);
+    if (an && bn) return Number(ap[index]) > Number(bp[index]) ? 1 : -1;
+    if (an !== bn) return an ? -1 : 1;
+    return ap[index] > bp[index] ? 1 : -1;
+  }
+  return 0;
+}
+
+async function readOptional(file) {
+  try { return await readFile(file, "utf8"); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+function quoteUnit(value) {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
+}
+
+// Accept the simple ExecStart form produced by Artifacty's service installer.
+// Reject specifiers, environment expansion, and ambiguous quoting before stopping it.
+function unitArguments(text) {
+  const commands = [];
+  for (const line of text.replace(/\\\n\s*/g, " ").split("\n")) {
+    if (!line.startsWith("ExecStart=")) continue;
+    const command = line.slice(10).trim();
+    if (!command) commands.length = 0;
+    else commands.push(command);
+  }
+  if (commands.length !== 1 || /[$%\r\n]/.test(commands[0])) throw failure("Unsupported service ExecStart. No changes were made.", "UNSUPPORTED_SERVICE");
+  const args = [];
+  const expression = /\s*(?:"((?:[^"\\]|\\["\\])*)"|'([^']*)'|([^\s"'\\]+))/gy;
+  let offset = 0;
+  while (offset < commands[0].length) {
+    expression.lastIndex = offset;
+    const match = expression.exec(commands[0]);
+    if (!match) throw failure("Unsupported service argument quoting", "UNSUPPORTED_SERVICE");
+    args.push(match[1] !== undefined ? match[1].replace(/\\(["\\])/g, "$1") : match[2] ?? match[3]);
+    offset = expression.lastIndex;
+  }
+  if (args.length < 2 || !path.isAbsolute(args[0]) || !path.isAbsolute(args[1]) || !args[1].endsWith("/src/server.js")) {
+    throw failure("The user service does not run an identifiable Artifacty server", "UNSUPPORTED_SERVICE");
+  }
+  return args;
+}
+
+async function packageAt(root) {
+  const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+  if (manifest.name !== "artifacty" || !VERSION.test(manifest.version)) throw failure("Invalid Artifacty package metadata");
+  return manifest;
+}
+
+async function discoverService(run, home) {
+  const result = await run("systemctl", ["--user", "show", UNIT, "--no-pager", "--property=LoadState,ActiveState,MainPID"]);
+  const properties = Object.fromEntries(result.stdout.trim().split("\n").map((line) => {
+    const index = line.indexOf("="); return [line.slice(0, index), line.slice(index + 1)];
+  }));
+  if (properties.LoadState !== "loaded" || !["active", "inactive", "failed"].includes(properties.ActiveState)) {
+    throw failure("Install a stable Artifacty systemd user service before automatic updates", "UNSUPPORTED_SERVICE");
+  }
+  const text = (await run("systemctl", ["--user", "cat", UNIT, "--no-pager"])).stdout;
+  const args = unitArguments(text);
+  if (args.filter((arg) => arg === "--home").length !== 1) throw failure("The service must have exactly one --home argument", "SERVICE_HOME_MISMATCH");
+  const homeIndex = args.indexOf("--home");
+  if (homeIndex < 0 || !args[homeIndex + 1] || path.resolve(args[homeIndex + 1]) !== home) {
+    throw failure("The service must explicitly use the selected --home directory", "SERVICE_HOME_MISMATCH");
+  }
+  const packageRoot = path.dirname(path.dirname(args[1]));
+  const manifest = await packageAt(packageRoot);
+  const pid = Number(properties.MainPID);
+  if (properties.ActiveState === "active" && (!Number.isInteger(pid) || pid <= 0)) throw failure("Cannot identify the running service process");
+  return { args, text, packageRoot, version: manifest.version, pid, active: properties.ActiveState === "active" };
+}
+
+async function assertNoOtherWriters({ home, allowedPid, ownPid = process.pid, processRoot = "/proc" }) {
+  const canonicalHome = await realpath(home);
+  for (const entry of await readdir(processRoot)) {
+    if (!/^\d+$/.test(entry) || Number(entry) === ownPid || Number(entry) === allowedPid) continue;
+    const directory = path.join(processRoot, entry);
+    let args;
+    try {
+      const owner = await lstat(directory);
+      if (process.getuid && owner.uid !== process.getuid()) continue;
+      args = (await readFile(`${directory}/cmdline`, "utf8")).split("\0").filter(Boolean);
+    } catch (error) {
+      if (["ENOENT", "ESRCH"].includes(error.code)) continue;
+      throw failure("Cannot inspect another user process; stop other clients before updating", "UNMANAGED_WRITER");
+    }
+    for (const argument of args.slice(1)) {
+      if (!/(?:server\.js|cli\.js|artifacty(?:-mcp)?)$/.test(argument)) continue;
+      let source;
+      let cwd;
+      try { cwd = await realpath(`${directory}/cwd`); source = await realpath(path.resolve(cwd, argument)); }
+      catch { continue; }
+      if (!/\/src\/(?:mcp-server|server|cli)\.js$/.test(source)) continue;
+      try { await packageAt(path.dirname(path.dirname(source))); } catch { continue; }
+      const indices = args.flatMap((arg, index) => arg === "--home" ? [index] : []);
+      if (indices.length > 1) throw failure("Stop Artifacty clients with ambiguous --home arguments", "UNMANAGED_WRITER");
+      let processHome = indices.length ? args[indices[0] + 1] : null;
+      if (!processHome) {
+        let environment;
+        try { environment = (await readFile(`${directory}/environ`, "utf8")).split("\0"); }
+        catch { throw failure("Cannot inspect another Artifacty process; stop it before updating", "UNMANAGED_WRITER"); }
+        processHome = environment.find((item) => item.startsWith("ARTIFACTY_HOME="))?.slice(15);
+        const userHome = environment.find((item) => item.startsWith("HOME="))?.slice(5);
+        processHome ||= userHome && path.join(userHome, ".artifacty");
+      }
+      let resolved;
+      try { resolved = processHome && await realpath(path.resolve(cwd, processHome)); } catch { /* Unknown homes fail closed. */ }
+      if (!resolved || resolved === canonicalHome) throw failure(`Stop the unmanaged Artifacty process (pid ${entry}) before updating`, "UNMANAGED_WRITER");
+    }
+  }
+}
+
+async function writableDirectory(directory) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw failure(`Expected a real directory: ${directory}`);
+  await access(directory, constants.W_OK);
+}
+
+async function originalFile(file, managedMark) {
+  const info = await lstat(file).catch((error) => { if (error.code === "ENOENT") return null; throw error; });
+  if (!info) return null;
+  if (!info.isFile() || info.isSymbolicLink()) throw failure(`Refusing to replace an unmanaged file: ${file}`, "UNMANAGED_FILE");
+  const content = await readFile(file, "utf8");
+  if (managedMark && !content.includes(managedMark)) throw failure(`Refusing to replace an unmanaged file: ${file}`, "UNMANAGED_FILE");
+  await access(file, constants.W_OK);
+  return { content, mode: info.mode & 0o777 };
+}
+
+async function replaceFile(file, content, mode = 0o600) {
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { mode, flag: "wx" });
+    await rename(temporary, file);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+function launcher(node, entry) {
+  return `#!/usr/bin/env node\n${LAUNCHER_MARK}\nconst { spawnSync } = require("node:child_process");\nconst result = spawnSync(${JSON.stringify(node)}, [${JSON.stringify(entry)}, ...process.argv.slice(2)], { stdio: "inherit", env: process.env });\nif (result.error) { console.error(result.error.message); process.exitCode = 1; } else { process.exitCode = result.status ?? 1; }\n`;
+}
+
+function validHealthUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" && !url.username && !url.password && !url.search && !url.hash && url.pathname === "/" && Boolean(url.port);
+  } catch { return false; }
+}
+
+async function verifyServiceIdentity(pid, args) {
+  const executable = await realpath(`/proc/${pid}/exe`);
+  const expected = await realpath(args[0]);
+  const command = (await readFile(`/proc/${pid}/cmdline`, "utf8")).split("\0").filter(Boolean);
+  if (executable !== expected || JSON.stringify(command.slice(1)) !== JSON.stringify(args.slice(1))) {
+    throw failure("The service PID does not match its configured Node process", "SERVICE_IDENTITY_MISMATCH");
+  }
+}
+
+async function waitHealthy(run, home, health, sleep, identity, args) {
+  for (let attempt = 0; attempt < 30; attempt++) {
+    let state;
+    try { state = JSON.parse(await readOptional(path.join(home, "server.json")) || "null"); } catch { /* Server state may be mid-write. */ }
+    const result = await run("systemctl", ["--user", "show", UNIT, "--property=MainPID", "--value"]);
+    const pid = Number(result.stdout.trim());
+    if (pid > 0 && state?.pid === pid && validHealthUrl(state.url)) {
+      await identity(pid, args);
+      if (await health(state.url)) return pid;
+    }
+    await sleep(1000);
+  }
+  throw failure("The updated service did not pass its PID and HTTP health checks", "UPDATE_HEALTH_FAILED");
+}
+
+/** Update the managed Linux user service. Dependencies are injectable for offline tests. */
+export async function updateApplication(options = {}, injected = {}) {
+  const env = injected.env || process.env;
+  const platform = injected.platform || process.platform;
+  const userHome = injected.userHome || homedir();
+  const home = path.resolve(options.home || env.ARTIFACTY_HOME || path.join(userHome, ".artifacty"));
+  const run = injected.run || ((command, args) => execute(command, args, { env, timeout: 180000, maxBuffer: 2 * 1024 * 1024 }));
+  const sleep = injected.sleep || pause;
+  const identity = injected.verifyServiceIdentity || verifyServiceIdentity;
+  const writers = injected.assertNoOtherWriters || ((context) => assertNoOtherWriters({ ...context, processRoot: injected.processRoot }));
+  const progress = (message) => { try { options.onProgress?.(message); } catch { /* Reporting cannot interrupt recovery. */ } };
+  const health = injected.health || (async (url) => {
+    try {
+      const response = await fetch(`${url}/health`, { signal: AbortSignal.timeout(2000), redirect: "error" });
+      const body = await response.json();
+      return response.ok && body.ok === true && body.name === "artifacty" && path.resolve(body.store) === home;
+    } catch { return false; }
+  });
+  const backups = injected.backups || { create: createUpgradeBackup, verify: verifyUpgradeBackup, restore: restoreUpgradeBackup };
+  const requested = options.targetVersion || "latest";
+  if (requested !== "latest" && !VERSION.test(requested)) throw failure("--target-version must be latest or an exact version", "INVALID_UPDATE_VERSION");
+  let service;
+  let unsupported;
+  if (platform === "linux") {
+    try { service = await discoverService(run, home); } catch (error) { unsupported = error.message; }
+  } else unsupported = "Automatic updates currently require a Linux systemd user service";
+  const current = service?.version || (await packageAt(options.packageRoot || path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url)))))).version;
+  const targetVersion = JSON.parse((await run("npm", ["view", `artifacty@${requested}`, "version", "--json"])).stdout);
+  if (typeof targetVersion !== "string" || !VERSION.test(targetVersion)) throw failure("npm did not resolve one exact Artifacty version");
+  const summary = { currentVersion: current, targetVersion, supported: Boolean(service), service: service ? UNIT : null };
+  if (options.check) return { ...summary, check: true, updateAvailable: compareVersions(current, targetVersion) < 0, ...(unsupported ? { reason: unsupported } : {}) };
+  if (!service) throw failure(unsupported, "UNSUPPORTED_SERVICE");
+  if ((injected.uid ?? process.geteuid?.()) === 0) throw failure("Run updates as the service user, without sudo", "ROOT_UPDATE_REFUSED");
+  if (/[\r\n$%]/.test(home + userHome)) throw failure("Store and user paths containing $, %, or newlines are unsupported", "UNSUPPORTED_PATH");
+  if (compareVersions(current, targetVersion) > 0) {
+    if (requested !== "latest") throw failure("Automatic package downgrades are not supported", "UPDATE_DOWNGRADE_REFUSED");
+    return { ...summary, updated: false, reason: "already-newer" };
+  }
+  if (current === targetVersion) return { ...summary, updated: false, reason: "already-current" };
+  if (service.active) {
+    await identity(service.pid, service.args);
+    let state;
+    try { state = JSON.parse(await readOptional(path.join(home, "server.json")) || "null"); } catch { /* Fail before stopping an uncheckable service. */ }
+    if (state?.pid !== service.pid || !validHealthUrl(state.url) || !await health(state.url)) {
+      throw failure("The current service cannot pass its HTTP health check. Check its bind address and IP policy before updating.", "UPDATE_PREFLIGHT_HEALTH");
+    }
+  }
+  await writers({ home, allowedPid: service.pid });
+
+  const stateRoot = path.join(userHome, ".local", "share", "artifacty");
+  const releases = path.join(stateRoot, "releases");
+  const bin = path.join(userHome, ".local", "bin");
+  const dropinDirectory = path.join(userHome, ".config", "systemd", "user", `${UNIT}.d`);
+  for (const directory of [stateRoot, releases, bin, dropinDirectory]) await writableDirectory(directory);
+  const dropin = path.join(dropinDirectory, "zz-artifacty-self-update.conf");
+  const destinations = [dropin, path.join(bin, "artifacty"), path.join(bin, "artifacty-mcp")];
+  const originals = await Promise.all(destinations.map((file, index) => originalFile(file, index ? LAUNCHER_MARK : "# artifacty-managed-update")));
+  const lockPath = path.join(stateRoot, "update.lock");
+  let lock;
+  try { lock = await open(lockPath, "wx", 0o600); }
+  catch (error) { if (error.code === "EEXIST") throw failure(`Another update or an interrupted update holds ${lockPath}`, "UPDATE_LOCKED"); throw error; }
+  const stage = path.join(releases, `${targetVersion}-${randomUUID()}`);
+  let snapshot;
+  let stopped = false;
+  let switched = false;
+  let succeeded = false;
+  try {
+    await lock.writeFile(JSON.stringify({ pid: process.pid, targetVersion }));
+    progress(`Staging Artifacty ${targetVersion} before stopping the service.`);
+    await run("npm", ["install", "--prefix", stage, "--ignore-scripts", "--omit=dev", "--no-audit", "--no-fund", "--package-lock=false", "--save-exact", `artifacty@${targetVersion}`]);
+    const stagedRoot = path.join(stage, "node_modules", "artifacty");
+    if ((await packageAt(stagedRoot)).version !== targetVersion) throw failure("Staged package version does not match the resolved version");
+    for (const entry of ["cli.js", "server.js", "mcp-server.js"]) await run(service.args[0], ["--check", path.join(stagedRoot, "src", entry)]);
+    const version = (await run(service.args[0], [path.join(stagedRoot, "src", "cli.js"), "--version"])).stdout.trim();
+    if (version !== targetVersion) throw failure("Staged CLI version check failed");
+    const refreshed = await discoverService(run, home);
+    if (refreshed.text !== service.text || refreshed.pid !== service.pid) throw failure("Service configuration changed while staging; retry the update");
+    await writers({ home, allowedPid: service.pid });
+    progress("Stopping the user service and verifying a recovery snapshot.");
+    stopped = true;
+    await run("systemctl", ["--user", "stop", UNIT]);
+    await writers({ home, allowedPid: 0 });
+    snapshot = await backups.create({ home }, { reason: "manual", targetAppVersion: targetVersion });
+    await backups.verify({ home }, snapshot.id);
+    const args = [service.args[0], path.join(stagedRoot, "src", "server.js"), ...service.args.slice(2)];
+    progress("Switching the user service to the staged release.");
+    switched = true;
+    await replaceFile(dropin, `# artifacty-managed-update\n[Service]\nExecStart=\nExecStart=${args.map(quoteUnit).join(" ")}\n`);
+    await replaceFile(destinations[1], launcher(service.args[0], path.join(stagedRoot, "src", "cli.js")), 0o755);
+    await replaceFile(destinations[2], launcher(service.args[0], path.join(stagedRoot, "src", "mcp-server.js")), 0o755);
+    await run("systemctl", ["--user", "daemon-reload"]);
+    const configured = await discoverService(run, home);
+    if (configured.args[1] !== args[1] || JSON.stringify(configured.args.slice(2)) !== JSON.stringify(args.slice(2))) throw failure("A service override prevented the staged package from becoming active");
+    if (service.active) {
+      await run("systemctl", ["--user", "start", UNIT]);
+      progress("Waiting for service health and process identity.");
+      await waitHealthy(run, home, health, sleep, identity, args);
+    }
+    succeeded = true;
+    let firstExecutable;
+    for (const directory of (env.PATH || "").split(path.delimiter)) {
+      const candidate = path.resolve(directory, "artifacty");
+      try { await access(candidate, constants.X_OK); firstExecutable = await realpath(candidate); break; } catch { /* Try the next PATH entry. */ }
+    }
+    const pathWarning = firstExecutable !== await realpath(destinations[1]) ? `Use ${destinations[1]} until ${bin} precedes other Artifacty installations in PATH.` : undefined;
+    const commandPath = /^[\w/.-]+$/.test(destinations[1]) ? destinations[1] : `'${destinations[1].replaceAll("'", "'\\''")}'`;
+    return { ...summary, updated: true, backupId: snapshot.id, backupPath: snapshot.path, packageRoot: stagedRoot, restarted: service.active, launcher: destinations[1], nextCommand: `${commandPath} update`, ...(pathWarning ? { pathWarning } : {}) };
+  } catch (cause) {
+    progress("Update failed. Restoring the previous service and store where safe.");
+    const recoveryErrors = [];
+    if (switched) {
+      try { await run("systemctl", ["--user", "stop", UNIT]); } catch { recoveryErrors.push("could not stop the updated service"); }
+      if (!recoveryErrors.length) {
+        try {
+          for (let index = 0; index < destinations.length; index++) {
+            const original = originals[index];
+            if (original) await replaceFile(destinations[index], original.content, original.mode);
+            else await rm(destinations[index], { force: true });
+          }
+          await run("systemctl", ["--user", "daemon-reload"]);
+          await writers({ home, allowedPid: 0 });
+          await backups.restore({ home }, snapshot.id, { confirm: "restore-store" });
+        } catch (error) { recoveryErrors.push(`could not restore the previous configuration and store (${/^[A-Z_]+$/.test(error.code || "") ? error.code : "restore failed"})`); }
+      }
+    }
+    if (stopped && service.active && !recoveryErrors.length) {
+      try { await run("systemctl", ["--user", "start", UNIT]); await waitHealthy(run, home, health, sleep, identity, service.args); }
+      catch { recoveryErrors.push("the previous service did not restart cleanly"); }
+    }
+    const error = failure(`Update failed: ${cause.code || "operation failed"}. ${recoveryErrors.length ? `Recovery incomplete: ${recoveryErrors.join("; ")}.` : stopped ? "The previous service configuration was restored." : "The running service was not changed."}${snapshot ? ` Backup: ${snapshot.id}.` : ""}`, recoveryErrors.length ? "UPDATE_RECOVERY_INCOMPLETE" : "SELF_UPDATE_FAILED");
+    error.backupId = snapshot?.id;
+    error.backupPath = snapshot?.path;
+    error.cause = cause;
+    throw error;
+  } finally {
+    await lock.close();
+    await rm(lockPath, { force: true });
+    if (!succeeded && !switched) await rm(stage, { recursive: true, force: true });
+  }
+}