patchwarden 1.5.0 → 1.6.1

package/src/utils/lockedJsonFile.ts

@@ -0,0 +1,251 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteJsonFileSync } from "./atomicFile.js";
+
+export interface LockedJsonMutation<T extends object, R> {
+  next?: T;
+  result: R;
+}
+
+export interface LockedJsonOptions {
+  waitMs?: number;
+  corruptLockStaleMs?: number;
+  busyError?: () => Error;
+}
+
+const waitArray = new Int32Array(new SharedArrayBuffer(4));
+const lockReleaseRetryCodes = new Set(["EACCES", "EBUSY", "ENOTEMPTY", "EPERM"]);
+const lockReleaseRetryMs = 5_000;
+const lockReleaseRetryDelayMs = 10;
+const deadOwnerGraceMs = 250;
+const lockOwnerFile = "owner.json";
+
+interface AcquiredLock {
+  path: string;
+  owner: string;
+}
+
+interface LockRecord {
+  owner?: string;
+  pid?: number;
+}
+
+export function readJsonObjectFileSync<T extends object>(path: string): T {
+  const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Expected a JSON object in ${path}`);
+  }
+  return parsed as T;
+}
+
+export function mutateLockedJsonFileSync<T extends object, R>(
+  path: string,
+  mutation: (current: T) => LockedJsonMutation<T, R>,
+  options: LockedJsonOptions = {},
+): R {
+  return withFileLockSync(path, () => {
+    const current = readJsonObjectFileSync<T>(path);
+    const outcome = mutation(current);
+    if (outcome.next) atomicWriteJsonFileSync(path, outcome.next);
+    return outcome.result;
+  }, options);
+}
+
+/** Serialize an arbitrary same-file read/modify/write sequence across processes. */
+export function withFileLockSync<R>(
+  path: string,
+  action: () => R,
+  options: LockedJsonOptions = {},
+): R {
+  const lock = acquireLock(path, options);
+  try {
+    return action();
+  } finally {
+    releaseLock(lock.path, lock.owner);
+  }
+}
+
+/** Hold the same cross-process lock for the lifetime of an async operation. */
+export async function withFileLock<R>(
+  path: string,
+  action: () => Promise<R>,
+  options: LockedJsonOptions = {},
+): Promise<R> {
+  // Async callers must not use the synchronous Atomics.wait loop: a second
+  // request in the same Node event loop would otherwise block the first
+  // request from finishing its awaited mutation and releasing the lock.
+  const lock = await acquireLockAsync(path, options);
+  try {
+    return await action();
+  } finally {
+    releaseLock(lock.path, lock.owner);
+  }
+}
+
+async function acquireLockAsync(path: string, options: LockedJsonOptions): Promise<AcquiredLock> {
+  const lockPath = `${path}.lock`;
+  const owner = `${process.pid}-${randomBytes(8).toString("hex")}`;
+
+  const deadline = Date.now() + (options.waitMs ?? 2000);
+  while (true) {
+    if (tryCreateLock(lockPath, owner)) return { path: lockPath, owner };
+    if (
+      removeStaleLock(lockPath, options.corruptLockStaleMs ?? 30_000) &&
+      tryCreateLock(lockPath, owner)
+    ) {
+      return { path: lockPath, owner };
+    }
+    if (Date.now() >= deadline) {
+      throw options.busyError?.() ?? new Error(`JSON file is busy: ${path}`);
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, lockReleaseRetryDelayMs));
+  }
+}
+
+function acquireLock(path: string, options: LockedJsonOptions): AcquiredLock {
+  const lockPath = `${path}.lock`;
+  const owner = `${process.pid}-${randomBytes(8).toString("hex")}`;
+
+  const deadline = Date.now() + (options.waitMs ?? 2000);
+  while (true) {
+    if (tryCreateLock(lockPath, owner)) return { path: lockPath, owner };
+    if (
+      removeStaleLock(lockPath, options.corruptLockStaleMs ?? 30_000) &&
+      tryCreateLock(lockPath, owner)
+    ) {
+      return { path: lockPath, owner };
+    }
+    if (Date.now() >= deadline) {
+      throw options.busyError?.() ?? new Error(`JSON file is busy: ${path}`);
+    }
+    Atomics.wait(waitArray, 0, 0, lockReleaseRetryDelayMs);
+  }
+}
+
+function tryCreateLock(lockPath: string, owner: string): boolean {
+  try {
+    mkdirSync(lockPath, { mode: 0o700 });
+  } catch (error) {
+    const code = errorCode(error);
+    if (code === "EEXIST" || lockReleaseRetryCodes.has(code || "")) return false;
+    throw error;
+  }
+
+  try {
+    writeFileSync(join(lockPath, lockOwnerFile), JSON.stringify({
+      owner,
+      pid: process.pid,
+      created_at: new Date().toISOString(),
+    }), { encoding: "utf-8", flag: "wx", mode: 0o600 });
+    return true;
+  } catch (error) {
+    try { rmSync(lockPath, { recursive: true, force: true }); } catch { /* leave fail-closed */ }
+    throw error;
+  }
+}
+
+function releaseLock(lockPath: string, owner: string): void {
+  const detachDeadline = Date.now() + lockReleaseRetryMs;
+  const releasePath = `${lockPath}.release-${owner}`;
+
+  // Rename the owned lock directory out of the active lock path before
+  // recursive cleanup. A new contender can then create lockPath immediately,
+  // while Windows rimraf retries cannot delete that replacement lock.
+  while (true) {
+    const currentOwner = readLock(lockPath)?.owner;
+    if (currentOwner !== owner) {
+      if (!existsSync(lockPath)) return;
+      if (currentOwner !== undefined) return;
+      if (Date.now() >= detachDeadline) {
+        throw new Error(`Unable to verify lock ownership before release: ${lockPath}`);
+      }
+      Atomics.wait(waitArray, 0, 0, lockReleaseRetryDelayMs);
+      continue;
+    }
+    try {
+      renameSync(lockPath, releasePath);
+      break;
+    } catch (error) {
+      const code = errorCode(error);
+      if (code === "ENOENT") return;
+      if (!code || !lockReleaseRetryCodes.has(code) || Date.now() >= detachDeadline) throw error;
+      Atomics.wait(waitArray, 0, 0, lockReleaseRetryDelayMs);
+    }
+  }
+
+  // Cleanup is no longer ownership-sensitive after the atomic detach, so give
+  // it an independent retry budget instead of consuming whatever remained
+  // from a slow antivirus-delayed rename.
+  const cleanupDeadline = Date.now() + lockReleaseRetryMs;
+  while (true) {
+    try {
+      rmSync(releasePath, { recursive: true, force: false });
+      return;
+    } catch (error) {
+      const code = errorCode(error);
+      if (code === "ENOENT") return;
+      if (!code || !lockReleaseRetryCodes.has(code) || Date.now() >= cleanupDeadline) throw error;
+      Atomics.wait(waitArray, 0, 0, lockReleaseRetryDelayMs);
+    }
+  }
+}
+
+function removeStaleLock(lockPath: string, corruptLockStaleMs: number): boolean {
+  const lock = readLock(lockPath);
+  let ageMs: number;
+  try {
+    ageMs = Date.now() - statSync(lockPath).mtimeMs;
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return true;
+    throw error;
+  }
+  const stale = typeof lock?.pid === "number"
+    ? !processIsAlive(lock.pid) && ageMs >= deadOwnerGraceMs
+    : ageMs >= corruptLockStaleMs;
+  if (!stale) return false;
+
+  // Re-read immediately before removal so one stale-lock contender cannot
+  // delete a replacement acquired after its first observation.
+  const latest = readLock(lockPath);
+  if (lock?.owner) {
+    if (latest?.owner !== lock.owner || latest.pid !== lock.pid) return false;
+  } else if (latest) {
+    return false;
+  }
+  try {
+    rmSync(lockPath, { recursive: true, force: false });
+    return true;
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return true;
+    if (lockReleaseRetryCodes.has(errorCode(error) || "")) return false;
+    throw error;
+  }
+}
+
+function readLock(path: string): LockRecord | null {
+  try {
+    const metadata = statSync(path);
+    const recordPath = metadata.isDirectory() ? join(path, lockOwnerFile) : path;
+    return readJsonObjectFileSync<LockRecord>(recordPath);
+  } catch {
+    return null;
+  }
+}
+
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // Only ESRCH proves the process does not exist. Access-denied and unknown
+    // platform errors must keep the lock fail-closed.
+    return errorCode(error) !== "ESRCH";
+  }
+}
+
+function errorCode(error: unknown): string | null {
+  return error && typeof error === "object" && "code" in error
+    ? String((error as NodeJS.ErrnoException).code || "")
+    : null;
+}

package/src/utils/platform.ts

@@ -0,0 +1,31 @@
+/**
+ * Cross-platform abstractions for PatchWarden.
+ *
+ * Centralizes platform detection, path separators, the platform-specific null
+ * device, and a path-containment helper that works correctly on Windows where
+ * forward and backward slashes may be mixed. Use these helpers instead of
+ * hard-coded Unix assumptions so the runtime guard and change capture behave
+ * consistently across Windows and Unix hosts.
+ */
+import { sep, relative, isAbsolute } from "node:path";
+
+export const isWindows: boolean = process.platform === "win32";
+
+export const pathSep: string = sep;
+
+export const nullDevice: string = isWindows ? "NUL" : "/dev/null";
+
+export function isSamePath(left: string, right: string): boolean {
+  return relative(left, right) === "";
+}
+
+/**
+ * Returns true when `child` is located inside `parent` (or equals it is NOT
+ * treated as a child here — callers that need equality should check it
+ * separately). Uses `path.relative` so mixed Windows separators are normalized
+ * before comparison, unlike `String.prototype.startsWith`.
+ */
+export function isPathChildOf(child: string, parent: string): boolean {
+  const rel = relative(parent, child);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}

package/src/utils/stableJson.ts

@@ -0,0 +1,12 @@
+/** Canonical JSON with object keys sorted recursively. */
+export function stableJsonStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJsonStringify).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right));
+    return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableJsonStringify(entry)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}

package/src/version.ts

@@ -1,2 +1,3 @@
-export const PATCHWARDEN_VERSION = "1.5.0";
-export const TOOL_SCHEMA_EPOCH = "2026-07-05-v13";
+export const PATCHWARDEN_VERSION = "1.6.1";
+export const TOOL_SCHEMA_EPOCH = "2026-07-19-v15";
+export const ARTIFACT_SCHEMA_VERSION = TOOL_SCHEMA_EPOCH;

package/src/watcherStatus.ts

@@ -2,10 +2,11 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getConfig, getTasksDir, type PatchWardenConfig } from "./config.js";
 
-export type WatcherState = "healthy" | "stale" | "missing" | "unreadable";
+export type WatcherState = "healthy" | "degraded" | "stale" | "missing" | "unreadable";
 export type PendingReason =
   | "queued_waiting_for_watcher"
   | "queued_but_watcher_stale"
+  | "queued_but_watcher_degraded"
   | "queued_but_watcher_missing"
   | "queued_but_watcher_unreadable"
   | "agent_running"
@@ -75,6 +76,22 @@ export function readWatcherStatus(
     if (!Number.isFinite(heartbeatMs)) throw new Error("invalid heartbeat timestamp");
     const ageMs = Math.max(0, nowMs - heartbeatMs);
     const ageSeconds = Math.round(ageMs / 1000);
+    if (data.status === "degraded") {
+      return {
+        status: "degraded",
+        available: false,
+        stale_after_seconds: staleAfterSeconds,
+        last_heartbeat_at: String(data.last_heartbeat_at),
+        heartbeat_age_seconds: ageSeconds,
+        heartbeat_pid: Number.isInteger(Number(data.pid)) ? Number(data.pid) : null,
+        instance_id: typeof data.instance_id === "string" ? data.instance_id : null,
+        launcher_pid: Number.isInteger(Number(data.launcher_pid)) ? Number(data.launcher_pid) : null,
+        reason: typeof data.last_error === "string" && data.last_error
+          ? `Watcher is degraded after repeated tick failures: ${data.last_error}`
+          : "Watcher is degraded after repeated tick failures. Restart the PatchWarden watcher.",
+        activity: null,
+      };
+    }
     const healthy = ageMs < staleAfterSeconds * 1000;
     if (healthy) {
       return {
@@ -186,6 +203,7 @@ export function derivePendingReason(
   watcher: WatcherStatusSnapshot
 ): PendingReason {
   if (task.status === "pending") {
+    if (watcher.status === "degraded") return "queued_but_watcher_degraded";
     if (watcher.status === "stale") return "queued_but_watcher_stale";
     if (watcher.status === "missing") return "queued_but_watcher_missing";
     if (watcher.status === "unreadable") return "queued_but_watcher_unreadable";

package/ui/desktop-bootstrap.js

@@ -0,0 +1,11 @@
+(function () {
+  if (!window.patchwardenDesktop) return;
+  var html = document.documentElement;
+  var theme = localStorage.getItem("patchwarden.desktop.theme") || "system";
+  var dark = theme === "dark" || (theme === "system" && window.matchMedia("(prefers-color-scheme: dark)").matches);
+  html.classList.add("pw-desktop", dark ? "dark" : "light");
+  html.dataset.theme = dark ? "dark" : "light";
+  html.style.backgroundColor = dark ? "#0f1413" : "#eef2f1";
+  var language = localStorage.getItem("patchwarden.language");
+  if (language === "zh-CN" || language === "en") html.lang = language;
+})();

package/ui/desktop-bridge.js

@@ -0,0 +1,36 @@
+(function () {
+  var api = window.patchwardenDesktop;
+  if (!api) return;
+
+  var html = document.documentElement;
+  html.classList.add("pw-desktop");
+
+  var nativeFetch = window.fetch.bind(window);
+  window.fetch = function (input, init) {
+    var options = init || {};
+    var method = String(options.method || "GET").toUpperCase();
+    if (method !== "GET" || options.signal) return nativeFetch(input, options);
+    var controller = new AbortController();
+    var timer = window.setTimeout(function () { controller.abort(); }, 10000);
+    return nativeFetch(input, Object.assign({}, options, { signal: controller.signal })).catch(function (error) {
+      if (error && error.name === "AbortError") throw new Error("请求超过 10 秒，请重试");
+      throw error;
+    }).finally(function () { window.clearTimeout(timer); });
+  };
+
+  function applyTheme(theme) {
+    var dark = theme === "dark" || (theme === "system" && window.matchMedia("(prefers-color-scheme: dark)").matches);
+    html.dataset.theme = dark ? "dark" : "light";
+    html.classList.toggle("dark", dark);
+    html.classList.toggle("light", !dark);
+    localStorage.setItem("patchwarden.desktop.theme", theme || "system");
+    html.style.backgroundColor = dark ? "#0f1413" : "#eef2f1";
+  }
+
+  window.patchwardenApplyTheme = applyTheme;
+
+  api.getPreferences().then(function (preferences) { applyTheme(preferences.theme || "system"); });
+  window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", function () {
+    api.getPreferences().then(function (preferences) { if (preferences.theme === "system") applyTheme("system"); });
+  });
+})();

package/ui/desktop.css

@@ -0,0 +1,160 @@
+/* Shared responsive shell plus desktop-only theme refinements. */
+.desktop-only-nav { display: none !important; }
+
+@view-transition { navigation: auto; }
+::view-transition-old(root), ::view-transition-new(root) { animation-duration: 120ms; animation-timing-function: ease-out; }
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(root), ::view-transition-new(root) { animation-duration: 0s; }
+}
+
+html, body { max-width: 100%; overflow-x: hidden; }
+.pw-dashboard-toolbar {
+  display: grid !important;
+  grid-template-columns: auto minmax(180px, 1fr) auto;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+}
+.pw-toolbar-actions, .pw-toolbar-links { display: flex; align-items: center; gap: 8px; min-width: 0; flex-wrap: wrap; }
+.pw-toolbar-repo { min-width: 0; }
+.pw-toolbar-repo select { width: 100%; min-width: 0 !important; max-width: 100%; }
+@media (min-width: 1121px) {
+  .pw-dashboard-toolbar { grid-template-columns: max-content minmax(160px, 1fr) max-content; }
+  .pw-toolbar-actions, .pw-toolbar-links { flex-wrap: nowrap; }
+  .pw-dashboard-toolbar .pw-toolbar-actions button,
+  .pw-dashboard-toolbar .pw-toolbar-links a,
+  .pw-dashboard-toolbar .pw-toolbar-links button { padding-left: 9px !important; padding-right: 9px !important; }
+}
+
+.pw-app-shell { display: flex; height: 100vh; margin: 0; color: var(--pw-text-primary); background: var(--pw-bg-elevated); font-family: var(--pw-font-sans); }
+.pw-sidebar { display: flex; flex: 0 0 220px; flex-direction: column; height: 100vh; background: var(--pw-bg); border-right: 1px solid var(--pw-border); }
+.pw-brand { display: flex; align-items: center; gap: 10px; min-height: 58px; padding: 0 18px; border-bottom: 1px solid var(--pw-border-subtle); }
+.pw-brand svg { width: 21px; color: var(--pw-accent); }
+.pw-sidebar nav { display: flex; flex-direction: column; gap: 4px; padding: 14px 10px; overflow-y: auto; }
+.pw-sidebar nav a { display: flex; align-items: center; gap: 10px; min-height: 38px; padding: 0 10px; color: var(--pw-text-secondary); text-decoration: none; border-radius: 6px; }
+.pw-sidebar nav a:hover { color: var(--pw-text-primary); background: var(--pw-bg-hover); }
+.pw-sidebar nav a[data-active="true"] { color: var(--pw-accent); background: var(--pw-accent-subtle); border-left: 2px solid var(--pw-accent); }
+.pw-sidebar nav svg { width: 17px; flex: none; }
+.pw-page { display: flex; flex: 1; min-width: 0; flex-direction: column; height: 100vh; }
+.pw-page-header { display: flex; align-items: center; justify-content: space-between; gap: 20px; min-height: 74px; padding: 12px 24px; background: var(--pw-bg-surface); border-bottom: 1px solid var(--pw-border); }
+.pw-page-header h1 { margin: 0; font-size: 19px; letter-spacing: 0; }
+.pw-page-header p { margin: 4px 0 0; color: var(--pw-text-secondary); font-size: 12px; }
+.pw-page-header select { min-height: 34px; max-width: 190px; padding: 0 28px 0 10px; color: var(--pw-text-primary); background: var(--pw-bg-elevated); border: 1px solid var(--pw-border); border-radius: 6px; }
+.getting-started-main { flex: 1; min-width: 0; padding: 22px 24px; overflow-y: auto; }
+.readiness-list { max-width: 980px; background: var(--pw-bg-surface); border: 1px solid var(--pw-border); border-radius: 7px; }
+.readiness-item { display: grid; grid-template-columns: 34px minmax(0, 1fr) auto; align-items: center; gap: 15px; min-height: 112px; padding: 18px; border-bottom: 1px solid var(--pw-border-subtle); }
+.readiness-item:last-child { border-bottom: 0; }
+.check-index { display: grid; width: 30px; height: 30px; place-items: center; color: var(--pw-text-secondary); border: 1px solid var(--pw-border); border-radius: 50%; font: 600 12px var(--pw-font-mono); }
+.readiness-item[data-state="ready"] .check-index { color: var(--pw-text-inverse); background: var(--pw-state-success); border-color: var(--pw-state-success); }
+.check-heading { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+.check-heading h2 { margin: 0; font-size: 14px; letter-spacing: 0; }
+.readiness-item p { margin: 7px 0 0; color: var(--pw-text-secondary); font-size: 12px; line-height: 1.5; }
+.readiness-item .reason-detail { color: var(--pw-state-error); }
+.check-status { padding: 3px 7px; color: var(--pw-state-warning); background: var(--pw-state-warning-bg); border-radius: 4px; font-size: 11px; }
+.readiness-item[data-state="ready"] .check-status { color: var(--pw-state-success); background: var(--pw-state-success-bg); }
+.check-status.manual { color: var(--pw-text-secondary); background: var(--pw-bg-hover); }
+.primary-command { display: none; align-items: center; justify-content: center; min-height: 36px; padding: 0 13px; color: var(--pw-text-inverse); background: var(--pw-accent); border: 1px solid var(--pw-accent); border-radius: 6px; text-decoration: none; font: 600 12px var(--pw-font-sans); cursor: pointer; white-space: nowrap; }
+.readiness-item[data-primary-action="true"] .primary-command { display: inline-flex; }
+.primary-command:disabled { cursor: wait; opacity: .62; }
+.guide-band { max-width: 980px; margin-top: 16px; padding: 18px 0; }
+.guide-band h2 { margin: 0 0 10px; font-size: 13px; }
+.guide-links { display: flex; gap: 16px; flex-wrap: wrap; }
+.guide-links a { color: var(--pw-accent); font-size: 12px; }
+.pw-toast { position: fixed; right: 20px; bottom: 20px; max-width: min(360px, calc(100vw - 40px)); padding: 10px 13px; color: var(--pw-text-inverse); background: var(--pw-text-primary); border-radius: 6px; opacity: 0; pointer-events: none; transform: translateY(8px); transition: .18s ease; }
+.pw-toast.visible { opacity: 1; transform: translateY(0); }
+.pw-language-switcher { min-height: 34px; max-width: 190px; margin-left: auto; padding: 0 28px 0 10px; color: var(--pw-text-primary); background: var(--pw-bg-elevated); border: 1px solid var(--pw-border); border-radius: 6px; }
+aside > .pw-language-switcher { width: calc(100% - 20px); max-width: none; margin: 10px; flex: none; }
+
+html.pw-desktop {
+  --pw-bg: #eef2f1;
+  --pw-bg-elevated: #f7f9f8;
+  --pw-bg-surface: #ffffff;
+  --pw-bg-hover: #e6ece9;
+  --pw-bg-active: #dbe5e1;
+  --pw-border: #cad4d0;
+  --pw-border-subtle: #dce3e0;
+  --pw-border-focus: #167a58;
+  --pw-text-primary: #192521;
+  --pw-text-secondary: #52625c;
+  --pw-text-tertiary: #74837e;
+  --pw-text-inverse: #ffffff;
+  --pw-text-accent: #167a58;
+  --pw-accent: #167a58;
+  --pw-accent-hover: #105f45;
+  --pw-accent-muted: rgba(22, 122, 88, 0.11);
+  --pw-accent-subtle: rgba(22, 122, 88, 0.06);
+  --pw-code-bg: #18201e;
+  color-scheme: light;
+}
+
+html.pw-desktop.dark {
+  --pw-bg: #0f1413;
+  --pw-bg-elevated: #141a18;
+  --pw-bg-surface: #1b2321;
+  --pw-bg-hover: #25302d;
+  --pw-bg-active: #2c3935;
+  --pw-border: #34423e;
+  --pw-border-subtle: #293530;
+  --pw-text-primary: #edf4f1;
+  --pw-text-secondary: #a0afa9;
+  --pw-text-tertiary: #71817b;
+  --pw-accent: #43c798;
+  --pw-accent-hover: #60d8ad;
+  --pw-text-accent: #43c798;
+  --pw-accent-muted: rgba(67, 199, 152, 0.13);
+  --pw-accent-subtle: rgba(67, 199, 152, 0.07);
+  color-scheme: dark;
+}
+
+html.pw-desktop body { background: var(--pw-bg) !important; color: var(--pw-text-primary) !important; }
+html.pw-desktop .desktop-only-nav { display: flex !important; }
+html.pw-desktop aside { width: 220px !important; background: var(--pw-bg) !important; }
+html.pw-desktop aside > div:first-child { padding-top: 17px !important; padding-bottom: 17px !important; }
+html.pw-desktop header { min-height: 58px; background: var(--pw-bg-surface) !important; }
+html.pw-desktop main { background: var(--pw-bg-elevated) !important; }
+html.pw-desktop section,
+html.pw-desktop table,
+html.pw-desktop .bg-white,
+html.pw-desktop .bg-gray-50,
+html.pw-desktop .bg-slate-50 { background-color: var(--pw-bg-surface) !important; }
+html.pw-desktop input,
+html.pw-desktop select,
+html.pw-desktop textarea { background-color: var(--pw-bg-elevated) !important; color: var(--pw-text-primary) !important; border-color: var(--pw-border) !important; }
+html.pw-desktop .text-gray-900,
+html.pw-desktop .text-slate-900 { color: var(--pw-text-primary) !important; }
+html.pw-desktop .text-gray-500,
+html.pw-desktop .text-gray-600,
+html.pw-desktop .text-slate-500,
+html.pw-desktop .text-slate-600 { color: var(--pw-text-secondary) !important; }
+html.pw-desktop .border-gray-200,
+html.pw-desktop .border-slate-200 { border-color: var(--pw-border) !important; }
+html.pw-desktop [data-nav-key] { border-radius: 6px !important; }
+html.pw-desktop [data-nav-key][data-active="true"] { border-left-width: 2px !important; }
+html.pw-desktop button, html.pw-desktop select, html.pw-desktop input { border-radius: 6px !important; letter-spacing: 0; }
+html.pw-desktop .rounded-lg { border-radius: 7px !important; }
+html.pw-desktop .rounded-xl { border-radius: 8px !important; }
+html.pw-desktop [style*="box-shadow"] { box-shadow: none !important; }
+html.pw-desktop .pw-desktop-badge { color: var(--pw-accent); background: var(--pw-accent-subtle); border: 1px solid var(--pw-border); }
+
+@media (max-width: 1050px) {
+  html.pw-desktop aside { width: 196px !important; }
+  html.pw-desktop main { padding: 18px !important; }
+}
+
+@media (max-width: 1120px) {
+  .pw-dashboard-toolbar { grid-template-columns: minmax(0, 1fr) auto; }
+  .pw-toolbar-actions { grid-column: 1 / -1; }
+  .pw-toolbar-links { justify-content: flex-end; }
+}
+
+@media (max-width: 980px) {
+  .pw-sidebar { flex-basis: 190px; }
+  .pw-page-header, .getting-started-main { padding-left: 18px; padding-right: 18px; }
+  .readiness-item { grid-template-columns: 34px minmax(0, 1fr); }
+  .readiness-item .primary-command { grid-column: 2; justify-self: start; }
+}
+
+@media (max-width: 760px) {
+  .pw-dashboard-toolbar { grid-template-columns: 1fr; }
+  .pw-toolbar-actions, .pw-toolbar-links { flex-wrap: wrap; justify-content: flex-start; }
+}

package/ui/getting-started.js

@@ -0,0 +1,93 @@
+(function () {
+  var api = window.patchwardenDesktop;
+  var i18n = window.PatchWardenI18n;
+  var statusData = null;
+  var tunnelData = null;
+  var coreStarting = false;
+  var lastCoreReady = false;
+  function tr(key) { return i18n ? i18n.t(key) : key; }
+  function item(name) { return document.querySelector('[data-check="' + name + '"]'); }
+  function reasonText(reason, fallback) {
+    if (!reason) return "";
+    var key = "reason." + reason; var translated = tr(key);
+    return translated === key ? (fallback || reason) : translated;
+  }
+  function render(name, state, message, reason, fallback) {
+    var root = item(name); if (!root) return;
+    root.dataset.state = state;
+    root.querySelector("[data-status]").textContent = tr(state === "ready" ? "home.ready" : state === "manual" ? "home.manual" : "home.needsAction");
+    root.querySelector("[data-message]").textContent = tr(message);
+    var detail = root.querySelector("[data-reason]"); if (detail) detail.textContent = reasonText(reason, fallback);
+  }
+  function renderLiveCheck(name, check) {
+    if (!check) return;
+    var root = item(name); if (!root) return;
+    var state = check.state === "ready" ? "ready" : check.state === "optional" ? "manual" : "action";
+    root.dataset.state = state;
+    root.querySelector("[data-status]").textContent = tr(state === "ready" ? "home.ready" : state === "manual" ? "home.manual" : "home.needsAction");
+    root.querySelector("[data-message]").textContent = check.detail || "";
+    var detail = root.querySelector("[data-reason]"); if (detail) detail.textContent = "";
+  }
+  function setPrimaryAction(name) {
+    ["workspace", "core", "tunnel", "chatgpt"].forEach(function (key) {
+      var root = item(key);
+      if (root) root.dataset.primaryAction = key === name ? "true" : "false";
+    });
+  }
+  function syncCoreButton() {
+    var button = document.getElementById("startCore");
+    button.disabled = coreStarting || lastCoreReady;
+    button.textContent = tr(coreStarting ? "home.startingCore" : lastCoreReady ? "home.coreRunning" : "home.startCore");
+  }
+  async function fetchJson(url, options) {
+    var response = await fetch(url, options); var body = await response.json().catch(function () { return {}; });
+    if (!response.ok || body.ok === false) { var error = new Error(body.error || "Request failed"); error.reasonCode = body.reason_code; error.nextSteps = body.next_steps || []; throw error; }
+    return body;
+  }
+  async function refresh() {
+    statusData = await fetchJson("/api/status");
+    var agents = Array.isArray(statusData.agents) ? statusData.agents : [];
+    var workspaceReady = !!statusData.workspace_root && agents.some(function (agent) { return agent && agent.available; });
+    var coreAvailable = !!(statusData.core && statusData.core.available);
+    var watcherReady = !!(statusData.watcher && statusData.watcher.status === "healthy");
+    var coreReady = coreAvailable && watcherReady;
+    var coreTunnel = statusData.tunnel && statusData.tunnel.core ? statusData.tunnel.core : {};
+    var tunnelReady = coreTunnel.ready === true;
+
+    render("workspace", workspaceReady ? "ready" : "action", workspaceReady ? "home.workspaceReady" : "home.workspaceMissing", workspaceReady ? null : "workspace_agent_missing");
+    render("core", coreReady ? "ready" : "action", coreReady ? "home.coreReady" : "home.coreMissing", coreReady ? null : (statusData.watcher && statusData.watcher.reason) || (statusData.core && statusData.core.reason) || "watcher_unhealthy");
+    render("tunnel", tunnelReady ? "ready" : "action", tunnelReady ? "home.tunnelReady" : "home.tunnelMissing", tunnelReady ? null : coreTunnel.reason_code || "tunnel_not_ready");
+    render("chatgpt", "manual", "home.chatgptManual", null);
+
+    lastCoreReady = coreReady;
+    syncCoreButton();
+    setPrimaryAction(!workspaceReady ? "workspace" : !coreReady ? "core" : !tunnelReady ? "tunnel" : "chatgpt");
+  }
+  async function startCore() {
+    coreStarting = true;
+    syncCoreButton();
+    render("core", "action", "home.coreStarting");
+    try {
+      var token = await fetchJson("/control-token.json");
+      await fetchJson("/api/core/start", { method: "POST", headers: { "X-PatchWarden-Control-Token": token.token } });
+      await refresh();
+    } catch (error) {
+      lastCoreReady = false;
+      var fallback = error.message + (error.nextSteps && error.nextSteps[0] ? " " + error.nextSteps[0] : "");
+      render("core", "action", "home.startFailed", error.reasonCode || "start_failed", fallback);
+      toastText(reasonText(error.reasonCode || "start_failed", fallback));
+    } finally {
+      coreStarting = false;
+      syncCoreButton();
+    }
+  }
+  function toastText(value) { var node = document.getElementById("toast"); node.textContent = value; node.classList.add("visible"); setTimeout(function () { node.classList.remove("visible"); }, 4000); }
+  function toast(key) { toastText(tr(key)); }
+  document.getElementById("startCore").addEventListener("click", startCore);
+  document.getElementById("copyPrompt").addEventListener("click", function () { navigator.clipboard.writeText("Call health_check and report Core readiness, Watcher health, active profile, and the discovered tool count.").then(function () { toast("home.copied"); }); });
+  var language = document.getElementById("language");
+  window.addEventListener("patchwarden:i18nready", function () { language.value = i18n.getSelectedLanguage(); void refresh(); });
+  language.addEventListener("change", function () { void i18n.setLanguage(language.value).then(refresh); });
+  window.addEventListener("patchwarden:languagechange", function () { if (statusData) void refresh(); });
+  if (window.lucide) window.lucide.createIcons();
+})();