artifacty 0.14.0 → 0.15.0

package/src/lib/sample-content.js

@@ -30,7 +30,7 @@ Open http://127.0.0.1:8787. The server binds to localhost by default. To start a
 5. Inspect the version history.
 6. Compare the versions with a diff.
 7. Add tags.
-8. Use search, filters, or saved views to find the artifact again.
+8. Use search to find the artifact again. Open **Advanced filters** or **Saved views** in the main dashboard when needed. These sections start collapsed; closing them preserves your filters.
 9. Add a comment.
 10. Request a review.
 11. As the owner or administrator, record an approved or changes-requested status.
@@ -42,7 +42,7 @@ Open http://127.0.0.1:8787. The server binds to localhost by default. To start a
 
 ## Choose your access model
 
-Before accounts exist, Artifacty operates as a local single-user store. Once accounts exist, use personal accounts and tokens. Create the initial administrator at **/login**. Administrators manage accounts at **/admin/users**. The Access page links to that page. Administrators manage teams, access mode, and network rules at **/admin/access**. In private mode, use personal authentication for ordinary artifact reads and creation. Server-wide tokens do not authorize those operations. Local CLI operations remain trusted store administration.
+Before accounts exist, Artifacty operates as a local single-user store. Once accounts exist, use personal accounts and tokens. Create the initial administrator at **/login**. In the desktop navigation rail, open **Administration**. On narrower screens, open **Menu** first. Use **Users** (**/admin/users**) for accounts. Use **Access** (**/admin/access**) for teams, access mode, and network rules. Administration also contains Backup, Retention, Webhooks, and Server update. In private mode, use personal authentication for ordinary artifact reads and creation. Server-wide tokens do not authorize those operations. Local CLI operations remain trusted store administration.
 
 A share link is a separate read-only capability with an expiry time. It does not grant account membership. Default expiry is seven days. Owners can share the latest version or pin one version. Share links while the server is in private mode require explicit administrator opt-in. In public mode, an owner can link a private-visibility artifact without that site toggle. When you no longer need a link, revoke it. An owner change invalidates existing links.
 
@@ -70,10 +70,10 @@ If the current store is corrupt, preserve it and copy the selected snapshot to a
 <header><p>ARTIFACTY / REFERENCE</p><h1>From an agent output to a shared record</h1><p>Use this inventory to choose the right publishing, review, access, and maintenance workflow. Use Node.js 22.12.0 or newer. The current store schema is 10. Mermaid 12.1.0 keeps the classic look, dagre layout, and default theme. Use an ES2024-capable browser, such as Safari 17.4 or newer. The optional Babel 8 React renderer requires Node ^22.18.0 or &gt;=24.11.0.</p></header>
 <nav aria-label="Guide sections"><a href="#formats">Formats</a> · <a href="#history">History and discovery</a> · <a href="#collaboration">Collaboration</a> · <a href="#access">Access</a> · <a href="#operations">Operations</a></nav>
 <section id="formats"><h2>Formats and imports</h2><p>The 13 formats are HTML, Markdown, text, JSON, code, SVG, Mermaid, React, SARIF, CSV, image, video, and notebook. Choose an artifact type separately: a document, handoff, code review, test report, dashboard, diagram, component, table, or another supported type.</p><p>Bundles group multiple files under one artifact. Supported binary bundle assets include PDF, DOCX, XLSX, and ZIP. Importers normalize outputs from Claude, Codex, Gemini, GitHub Copilot, Cursor, and generic inputs. Use the browser import screen or <code>artifacty import --agent codex --file handoff.md</code>.</p><p>Artifact content is untrusted. Browser previews use constrained rendering. A public HTML share preview is static. It blocks scripts and external resource loading. Share links show other active formats as source. Do not expect those previews to preserve interactive application behavior.</p></section>
