arkaos 4.33.0 → 4.34.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.33.0 — 89 agents, 17 departments, 331 skills, 297 commands, 16 ADRs.
+> v4.34.0 — 89 agents, 17 departments, 331 skills, 297 commands, 16 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-4.33.0
+4.34.0

package/config/hooks/session-start.sh

@@ -32,6 +32,6 @@ fi
 
 # ─── Degraded fallback: static banner, valid JSON, exit 0 ──────────────
 cat <<'EOF'
-{"systemMessage": "\n╔══════════════════════════════════════════════╗\n║              A R K A   O S                   ║\n║   The Operating System for AI Teams          ║\n╚══════════════════════════════════════════════╝\nOlá, founder (WizardingCode)\nArkaOS (degraded: no usable interpreter — run npx arkaos doctor)"}
+{"systemMessage": "\n  ▲  A R K A   O S\n     The Operating System for AI Agent Teams\n\n  Olá, founder\n  degraded: no usable interpreter — run npx arkaos doctor"}
 EOF
 exit 0

package/config/statusline.sh

@@ -173,7 +173,12 @@ if [ -f "$ARKA_CONFIG" ]; then
 fi
 
 # ─── Build Line 1: Context bar ───────────────────────────────────────────
-LINE1="${C_CYAN}▲ARKA${C_RESET}  ${C_WHITE}${DIR_NAME}${C_RESET}"
+# Version from the stable snapshot (one cat, no spawn storm on re-render).
+ARKA_VER=""
+if [ -f "$HOME/.arkaos/lib/VERSION" ]; then
+  ARKA_VER=$(tr -d '[:space:]' < "$HOME/.arkaos/lib/VERSION" 2>/dev/null)
+fi
+LINE1="${C_CYAN}▲ARKA${C_RESET}${ARKA_VER:+ ${C_DIM}v${ARKA_VER}${C_RESET}}  ${C_WHITE}${DIR_NAME}${C_RESET}"
 
 # Git branch (hidden on main/master to reduce noise)
 if [ -n "$BRANCH" ] && [ "$BRANCH" != "main" ] && [ "$BRANCH" != "master" ]; then

package/core/hooks/session_start.py

@@ -7,13 +7,15 @@ print) with ONE python process that emits the full ``systemMessage``.
 Measured baseline before this consolidation: 251ms p50 (isolated floor,
 benchmarks/results.md); each spawn costs ~20-80ms.
 
-Section order preserved exactly from the shell version:
-    banner+greeting → workflow line → version+forge+drift →
-    evidence-flow contract → meta-tag contract → Model Fabric directive
-    → [SESSION] rehydrator resume → [SESSION-MEMORY] recap → JSON out.
+Presentation contract (Foundation PR-2): the user sees a compact branded
+greeting — ``systemMessage`` carries ONLY banner+greeting, workflow/forge
+state, and the drift warning. Everything the MODEL needs but the user
+should not scroll through (evidence-flow contract, meta-tag contract,
+authority brief, Model Fabric directive, [SESSION] resume,
+[SESSION-MEMORY] recap) ships via ``hookSpecificOutput.
+additionalContext`` — same enforcement, zero wall of text.
 Background side effects (reorganizer trigger, dashboard ensure) stay
-detached and are config-gated; the NEW ``cognition.reorganize_on_session``
-gate lands here (QG F2-1 follow-up, endorsed for this PR).
+detached and are config-gated (``cognition.reorganize_on_session``).
 
 The shell wrapper only resolves the interpreter and ``exec``s this
 module; with no usable venv it emits a static banner (fail-open).
@@ -35,17 +37,21 @@ _BUDGET_MS = 300
 _RECAP_ITEMS = 3
 _SUMMARY_CHARS = 130
 
-_BANNER = (
-    "\n╔══════════════════════════════════════════════╗\n"
-    "║                                              ║\n"
-    "║              A R K A   O S                   ║\n"
-    "║                                              ║\n"
-    "║   The Operating System for AI Teams          ║\n"
-    "║                  by WizardingCode            ║\n"
-    "║                                              ║\n"
-    "╚══════════════════════════════════════════════╝\n"
+# Compact wordmark (Levitation identity: flat apex + floating bar) — the
+# box-drawing wall it replaces read as a default terminal artifact.
+_FALLBACK_BANNER = (
+    "\n  ▲  A R K A   O S\n"
+    "     The Operating System for AI Agent Teams\n"
 )
 
+
+def _banner(version: str, name: str, company: str) -> str:
+    return (
+        f"\n  ▲  A R K A   O S — v{version}\n"
+        f"     The Operating System for AI Agent Teams · {company}\n"
+        f"\n  Olá, {name}\n"
+    )
+
 _EVIDENCE_CONTRACT = (
     "\n\n[ARKA:EVIDENCE-FLOW] NON-NEGOTIABLE. Every non-trivial request runs"
     " the 4-gate evidence flow (constitution rule evidence-flow; source"
@@ -266,27 +272,52 @@ def _authority_brief(cwd: str) -> str:
     return f"\n\n{brief}" if brief else ""
 
 
-def build_message(cwd: str) -> str:
+def build_visible(cwd: str) -> str:
+    """User-facing ``systemMessage``: branded greeting + live state only.
+
+    Owns the background side effects (reorganizer, dashboard ensure) so
+    they fire exactly once per session regardless of which builder a
+    caller combines.
+    """
     repo = repo_path()
     config = _config()
     name, company = _profile()
     version = _version(repo)
-    msg = _BANNER + f"\nOlá, {name} ({company})\n"
+    msg = _banner(version, name, company)
     msg += _workflow_line()
-    msg += f"ArkaOS v{version}"
     msg += _forge_line()
     msg += _drift(version)
-    msg += _EVIDENCE_CONTRACT
-    msg += _META_TAG_CONTRACT
-    msg += _authority_brief(cwd)
-    msg += _model_fabric()
     _trigger_reorganizer(repo, config)
     _ensure_dashboard(repo, config)
-    msg += _session_resume()
+    return msg
+
+
+def build_context(cwd: str) -> str:
+    """Model-only ``additionalContext``: the operating contracts.
+
+    Same text that used to flood the visible banner — the enforcement
+    surfaces (PreToolUse gate, Stop hook) read the model's OUTPUT
+    markers, so moving the injected contracts off-screen changes nothing
+    about enforcement.
+    """
+    parts = [
+        _EVIDENCE_CONTRACT,
+        _META_TAG_CONTRACT,
+        _authority_brief(cwd),
+        _model_fabric(),
+        _session_resume(),
+    ]
     recap = build_recap(cwd)
     if recap:
-        msg += f"\n\n{recap}"
-    return msg
+        parts.append(f"\n\n{recap}")
+    return "".join(parts).lstrip("\n")
+
+
+def build_message(cwd: str) -> str:
+    """Full text (visible + contracts) — legacy single-string view."""
+    visible = build_visible(cwd)
+    context = build_context(cwd)
+    return visible + (f"\n\n{context}" if context else "")
 
 
 def build_recap(cwd: str, budget_ms: int = _BUDGET_MS) -> str:
@@ -336,10 +367,20 @@ def main(stdin_json: dict | None = None) -> int:
         or os.getcwd()
     )
     try:
-        message = build_message(cwd)
+        visible = build_visible(cwd)
     except Exception:  # absolute fail-open: static banner, exit 0
-        message = _BANNER + "\nOlá, founder (WizardingCode)\nArkaOS"
-    print(json.dumps({"systemMessage": message}))
+        visible = _FALLBACK_BANNER + "\n  Olá, founder\n"
+    try:
+        context = build_context(cwd)
+    except Exception:  # contracts are best-effort; greeting never breaks
+        context = ""
+    payload: dict = {"systemMessage": visible}
+    if context:
+        payload["hookSpecificOutput"] = {
+            "hookEventName": "SessionStart",
+            "additionalContext": context,
+        }
+    print(json.dumps(payload))
     return 0
 
 

package/harness/codex/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.33.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.34.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/copilot/copilot-instructions.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.33.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.34.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/cursor/rules/arkaos.mdc

@@ -1,11 +1,11 @@
 ---
-description: ArkaOS v4.33.0 agent-team contract
+description: ArkaOS v4.34.0 agent-team contract
 alwaysApply: true
 ---
 
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.33.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.34.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/gemini/GEMINI.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.33.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.34.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/opencode/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.33.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.34.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/harness/zed/.rules

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.33.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.34.0 — 89 agents, 17 departments, 331 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.

package/installer/autoupdate.js

@@ -0,0 +1,249 @@
+/**
+ * Background auto-update daemon for ArkaOS (Foundation PR-1).
+ *
+ * Users were found running v2 while v4.33 was live — the update path
+ * (`npx arkaos@latest update`) only fires when the user remembers to run
+ * it. This installs a per-OS scheduled unit that runs
+ * `scripts/auto-update.sh` daily (and at load): the script checks the npm
+ * registry, applies the core update headlessly, and notifies the user.
+ * Project sync stays supervised — the next Claude session picks it up via
+ * [arka:update-available].
+ *
+ * Opt-in by default on install/update (`ensureDefaultEnabled`), with a
+ * persisted opt-out marker so `npx arkaos autoupdate disable` survives
+ * future updates. ESM, Node + Bun, no interactive prompts. Unit
+ * generation (`unitFor`) is pure so it can be unit-tested without
+ * touching the OS (autostart.js precedent).
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const AUTOUPDATE_LABEL = "io.wizardingcode.arkaos.updater";
+const SERVICE_NAME = "arkaos-updater.service";
+const TIMER_NAME = "arkaos-updater.timer";
+
+function defaultRepoRoot() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+/** Pure: the opt-out marker path — written by disable(), honored by
+ *  ensureDefaultEnabled() and by scripts/auto-update.sh itself. */
+export function optoutPath(home = homedir()) {
+  return join(home, ".arkaos", "autoupdate.optout");
+}
+
+/** Anchor the daemon at the stable ~/.arkaos/lib snapshot, never at the
+ *  package root when it can be an npx cache: `npm cache clean` purges
+ *  that location at any time, and a default-on daemon anchored there
+ *  dies silently — with no surviving daemon to self-heal (QG blocker,
+ *  Foundation PR-1). core-snapshot.js ships scripts/ into the snapshot;
+ *  repoRoot is the fallback for dev checkouts before the first deploy. */
+export function stableRoot({ home = homedir(), repoRoot = defaultRepoRoot() } = {}) {
+  const lib = join(home, ".arkaos", "lib");
+  return existsSync(join(lib, "scripts", "auto-update.sh")) ? lib : repoRoot;
+}
+
+/** Pure: the scheduled unit(s) for a given platform. Throws on
+ *  unsupported OS. Returns { kind, files: [{ path, content }] } —
+ *  systemd needs a service + timer pair, launchd a single plist. */
+export function unitFor(os, { repoRoot, home }) {
+  const script = `${repoRoot}/scripts/auto-update.sh`;
+  const log = `${home}/.arkaos/logs/auto-update-daemon.log`;
+
+  if (os === "darwin") {
+    // launchd runs with a minimal PATH (/usr/bin:/bin:...) — node/npx
+    // live in /opt/homebrew/bin or /usr/local/bin, so the plist must
+    // carry a usable PATH or the daemon dies on `command -v npx`.
+    // StartCalendarInterval fires daily; RunAtLoad covers machines that
+    // were asleep/off at that hour (login catches up).
+    const content = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${AUTOUPDATE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>${script}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+  </dict>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key>
+    <integer>10</integer>
+    <key>Minute</key>
+    <integer>30</integer>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${log}</string>
+  <key>StandardErrorPath</key>
+  <string>${log}</string>
+</dict>
+</plist>
+`;
+    return {
+      kind: "launchd",
+      files: [
+        {
+          path: join(home, "Library", "LaunchAgents", `${AUTOUPDATE_LABEL}.plist`),
+          content,
+        },
+      ],
+    };
+  }
+
+  if (os === "linux") {
+    const service = `[Unit]
+Description=ArkaOS auto-update (npm registry watch + headless core update)
+After=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=/bin/bash ${script}
+StandardOutput=append:${log}
+StandardError=append:${log}
+`;
+    // Persistent=true replays a missed daily run at next boot — the
+    // laptop-that-was-off case that left users on v2.
+    const timer = `[Unit]
+Description=Daily ArkaOS auto-update check
+
+[Timer]
+OnCalendar=daily
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`;
+    const unitDir = join(home, ".config", "systemd", "user");
+    return {
+      kind: "systemd",
+      files: [
+        { path: join(unitDir, SERVICE_NAME), content: service },
+        { path: join(unitDir, TIMER_NAME), content: timer },
+      ],
+    };
+  }
+
+  throw new Error(`unsupported platform for autoupdate: ${os}`);
+}
+
+function _silent(cmd) {
+  try {
+    execSync(cmd, { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function enable({ repoRoot = defaultRepoRoot() } = {}) {
+  const root = stableRoot({ repoRoot });
+  const unit = unitFor(process.platform, { repoRoot: root, home: homedir() });
+  mkdirSync(join(homedir(), ".arkaos", "logs"), { recursive: true });
+  for (const f of unit.files) {
+    mkdirSync(dirname(f.path), { recursive: true });
+    writeFileSync(f.path, f.content, "utf8");
+  }
+  if (existsSync(optoutPath())) rmSync(optoutPath());
+  const mainPath = unit.files[0].path;
+  if (unit.kind === "launchd") {
+    _silent(`launchctl unload "${mainPath}"`);
+    if (!_silent(`launchctl load -w "${mainPath}"`)) {
+      return { ok: false, path: mainPath,
+        message: "Plist written but launchctl load failed — it will still run at next login." };
+    }
+  } else if (unit.kind === "systemd") {
+    _silent("systemctl --user daemon-reload");
+    if (!_silent(`systemctl --user enable --now ${TIMER_NAME}`)) {
+      return { ok: false, path: mainPath,
+        message: "Timer written but systemctl enable failed — check 'systemctl --user' availability." };
+    }
+  }
+  return { ok: true, path: mainPath,
+    message: "Auto-update enabled. ArkaOS checks npm daily and updates itself." };
+}
+
+export function disable() {
+  const unit = unitFor(process.platform, { repoRoot: defaultRepoRoot(), home: homedir() });
+  const mainPath = unit.files[0].path;
+  if (unit.kind === "launchd") _silent(`launchctl unload "${mainPath}"`);
+  else if (unit.kind === "systemd") _silent(`systemctl --user disable --now ${TIMER_NAME}`);
+  for (const f of unit.files) if (existsSync(f.path)) rmSync(f.path);
+  // Persisted opt-out: future `npx arkaos update` runs must not re-enable.
+  mkdirSync(join(homedir(), ".arkaos"), { recursive: true });
+  writeFileSync(optoutPath(), new Date().toISOString(), "utf8");
+  return { ok: true, path: mainPath, message: "Auto-update disabled (opt-out persisted)." };
+}
+
+export function status() {
+  let unit;
+  try {
+    unit = unitFor(process.platform, { repoRoot: defaultRepoRoot(), home: homedir() });
+  } catch (err) {
+    return { installed: false, supported: false, optout: false, message: err.message };
+  }
+  return {
+    installed: unit.files.every((f) => existsSync(f.path)),
+    supported: true,
+    optout: existsSync(optoutPath()),
+    kind: unit.kind,
+    path: unit.files[0].path,
+  };
+}
+
+/** Default-on wiring for install/update flows: enable unless the user
+ *  opted out or the platform is unsupported. Never throws. */
+export function ensureDefaultEnabled({ repoRoot = defaultRepoRoot() } = {}) {
+  const s = status();
+  if (!s.supported) return { action: "unsupported" };
+  if (s.optout) return { action: "optout" };
+  if (s.installed) {
+    // Refresh unit content in place (paths/schedule may change between
+    // versions) but do not force a reload storm on every update.
+    try {
+      const root = stableRoot({ repoRoot });
+      const unit = unitFor(process.platform, { repoRoot: root, home: homedir() });
+      for (const f of unit.files) writeFileSync(f.path, f.content, "utf8");
+    } catch {}
+    return { action: "already-enabled" };
+  }
+  const r = enable({ repoRoot });
+  return { action: r.ok ? "enabled" : "partial", message: r.message };
+}
+
+export async function autoupdate(args = []) {
+  const action = (args[0] || "status").toLowerCase();
+  if (action === "enable") {
+    const r = enable();
+    console.log(`  ${r.ok ? "✓" : "⚠"} ${r.message}\n    ${r.path}`);
+  } else if (action === "disable") {
+    const r = disable();
+    console.log(`  ✓ ${r.message}`);
+  } else if (action === "run") {
+    // Foreground one-shot check — same script (and anchor) the daemon runs.
+    const script = join(stableRoot(), "scripts", "auto-update.sh");
+    try {
+      execSync(`/bin/bash "${script}" --force`, { stdio: "inherit" });
+    } catch { process.exitCode = 1; }
+  } else if (action === "status") {
+    const s = status();
+    if (!s.supported) console.log(`  Auto-update not supported here: ${s.message}`);
+    else if (s.optout) console.log(`  Auto-update: DISABLED by user opt-out\n    (re-enable: npx arkaos autoupdate enable)`);
+    else console.log(`  Auto-update: ${s.installed ? "ENABLED" : "disabled"} (${s.kind})\n    ${s.path}`);
+  } else {
+    console.error(`  Unknown autoupdate action: ${action}. Use enable | disable | status | run.`);
+    process.exitCode = 1;
+  }
+}

package/installer/cli.js

@@ -63,6 +63,7 @@ Usage:
   npx arkaos migrate-user-data  Move user data (~/.claude/skills/arka/ → ~/.arkaos/)
   npx arkaos dashboard        Start monitoring dashboard
   npx arkaos autostart <enable|disable|status>  Start dashboard on boot
+  npx arkaos autoupdate <enable|disable|status|run>  Keep ArkaOS updated automatically (daily check + notification)
   npx arkaos keys             Manage API keys (OpenAI, fal.ai, etc.)
   npx arkaos models           Model Fabric: which model runs each role
   npx arkaos models set <role> <provider>/<model>  Re-route a role
@@ -134,6 +135,12 @@ async function main() {
       break;
     }
 
+    case "autoupdate": {
+      const { autoupdate } = await import("./autoupdate.js");
+      await autoupdate(positionals.slice(1));
+      break;
+    }
+
     case "uninstall":
       const { uninstall } = await import("./uninstall.js");
       await uninstall();

package/installer/core-snapshot.js

@@ -35,7 +35,11 @@ import { join, basename } from "node:path";
 // resolve_arkaos_root() checks, so a crash mid-deploy on a fresh install
 // leaves a snapshot that fails validation instead of a core-only root
 // that validates but lacks config/departments/knowledge.
-const SNAPSHOT_DIRS = ["config", "departments", "knowledge", "core"];
+// scripts/ joined in Foundation PR-1: the auto-update daemon's launchd/
+// systemd unit anchors at the snapshot (a unit pointing into the npx
+// cache dies silently on `npm cache clean` — QG blocker). Under 0.5MB
+// after the __pycache__ filter.
+const SNAPSHOT_DIRS = ["config", "departments", "knowledge", "scripts", "core"];
 
 export function deployCoreSnapshot(arkaosRoot, installDir) {
   if (!existsSync(join(arkaosRoot, "core", "sync", "__init__.py"))) return false;

package/installer/doctor.js

@@ -6,6 +6,7 @@ import { getArkaosPython, getVenvPython, canImportCore, getRepoRoot, diagnoseVen
 import { IS_WINDOWS, HOOK_EXT, CMD_FINDER } from "./platform.js";
 import { checkNode, checkObsidian, checkOllama } from "./system-tools.js";
 import { graphifyDoctor } from "./graphify.js";
+import { status as autoupdateStatus } from "./autoupdate.js";
 
 const INSTALL_DIR = join(homedir(), ".arkaos");
 
@@ -563,6 +564,16 @@ export const checks = [
     check: () => statuslineConfigured(),
     fix: () => "Run: npx arkaos install --force (redeploys and wires the statusline)",
   },
+  {
+    name: "autoupdate",
+    description: "Auto-update daemon installed (or explicit user opt-out)",
+    severity: "warn",
+    check: () => {
+      const s = autoupdateStatus();
+      return !s.supported || s.optout || s.installed;
+    },
+    fix: () => "Run: npx arkaos autoupdate enable",
+  },
   {
     name: "hooks-wired",
     description: "Hook chain referenced by ~/.claude/settings.json (governance live)",

package/installer/index.js

@@ -324,6 +324,17 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
     console.log(`         Warning: could not seed config.json (${err.message})`);
   }
 
+  // Foundation PR-1 — auto-update daemon, default-on (opt-out persists
+  // across installs via ~/.arkaos/autoupdate.optout).
+  try {
+    const { ensureDefaultEnabled } = await import("./autoupdate.js");
+    const au = ensureDefaultEnabled({ repoRoot: ARKAOS_ROOT });
+    if (au.action === "enabled") console.log(`         Auto-update daemon enabled (npx arkaos autoupdate status).`);
+    else if (au.action === "optout") console.log(`         Auto-update daemon: user opt-out respected.`);
+  } catch (err) {
+    console.log(`         Warning: auto-update daemon not enabled (${err.message})`);
+  }
+
   // PR28 v2.47.0 — scaffold the user-mutable files the discipline-arc
   // commands depend on: redaction-clients.json (leak scanner config)
   // and reorganize-proposals/ (daily proposal output). Idempotent.

package/installer/update.js

@@ -534,6 +534,17 @@ export async function update({ skillsFlag = "" } = {}) {
     console.log(`         ⚠ Could not set up Graphify (${err.message})`);
   }
 
+  // ── 7b. Auto-update daemon (Foundation PR-1) — default-on, opt-out kept ──
+  try {
+    const { ensureDefaultEnabled } = await import("./autoupdate.js");
+    const au = ensureDefaultEnabled({ repoRoot: ARKAOS_ROOT });
+    if (au.action === "enabled") console.log("         ✓ Auto-update daemon enabled (daily npm check + notification)");
+    else if (au.action === "already-enabled") console.log("         ✓ Auto-update daemon active");
+    else if (au.action === "optout") console.log("         · Auto-update daemon: user opt-out respected");
+  } catch (err) {
+    console.log(`         ⚠ Auto-update daemon not enabled (${err.message})`);
+  }
+
   // ── 8. Update manifest ──
   console.log("  [8/8] Finalizing...");
   manifest.version = VERSION;

package/knowledge/skills-manifest.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "generator": "scripts/marketplace_gen.py",
-    "version": "4.33.0",
+    "version": "4.34.0",
     "marketplace": "arkaos"
   },
   "structural": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.33.0",
+  "version": "4.34.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.33.0"
+version = "4.34.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/auto-update.sh

@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS — background auto-update (Foundation PR-1)
+#
+# Invoked daily by the io.wizardingcode.arkaos.updater unit (see
+# installer/autoupdate.js) or manually via `npx arkaos autoupdate run`.
+#
+# Flow: registry check (curl, short timeout) → compare with the installed
+# version (~/.arkaos/install-manifest.json) → headless `npx -y
+# arkaos@latest update` → OS notification with the outcome. Project sync
+# stays supervised: update.js resets sync-state.json, so the next Claude
+# session surfaces [arka:update-available] and /arka update runs there.
+#
+# Every failure path logs and exits 0 — a broken check must never surface
+# as a crashing login item.
+# ============================================================================
+set -u
+
+ARKA_HOME="${HOME}/.arkaos"
+LOG_DIR="${ARKA_HOME}/logs"
+LOG="${LOG_DIR}/auto-update.log"
+LOCK_DIR="${ARKA_HOME}/auto-update.lock"
+MANIFEST="${ARKA_HOME}/install-manifest.json"
+OPTOUT="${ARKA_HOME}/autoupdate.optout"
+PROFILE="${ARKA_HOME}/profile.json"
+REGISTRY_URL="https://registry.npmjs.org/arkaos/latest"
+
+FORCE=0
+[ "${1:-}" = "--force" ] && FORCE=1
+
+mkdir -p "$LOG_DIR"
+
+log() {
+  printf '%s %s\n' "$(date '+%Y-%m-%dT%H:%M:%S')" "$1" >> "$LOG"
+}
+
+# Keep the log bounded (~1MB cap, keep the newest half).
+rotate_log() {
+  local size
+  size=$(wc -c < "$LOG" 2>/dev/null || echo 0)
+  if [ "${size:-0}" -gt 1048576 ]; then
+    tail -c 524288 "$LOG" > "${LOG}.tmp" && mv "${LOG}.tmp" "$LOG"
+  fi
+}
+
+# JSON field reader: venv python → python3 → sed (last resort).
+json_field() {
+  local file="$1" field="$2"
+  local py="${ARKA_HOME}/venv/bin/python"
+  [ -x "$py" ] || py="$(command -v python3 || true)"
+  if [ -n "$py" ]; then
+    "$py" -c "import json,sys; print(json.load(open(sys.argv[1])).get(sys.argv[2],''))" \
+      "$file" "$field" 2>/dev/null && return 0
+  fi
+  sed -n "s/.*\"${field}\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$file" 2>/dev/null | head -1
+}
+
+notify() {
+  local msg="$1"
+  log "notify: $msg"
+  case "$(uname -s)" in
+    Darwin)
+      command -v osascript >/dev/null 2>&1 && \
+        osascript -e "display notification \"${msg}\" with title \"ArkaOS\"" >/dev/null 2>&1
+      ;;
+    Linux)
+      command -v notify-send >/dev/null 2>&1 && notify-send "ArkaOS" "$msg" >/dev/null 2>&1
+      ;;
+  esac
+}
+
+# Notification copy follows the installed profile language (pt → pt-PT).
+LANG_CODE=""
+[ -f "$PROFILE" ] && LANG_CODE="$(json_field "$PROFILE" language)"
+
+msg_updated() {
+  if [ "$LANG_CODE" = "pt" ]; then
+    echo "Atualizado para v$1. Os projetos sincronizam na próxima sessão Claude."
+  else
+    echo "Updated to v$1. Projects sync on your next Claude session."
+  fi
+}
+msg_failed() {
+  if [ "$LANG_CODE" = "pt" ]; then
+    echo "Falha no auto-update (v$1). Corre: npx arkaos@latest update"
+  else
+    echo "Auto-update failed (v$1). Run: npx arkaos@latest update"
+  fi
+}
+
+rotate_log
+
+# ── Opt-out and install guards ─────────────────────────────────────────
+if [ -f "$OPTOUT" ]; then
+  log "skip: user opt-out marker present"
+  exit 0
+fi
+if [ ! -f "$MANIFEST" ]; then
+  log "skip: no install-manifest.json — ArkaOS not installed"
+  exit 0
+fi
+
+# ── Lock (mkdir is atomic); reclaim stale locks older than 2h ──────────
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  if [ -n "$(find "$LOCK_DIR" -maxdepth 0 -mmin +120 2>/dev/null)" ]; then
+    log "reclaiming stale lock"
+    rmdir "$LOCK_DIR" 2>/dev/null || true
+    mkdir "$LOCK_DIR" 2>/dev/null || { log "skip: lock contention"; exit 0; }
+  else
+    log "skip: another auto-update run holds the lock"
+    exit 0
+  fi
+fi
+trap 'rmdir "$LOCK_DIR" 2>/dev/null' EXIT
+
+# launchd/systemd environments miss the node toolchain locations; append
+# (not prepend — explicit PATH entries, e.g. test stubs, must win).
+export PATH="${PATH}:/opt/homebrew/bin:/usr/local/bin"
+
+INSTALLED="$(json_field "$MANIFEST" version)"
+if [ -z "$INSTALLED" ]; then
+  log "skip: could not read installed version from manifest"
+  exit 0
+fi
+
+if ! command -v curl >/dev/null 2>&1; then
+  log "skip: curl unavailable"
+  exit 0
+fi
+LATEST_JSON="$(curl -sf --max-time 15 "$REGISTRY_URL" 2>/dev/null || true)"
+if [ -z "$LATEST_JSON" ]; then
+  log "skip: registry unreachable (offline?)"
+  exit 0
+fi
+TMP_JSON="${ARKA_HOME}/.autoupdate-latest.json"
+printf '%s' "$LATEST_JSON" > "$TMP_JSON"
+LATEST="$(json_field "$TMP_JSON" version)"
+rm -f "$TMP_JSON"
+if [ -z "$LATEST" ]; then
+  log "skip: could not parse registry response"
+  exit 0
+fi
+
+# Only ever move FORWARD: a dev/prerelease install newer than the
+# registry `latest` must not be silently downgraded (QG, Francisca).
+# Ordering compare via python; degraded fallback is plain inequality.
+is_newer() { # is_newer LATEST INSTALLED → exit 0 when LATEST > INSTALLED
+  local py="${ARKA_HOME}/venv/bin/python"
+  [ -x "$py" ] || py="$(command -v python3 || true)"
+  if [ -n "$py" ]; then
+    "$py" -c '
+import re, sys
+def key(v):
+    core = re.split(r"[-+]", v, maxsplit=1)[0]
+    nums = [int(x) for x in re.findall(r"\d+", core)[:3]]
+    nums += [0] * (3 - len(nums))
+    return (nums, "-" not in v)  # prerelease sorts below its release
+sys.exit(0 if key(sys.argv[1]) > key(sys.argv[2]) else 1)' "$1" "$2" 2>/dev/null
+    return $?
+  fi
+  [ "$1" != "$2" ]
+}
+
+if [ "$FORCE" -ne 1 ]; then
+  if [ "$LATEST" = "$INSTALLED" ]; then
+    log "up to date (v${INSTALLED})"
+    exit 0
+  fi
+  if ! is_newer "$LATEST" "$INSTALLED"; then
+    log "installed v${INSTALLED} is ahead of registry v${LATEST} — skip"
+    exit 0
+  fi
+fi
+
+if ! command -v npx >/dev/null 2>&1; then
+  log "skip: npx unavailable — cannot apply v${LATEST}"
+  exit 0
+fi
+
+log "updating v${INSTALLED} → v${LATEST}"
+if npx -y arkaos@latest update >> "$LOG" 2>&1; then
+  log "update to v${LATEST} succeeded"
+  notify "$(msg_updated "$LATEST")"
+else
+  log "update to v${LATEST} FAILED (see log above)"
+  notify "$(msg_failed "$LATEST")"
+fi
+exit 0