-<section id="history"><h2>Versions, discovery, and retrieval</h2><ul><li>Updates create versions with immutable content files. You can read a historical version and compare versions with a diff. To avoid overwriting a concurrent edit, use an expected-version check.</li><li>Archive and restore artifacts instead of losing their history. Integrity checks verify stored files, hashes, and orphaned files.</li><li>Search by keyword and filter by tags, source agent, artifact type, publisher, dates, review status, relationships, and archive state. Pagination and grouping help you use large lists. To reuse a set of filters, save it as a view.</li><li>When available, SQLite FTS5 accelerates keyword search. Otherwise, search uses metadata. Optional embeddings enable semantic and hybrid search. Without a configured provider, those modes use keyword search. Rebuild search or embedding indexes after configuration changes.</li></ul></section>
+<section id="history"><h2>Versions, discovery, and retrieval</h2><ul><li>Updates create versions with immutable content files. You can read a historical version and compare versions with a diff. To avoid overwriting a concurrent edit, use an expected-version check.</li><li>Archive and restore artifacts instead of losing their history. Integrity checks verify stored files, hashes, and orphaned files.</li><li>Search by keyword and filter by tags, source agent, artifact type, publisher, dates, review status, relationships, and archive state. Pagination and grouping help you use large lists. To reuse a set of filters, save it as a view. Search stays visible in the main dashboard. Open Advanced filters or Saved views when needed. Both sections start collapsed; closing them preserves selected filters.</li><li>When available, SQLite FTS5 accelerates keyword search. Otherwise, search uses metadata. Optional embeddings enable semantic and hybrid search. Without a configured provider, those modes use keyword search. Rebuild search or embedding indexes after configuration changes.</li></ul></section>
 <section id="collaboration"><h2>Relationships, comments, review, and notifications</h2><p>Connect artifacts using derived-from, supersedes, reviews, references, or part-of relations. Comments support threads and anchors. After you address a thread, resolve it. Review status progresses among none, pending, changes-requested, and approved.</p><p>The inbox at <code>/inbox</code> collects relevant shares, comments, review activity, and new versions. Notifications depend on the user and current artifact access. You can mark items read individually or together. A notification does not grant access.</p><p>Audit records support investigation. Event polling and server-sent events expose authorized activity streams. Webhooks deliver configured events to validated destinations. Use event filters, replay cursors, and webhook administration for integrations.</p></section>
-<section id="access"><h2>Accounts, permissions, share links, and network rules</h2><p>Create the initial administrator at <code>/login</code>. Administrators manage accounts at <code>/admin/users</code>. The Access page links to that page. Administrators manage teams, access mode, and network rules at <code>/admin/access</code>. The artifact <strong>Sharing</strong> panel shows effective access and its sources. Direct-user and team grants support read, comment, and edit. Where grants overlap, the strongest permission wins. Ownership and administrator management are separate from grants. Token scopes limit token actions. They do not grant artifact access.</p><p>Private mode requires an active personal account. Server-wide tokens do not authorize ordinary artifact reads or creation in private mode. Administrator APIs have their own authorization rules. Personal tokens remain constrained by both their scopes and the user's artifact permissions. Trusted local CLI operations can administer the local store directly.</p><p>Read-only share links default to seven days and can target the latest version or a pinned version. Share links while the server is in private mode require explicit administrator opt-in. In public mode, owners may link private-visibility artifacts without that site toggle. Links can be revoked, and owner changes invalidate them. A valid capability permits only its read-only shared surface.</p><p>Network allow rules accept IP addresses and CIDRs. First, stage a change. Next, verify access from the intended peer. Then confirm the change within 120 seconds or roll it back. Pending state survives a restart. Before the next access, the server checks for expiry. If the change has expired, the server restores the previous rules. Rules use the socket peer address, not forwarded proxy headers.</p></section>
-<section id="operations"><h2>Interfaces and maintenance</h2><ul><li>The browser supports creation, import, viewing, editing, discovery, review, inbox, and administration.</li><li>The CLI supports serve/start/stop/status, publish/import/update/read/list, history and diff, relations/comments/review, saved views, event watching, account import, backup, retention, indexes, integrity, and diagnostics. Run <code>artifacty help</code> for exact flags.</li><li>The JSON API exposes artifacts and operational endpoints under <code>/api/</code>. MCP exposes agent tools through stdio and optional HTTP transport. Use <code>artifacty install claude --dry-run</code> to inspect integration configuration and <code>artifacty check</code> to verify tool discovery.</li><li>Export and import JSON backups to move a store. Upgrade snapshots separately preserve raw SQLite, referenced versions, and any legacy index. Schema migrations always require a verified snapshot. Set <code>ARTIFACTY_BACKUP_ON_UPDATE=true</code> for application-version snapshots, including an unknown-version baseline. <code>ARTIFACTY_UPGRADE_BACKUP_KEEP</code> defaults to 3 and accepts 1–1000.</li><li>Use <code>artifacty backups list</code>, <code>artifacty backups verify &lt;id&gt;</code>, and <code>artifacty backups restore &lt;id&gt; --confirm restore-store</code>. Stop every server and MCP process first. Restore saves a recovery snapshot and rolls back credentials and security state. Revoked sessions, tokens, or links can become valid again. For a corrupt store, copy the snapshot to a new empty home and restore there. Preserve interrupted <code>.restore-*</code> directories and use their <code>restore.json</code> recoveryBackupId. See <code>docs/upgrade-backups.md</code>.</li><li>Retention supports archive rules, archived-item purge, audit/event history limits, and protected tags. Before an intentional purge, inspect a dry run.</li><li><code>artifacty samples install</code> installs these manuals idempotently. <code>artifacty samples remove</code> archives only managed samples in the current scope. Reinstallation restores existing versions and user edits.</li></ul><p>Keep ARTIFACTY_HOME private. Older builds refuse schema-10 stores. Before changing builds, preserve a backup. Consult repository integration documentation for concrete agent and API examples.</p></section>
+<section id="access"><h2>Accounts, permissions, share links, and network rules</h2><p>Create the initial administrator at <code>/login</code>. In the navigation, administrators open <strong>Administration</strong>. Use Users at <code>/admin/users</code> for accounts. Use Access at <code>/admin/access</code> for teams, access mode, and network rules. Backup, Retention, Webhooks, and Server update are in the same group. The artifact <strong>Sharing</strong> panel shows effective access and its sources. Direct-user and team grants support read, comment, and edit. Where grants overlap, the strongest permission wins. Ownership and administrator management are separate from grants. Token scopes limit token actions. They do not grant artifact access.</p><p>Private mode requires an active personal account. Server-wide tokens do not authorize ordinary artifact reads or creation in private mode. Administrator APIs have their own authorization rules. Personal tokens remain constrained by both their scopes and the user's artifact permissions. Trusted local CLI operations can administer the local store directly.</p><p>Read-only share links default to seven days and can target the latest version or a pinned version. Share links while the server is in private mode require explicit administrator opt-in. In public mode, owners may link private-visibility artifacts without that site toggle. Links can be revoked, and owner changes invalidate them. A valid capability permits only its read-only shared surface.</p><p>Network allow rules accept IP addresses and CIDRs. First, stage a change. Next, verify access from the intended peer. Then confirm the change within 120 seconds or roll it back. Pending state survives a restart. Before the next access, the server checks for expiry. If the change has expired, the server restores the previous rules. Rules use the socket peer address, not forwarded proxy headers.</p></section>
+<section id="operations"><h2>Interfaces and maintenance</h2><ul><li>The browser supports creation, import, viewing, editing, discovery, review, inbox, and administration. On desktop, use the navigation rail. On narrower screens, open Menu. Artifacts and Inbox lead to your work; New and Import add content. Account contains Account &amp; API tokens, password changes, and sign-out. API docs and language selection are also in the navigation. Administrators can open Server update at /admin/update. Checking the latest release does not install it. For a supported non-root Linux systemd user service, confirm the displayed version and backup/restart before starting. Keep the page open to reconnect and read the result.</li><li>The CLI supports serve/start/stop/status, publish/import/update/read/list, history and diff, relations/comments/review, saved views, event watching, account import, backup, retention, indexes, integrity, and diagnostics. Run <code>artifacty help</code> for exact flags.</li><li>The JSON API exposes artifacts and operational endpoints under <code>/api/</code>. MCP exposes agent tools through stdio and optional HTTP transport. Use <code>artifacty install claude --dry-run</code> to inspect integration configuration and <code>artifacty check</code> to verify tool discovery.</li><li>Export and import JSON backups to move a store. Upgrade snapshots separately preserve raw SQLite, referenced versions, and any legacy index. Schema migrations always require a verified snapshot. Set <code>ARTIFACTY_BACKUP_ON_UPDATE=true</code> for application-version snapshots, including an unknown-version baseline. <code>ARTIFACTY_UPGRADE_BACKUP_KEEP</code> defaults to 3 and accepts 1–1000.</li><li>Use <code>artifacty backups list</code>, <code>artifacty backups verify &lt;id&gt;</code>, and <code>artifacty backups restore &lt;id&gt; --confirm restore-store</code>. Stop every server and MCP process first. Restore saves a recovery snapshot and rolls back credentials and security state. Revoked sessions, tokens, or links can become valid again. For a corrupt store, copy the snapshot to a new empty home and restore there. Preserve interrupted <code>.restore-*</code> directories and use their <code>restore.json</code> recoveryBackupId. See <code>docs/upgrade-backups.md</code>.</li><li>Retention supports archive rules, archived-item purge, audit/event history limits, and protected tags. Before an intentional purge, inspect a dry run.</li><li><code>artifacty samples install</code> installs these manuals idempotently. <code>artifacty samples remove</code> archives only managed samples in the current scope. Reinstallation restores existing versions and user edits.</li></ul><p>Keep ARTIFACTY_HOME private. Older builds refuse schema-10 stores. Before changing builds, preserve a backup. Consult repository integration documentation for concrete agent and API examples.</p></section>
 <footer><p>This guide is a managed sample artifact. Editing it creates your own version. Reinstalling samples preserves that work.</p></footer>
 </main></body></html>`
   },
@@ -171,7 +171,7 @@ The four sample manuals are installed. You can open the browser dashboard. To pr
 
 ## Administration practice
 
-As an administrator, open **/admin/access** to inspect access mode and network rules. You can switch access mode or stage a network change.
+As an administrator, open **Administration → Access** (**/admin/access**) to inspect access mode and network rules. On narrower screens, open **Menu** first. You can switch access mode or stage a network change.
 
 1. Before you stage a network change, keep your actual socket peer address in the allowed rules.
 2. Stage the change.

package/src/lib/self-update.js

@@ -197,6 +197,18 @@ async function waitHealthy(run, home, health, sleep, identity, args) {
   throw failure("The updated service did not pass its PID and HTTP health checks", "UPDATE_HEALTH_FAILED");
 }
 
+/** Verify that a web administrator is operating the managed service itself. */
+export async function inspectWebUpdateService({ home, pid = process.pid }, injected = {}) {
+  if ((injected.platform || process.platform) !== "linux" || (injected.uid ?? process.geteuid?.()) === 0) {
+    throw failure("Web updates require a non-root Linux systemd user service", "UNSUPPORTED_SERVICE");
+  }
+  const run = injected.run || ((command, args) => execute(command, args, { timeout: 10000, maxBuffer: 1024 * 1024 }));
+  const service = await discoverService(run, path.resolve(home));
+  if (!service.active || service.pid !== pid) throw failure("This server is not the managed Artifacty service", "SERVICE_IDENTITY_MISMATCH");
+  await (injected.verifyServiceIdentity || verifyServiceIdentity)(pid, service.args);
+  return { currentVersion: service.version };
+}
+
 /** Update the managed Linux user service. Dependencies are injectable for offline tests. */
 export async function updateApplication(options = {}, injected = {}) {
   const env = injected.env || process.env;

package/src/lib/web-update.js

@@ -0,0 +1,177 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile, rename, open, rm, lstat, realpath } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import path from "node:path";
+import { updateApplication, inspectWebUpdateService } from "./self-update.js";
+
+const execute = promisify(execFile);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const ACTIVE = new Set(["queued", "running"]);
+const needsRecovery = (run) => run?.state === "interrupted" || run?.errorCode === "UPDATE_RECOVERY_INCOMPLETE";
+const fail = (message, code, statusCode = 409) => Object.assign(new Error(message), { code, statusCode });
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const unitName = (id) => `artifacty-update-${id}.service`;
+const runnerStateRoot = (userHome) => path.join(userHome, ".local", "share", "artifacty", "update-jobs");
+
+async function readJson(file) {
+  try { return JSON.parse(await readFile(file, "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+async function writeJson(file, value) {
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(value), { flag: "wx", mode: 0o600 });
+    await rename(temporary, file);
+  } finally { await rm(temporary, { force: true }); }
+}
+async function privateDirectory(directory) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink() || (process.getuid && info.uid !== process.getuid()) || (process.platform !== "win32" && (info.mode & 0o077))) {
+    throw fail("Update state directory must be private and owned by the service user", "UNSAFE_UPDATE_STATE");
+  }
+}
+
+/** The controller does no work on construction. Read-only pages never contact npm. */
+export function createWebUpdater({ home, packageRoot }, injected = {}) {
+  home = path.resolve(home);
+  const root = runnerStateRoot(injected.userHome || homedir());
+  const stateInsideStore = root === home || root.startsWith(`${home}${path.sep}`);
+  const directory = path.join(root, hash(home));
+  const file = path.join(directory, "status.json");
+  const now = injected.now || Date.now;
+  const run = injected.run || ((command, args) => execute(command, args, { timeout: 15000, maxBuffer: 1024 * 1024 }));
+  const inspect = injected.inspect || ((options) => inspectWebUpdateService(options));
+  const update = injected.update || updateApplication;
+  const read = async () => await readJson(file) || {};
+  const currentVersion = async () => JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8")).version;
+  const publicState = async (state, session) => ({
+    currentVersion: await currentVersion(),
+    check: state.check ? { ...state.check, confirmationId: state.sessionHash === hash(session || "") ? state.check.confirmationId : null } : null,
+    run: state.run || null
+  });
+  async function locked(action) {
+    if (stateInsideStore) throw fail("Update status must be outside the artifact store", "UNSAFE_UPDATE_STATE");
+    await privateDirectory(root);
+    const [resolvedRoot, resolvedHome] = await Promise.all([realpath(root), realpath(home)]);
+    if (resolvedRoot === resolvedHome || resolvedRoot.startsWith(`${resolvedHome}${path.sep}`)) throw fail("Update status must be outside the artifact store", "UNSAFE_UPDATE_STATE");
+    await privateDirectory(directory);
+    const lockPath = path.join(directory, "dispatch.lock");
+    let lock;
+    try { lock = await open(lockPath, "wx", 0o600); }
+    catch (error) { if (error.code === "EEXIST") throw fail("Another update request is in progress", "UPDATE_BUSY"); throw error; }
+    try { await lock.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date(now()).toISOString() })); return await action(); }
+    finally { await lock.close(); await rm(lockPath, { force: true }); }
+  }
+  async function status(session) {
+    if (stateInsideStore) return { currentVersion: await currentVersion(), supported: false, reason: "Update state must be outside the artifact store.", check: null, run: null };
+    const state = await read();
+    // An unfinished job is never inferred successful. Keep uncertain jobs locked.
+    if (ACTIVE.has(state.run?.state) && now() - Date.parse(state.run.startedAt) > 30000) {
+      try {
+        const result = await run("systemctl", ["--user", "show", unitName(state.run.id), "--property=ActiveState", "--value"]).catch((error) => {
+          // systemctl may exit nonzero for a collected unit while still
+          // returning its authoritative inactive state. Bus failures do not.
+          if (["inactive", "failed"].includes(error.stdout?.trim())) return { stdout: error.stdout };
+          throw error;
+        });
+        if (["inactive", "failed"].includes(result.stdout.trim())) {
+          return await locked(async () => {
+            const latest = await read();
+            if (latest.run?.id === state.run.id && ACTIVE.has(latest.run.state)) {
+              latest.run = { ...latest.run, state: "interrupted", finishedAt: new Date(now()).toISOString(), errorCode: "UPDATE_INTERRUPTED", error: "The update worker stopped without a final result. Inspect the retained update backup and service before retrying." };
+              await writeJson(file, latest);
+            }
+            return publicState(latest, session);
+          });
+        }
+      } catch { /* Unavailable user manager is not evidence that a job has stopped. */ }
+    }
+    return publicState(state, session);
+  }
+  async function check(session) {
+    return locked(async () => {
+      const state = await read();
+      if (ACTIVE.has(state.run?.state) || needsRecovery(state.run)) throw fail("Resolve the existing update before checking again", "UPDATE_BUSY");
+      let eligible = false;
+      try { await inspect({ home, pid: process.pid }); eligible = true; } catch { /* Read-only version checks also support unmanaged installations. */ }
+      let result;
+      try {
+        const checked = await update({ home, packageRoot, check: true });
+        result = { currentVersion: await currentVersion(), targetVersion: checked.targetVersion, supported: eligible && checked.supported, updateAvailable: checked.updateAvailable };
+        if (!result.supported) result.reason = "Web updates require this server to be the non-root Linux systemd user service.";
+      } catch (error) {
+        result = { currentVersion: await currentVersion(), supported: eligible, updateAvailable: false, reason: "The latest release could not be checked. Try again later.", errorCode: "UPDATE_CHECK_FAILED" };
+      }
+      state.check = { ...result, check: undefined, confirmationId: randomUUID(), checkedAt: new Date(now()).toISOString(), expiresAt: new Date(now() + 10 * 60 * 1000).toISOString() };
+      state.sessionHash = hash(session);
+      await writeJson(file, state);
+      return publicState(state, session);
+    });
+  }
+  async function start({ session, confirmationId, targetVersion, confirmUpdate }) {
+    return locked(async () => {
+      const state = await read();
+      if (ACTIVE.has(state.run?.state) || needsRecovery(state.run)) throw fail("An update is already running or needs recovery", "UPDATE_BUSY");
+      const checked = state.check;
+      if (confirmUpdate !== "true" || !checked?.supported || !checked.updateAvailable || checked.confirmationId !== confirmationId || state.sessionHash !== hash(session) || checked.targetVersion !== targetVersion || Date.parse(checked.expiresAt) <= now()) {
+        throw fail("Check for updates again and confirm the displayed version", "UPDATE_CONFIRMATION_REQUIRED", 400);
+      }
+      await inspect({ home, pid: process.pid });
+      if (checked.currentVersion !== await currentVersion()) throw fail("The installed version changed; check again", "UPDATE_CONFIRMATION_REQUIRED", 400);
+      const id = randomUUID();
+      const requestFile = path.join(root, `${id}.json`);
+      await writeJson(requestFile, { id, home, packageRoot, targetVersion, statusFile: file });
+      state.check.confirmationId = null;
+      state.run = { id, state: "queued", targetVersion, startedAt: new Date(now()).toISOString(), phase: "Starting an independent update worker." };
+      await writeJson(file, state);
+      try {
+        await run("systemd-run", ["--user", `--unit=${unitName(id)}`, "--collect", "--property=Type=exec", "--", process.execPath, path.join(packageRoot, "src", "update-runner.js"), id]);
+      } catch {
+        // A timeout can occur after systemd accepted the unit. Preserve the job
+        // and its request; polling will resolve a stopped worker as interrupted.
+        // Never overwrite progress or completion written by that worker.
+        return publicState(await read(), session);
+      }
+      return publicState(state, session);
+    });
+  }
+  return { status, check, start };
+}
+
+/** Invoked only by the fixed systemd transient service, never the web server. */
+export async function runWebUpdate(id, injected = {}) {
+  if (!UUID.test(id || "")) throw fail("Invalid update job", "INVALID_UPDATE_JOB", 400);
+  const root = runnerStateRoot(injected.userHome || homedir());
+  await privateDirectory(root);
+  const requestFile = path.join(root, `${id}.json`);
+  const info = await lstat(requestFile);
+  if (!info.isFile() || info.isSymbolicLink() || (process.platform !== "win32" && (info.mode & 0o077)) || (process.getuid && info.uid !== process.getuid())) throw fail("Unsafe update request", "UNSAFE_UPDATE_STATE");
+  const request = await readJson(requestFile);
+  const expectedFile = path.join(root, hash(path.resolve(request.home)), "status.json");
+  if (request.id !== id || request.statusFile !== expectedFile || !path.isAbsolute(request.packageRoot)) throw fail("Invalid update request", "INVALID_UPDATE_JOB");
+  const sourceRoot = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
+  if (await realpath(request.packageRoot) !== await realpath(injected.packageRoot || sourceRoot) || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(request.targetVersion)) throw fail("Update package identity does not match the worker", "INVALID_UPDATE_JOB");
+  await privateDirectory(path.dirname(expectedFile));
+  // A durable claim makes replays fail closed, including after a worker crash.
+  const claim = await open(path.join(root, `${id}.claimed`), "wx", 0o600);
+  await claim.close();
+  const state = await readJson(expectedFile);
+  if (state?.run?.id !== id || state.run.state !== "queued") throw fail("Update job was already consumed", "INVALID_UPDATE_JOB");
+  const save = async (changes) => { state.run = { ...state.run, ...changes }; await writeJson(expectedFile, state); };
+  await save({ state: "running", phase: "Preparing update." });
+  let progressQueue = Promise.resolve();
+  try {
+    const result = await (injected.update || updateApplication)({ home: request.home, packageRoot: request.packageRoot, targetVersion: request.targetVersion,
+      onProgress: (phase) => { progressQueue = progressQueue.then(() => save({ phase })); }
+    });
+    await progressQueue;
+    await save({ state: "succeeded", phase: "Update completed.", finishedAt: new Date().toISOString(), result });
+  } catch (error) {
+    await progressQueue.catch(() => {});
+    await save({ state: "failed", finishedAt: new Date().toISOString(), errorCode: /^[A-Z_]+$/.test(error.code || "") ? error.code : "SELF_UPDATE_FAILED", error: "Update failed. Inspect the service and retained recovery backup before retrying.", result: { backupId: error.backupId, backupPath: error.backupPath } });
+  } finally { await rm(requestFile, { force: true }); }
+}

package/src/server.js

@@ -77,6 +77,7 @@ import {
 import { assertNetworkAccess, getNetworkPolicy, stageNetworkPolicy, getPendingNetworkPolicy, confirmNetworkPolicy, rollbackNetworkPolicy } from "./lib/network-policy.js";
 import { getShareLinkPolicy, setShareLinkPolicy, createShareLink, listShareLinks, revokeShareLink, resolveShareLink } from "./lib/share-links.js";
 import { installSamples, removeSamples } from "./lib/samples.js";
+import { createWebUpdater } from "./lib/web-update.js";
 import { MAX_BACKUP_BYTES, buildStoreBackup, exportStoreToString, importStoreBundle, importStoreFromString } from "./lib/backup.js";
 import { convertAgentArtifact, decodeMediaContent, mediaContentType } from "./lib/converters.js";
 import { createLineDiff, createStructuredDiff, diffFormatFor, resolveDiffView } from "./lib/diff.js";
@@ -111,6 +112,7 @@ import {
   renderAccountPage,
   renderAdminBackupPage,
   renderAdminAccessPage,
+  renderAdminUpdatePage,
   renderArtifactSharingPage,
   renderSharedArtifactPage,
   renderInboxPage,
@@ -189,6 +191,7 @@ export async function startServer(options = {}) {
     options.portFallback === true ||
     (!explicitPort && options.portFallback !== false);
   const store = createStore({ home: options.home });
+  const webUpdater = options.webUpdater || createWebUpdater({ home: store.home, packageRoot: PACKAGE_ROOT });
   const security = securityConfig(options);
   const mcpHttp = Boolean(options.mcpHttp || process.env.ARTIFACTY_MCP_HTTP === "true");
   validateServerExposure({ host, config: security });
@@ -202,7 +205,7 @@ export async function startServer(options = {}) {
     allowPortFallback,
     createServer(port) {
       const candidateServer = http.createServer((request, response) => {
-        handleRequest({ request, response, store, host, port: candidateServer.address()?.port || port, security, mcpHttp }).catch((error) => {
+        handleRequest({ request, response, store, host, port: candidateServer.address()?.port || port, security, mcpHttp, webUpdater }).catch((error) => {
           sendError(response, error);
         });
       });
@@ -307,7 +310,7 @@ function closeServer(server) {
   });
 }
 
-export async function handleRequest({ request, response, store, host, port, security = securityConfig(), mcpHttp = false }) {
+export async function handleRequest({ request, response, store, host, port, security = securityConfig(), mcpHttp = false, webUpdater }) {
   await assertNetworkAccess(store, request.socket.remoteAddress);
   const url = new URL(request.url, `http://${request.headers.host || `${host}:${port}`}`);
   const pathname = decodeURIComponent(url.pathname);
@@ -318,6 +321,10 @@ export async function handleRequest({ request, response, store, host, port, secu
   const headOnly = request.method === "HEAD";
   const method = headOnly ? "GET" : request.method;
 
+  if (method === "GET" && pathname === "/assets/update.js") {
+    return sendJavaScriptFile(response, path.join(PACKAGE_ROOT, "src", "client", "update.js"), headOnly, request);
+  }
+
   const publicShareMatch = /^\/s\/([^/]+)(\/raw)?$/.exec(pathname);
   if (publicShareMatch && method === "GET") {
     const shared = await resolveShareLink(store, publicShareMatch[1]);
@@ -546,6 +553,31 @@ export async function handleRequest({ request, response, store, host, port, secu
   }
 
   const browserAccess = accessContext(request, currentUser);
+  if (["/admin/update", "/admin/update/status", "/admin/update/check", "/admin/update/start"].includes(pathname)) {
+    if (!currentUser) throw Object.assign(new Error("An administrator browser session is required"), { statusCode: 401 });
+    requireAdmin(currentUser);
+    response.setHeader("cache-control", "no-store");
+    const updater = webUpdater || createWebUpdater({ home: store.home, packageRoot: PACKAGE_ROOT });
+    const session = sessionTokenFromRequest(request);
+    if (method === "GET" && pathname === "/admin/update/status") return sendJson(response, await updater.status(session), 200, headOnly);
+    if (method === "GET" && pathname === "/admin/update") {
+      return sendHtml(response, renderAdminUpdatePage({ baseUrl, user: currentUser, locale, currentPath, status: await updater.status(session) }), 200, headOnly);
+    }
+    if (method === "POST" && ["/admin/update/check", "/admin/update/start"].includes(pathname)) {
+      assertLocalOrigin(request);
+      const expectedOrigin = `${request.socket.encrypted ? "https" : "http"}://${request.headers.host}`;
+      if (request.headers.origin !== expectedOrigin) throw Object.assign(new Error("An exact same-origin request is required"), { statusCode: 403, code: "UPDATE_ORIGIN_REQUIRED" });
+      await enforceRateLimit({ store, host, request, bucket: "write" });
+      const body = await readFormBody(request);
+      if (pathname.endsWith("/check")) {
+        const status = await updater.check(session);
+        return sendHtml(response, renderAdminUpdatePage({ baseUrl, user: currentUser, locale: localeFromBodyOrUrl(body, url), currentPath: "/admin/update", status }));
+      }
+      await updater.start({ session, confirmationId: body.confirmationId, targetVersion: body.targetVersion, confirmUpdate: body.confirmUpdate });
+      return sendRedirect(response, localizedHref("/admin/update", localeFromBodyOrUrl(body, url)));
+    }
+    return sendJson(response, { error: "Method not allowed" }, 405, headOnly);
+  }
   const browserAudit = { surface: "web", actor: currentUser?.email, userId: currentUser?.id };
   const adminAccessPage = async (extra = {}) => renderAdminAccessPage({
     baseUrl, user: currentUser, mode: await getAccessMode(store),
@@ -1048,7 +1080,7 @@ export async function handleRequest({ request, response, store, host, port, secu
   }
 
   if (method === "GET" && pathname === "/new") {
-    return sendHtml(response, renderNewArtifactPage({ baseUrl, authToken, locale, currentPath }), 200, headOnly);
+    return sendHtml(response, renderNewArtifactPage({ baseUrl, authToken, user: currentUser, locale, currentPath }), 200, headOnly);
   }
 
   if (method === "POST" && pathname === "/new") {
@@ -1075,7 +1107,7 @@ export async function handleRequest({ request, response, store, host, port, secu
   }
 
   if (method === "GET" && pathname === "/import") {
-    return sendHtml(response, renderImportArtifactPage({ baseUrl, authToken, locale, currentPath }), 200, headOnly);
+    return sendHtml(response, renderImportArtifactPage({ baseUrl, authToken, user: currentUser, locale, currentPath }), 200, headOnly);
   }
 
   if (method === "POST" && pathname === "/import") {
@@ -1342,6 +1374,7 @@ export async function handleRequest({ request, response, store, host, port, secu
       access: accessContext(request, currentUser)
     });
     return sendHtml(response, renderArtifactFormPage({
+      user: currentUser,
       mode: "edit",
       baseUrl,
       artifact,
@@ -1388,6 +1421,7 @@ export async function handleRequest({ request, response, store, host, port, secu
           tags: splitTags(body.tags)
         };
         return sendHtml(response, renderArtifactFormPage({
+          user: currentUser,
           mode: "edit",
           baseUrl,
           artifact: unsavedArtifact,
@@ -1419,6 +1453,7 @@ export async function handleRequest({ request, response, store, host, port, secu
       ? createStructuredDiff(from.content, to.content, { format: diffFormat })
       : null;
     return sendHtml(response, renderDiffPage({
+      user: currentUser,
       artifact: latest,
       fromVersion: from.version,
       toVersion: to.version,

package/src/update-runner.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runWebUpdate } from "./lib/web-update.js";
+
+runWebUpdate(process.argv[2]).catch(() => {
+  console.error("Artifacty update worker could not finish. Inspect its persisted status and user service.");
+  process.exitCode = 1;
+});