@sayansr26/agent-os 0.5.2 → 0.6.0

package/plugins/agent-os/skills/init/scripts/settings.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * agent-os settings — write the permission and task-tool setup, not describe it.
+ *
+ * Three things, at project scope, user scope, or both:
+ *
+ *   settings.json  permissions.deny  += the git write-protection rules
+ *                  env.CLAUDE_CODE_ENABLE_TODO_TOOLS = "1"
+ *   CLAUDE.md      the task-tracking rule
+ *
+ * Merges, never replaces: existing keys, allow rules, deny rules and a value
+ * the user set for the env flag all survive. Idempotent. Before changing a
+ * file under ~/.claude it copies it to `<file>.agent-os.bak`; project files
+ * are left to git, so a backup does not show up as an untracked file.
+ *
+ * Previews by default. `--apply` writes. The preview is what /agent-os:init
+ * shows the user before asking once; the CLI's `init` asks the same question.
+ *
+ * Usage: node settings.mjs [--root <dir>] [--scope project|user|both] [--apply]
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const TODO_ENV = "CLAUDE_CODE_ENABLE_TODO_TOOLS";
+
+export const TASK_RULE = `- **Always track work with the task tool (TaskCreate / TaskUpdate).** Any request
+  with more than one step gets a task list before work starts: one task per
+  deliverable, marked \`in_progress\` when started and \`completed\` only when
+  verified. Keep it current as scope changes, including work delegated to
+  subagents, so I can see what is done, running and left at any moment.`;
+
+/**
+ * Every git command that changes the repository. Read-only inspection
+ * (status, log, diff, show, blame, …) stays available. The first five close
+ * the flag forms that would otherwise walk past a per-subcommand rule —
+ * references/git-permissions.md explains each judgment call.
+ */
+export const GIT_DENY = [
+  "Bash(git -C*)", "Bash(git -c*)", "Bash(git --git-dir*)", "Bash(git --work-tree*)", "Bash(git --exec-path*)",
+  "Bash(git add *)", "Bash(git am *)", "Bash(git apply *)", "Bash(git bisect *)", "Bash(git branch *)",
+  "Bash(git checkout *)", "Bash(git cherry-pick *)", "Bash(git clean *)", "Bash(git clone *)", "Bash(git commit *)",
+  "Bash(git config *)", "Bash(git fast-import *)", "Bash(git filter-branch *)", "Bash(git gc *)", "Bash(git init *)",
+  "Bash(git merge *)", "Bash(git mv *)", "Bash(git notes *)", "Bash(git prune *)", "Bash(git pull *)",
+  "Bash(git push *)", "Bash(git rebase *)", "Bash(git reflog *)", "Bash(git remote *)", "Bash(git repack *)",
+  "Bash(git replace *)", "Bash(git reset *)", "Bash(git restore *)", "Bash(git revert *)", "Bash(git rm *)",
+  "Bash(git stash *)", "Bash(git submodule *)", "Bash(git switch *)", "Bash(git symbolic-ref *)", "Bash(git tag *)",
+  "Bash(git update-ref *)", "Bash(git worktree *)",
+];
+
+export const userDir = () => process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+
+export function paths(scope, root) {
+  return scope === "user"
+    ? { settings: join(userDir(), "settings.json"), claudeMd: join(userDir(), "CLAUDE.md"), label: "USER (~/.claude)" }
+    : { settings: join(root, ".claude/settings.json"), claudeMd: join(root, "CLAUDE.md"), label: "PROJECT" };
+}
+
+const put = (p, text, keep) => {
+  if (keep && existsSync(p)) copyFileSync(p, `${p}.agent-os.bak`);
+  mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, text); };
+
+// "Bash(git commit *)" and "Bash(git commit:*)" are the same rule to Claude Code.
+const norm = (r) => r.replace(/:\*\)$/, " *)").replace(/\s+/g, " ");
+
+/**
+ * Merge the deny rules and the env flag into one settings.json.
+ * Returns { status: "changed"|"unchanged"|"invalid", file, denyAdded, env, current }
+ * where env is "added" | "present" | "conflict".
+ */
+export function mergeSettings(file, { dry = false, deny = GIT_DENY, todo = true, keep = false } = {}) {
+  let settings = {};
+  if (existsSync(file)) {
+    try { settings = JSON.parse(readFileSync(file, "utf8")); }
+    catch { return { status: "invalid", file, denyAdded: [], env: null }; }
+  }
+  const perms = settings.permissions || {};
+  const have = new Set((perms.deny || []).map(norm));
+  const denyAdded = deny.filter((r) => !have.has(norm(r)));
+
+  let env = null, current;
+  if (todo) {
+    current = (settings.env || {})[TODO_ENV];
+    // "true" and "1" are both truthy to Claude Code; an existing value is the
+    // user's choice and is left alone rather than normalised.
+    if (current === undefined) env = "added";
+    else env = current === "1" || current === "true" || current === true ? "present" : "conflict";
+  }
+
+  if (!denyAdded.length && env !== "added") return { status: "unchanged", file, denyAdded, env, current };
+
+  if (denyAdded.length) settings.permissions = { ...perms, deny: [...(perms.deny || []), ...denyAdded] };
+  if (env === "added") settings.env = { ...(settings.env || {}), [TODO_ENV]: "1" };
+  if (!dry) put(file, JSON.stringify(settings, null, 2) + "\n", keep);
+  return { status: "changed", file, denyAdded, env, current };
+}
+
+/**
+ * Put the task-tracking rule in a CLAUDE.md. Returns "added" | "present" | "no-file".
+ * A project CLAUDE.md is never created — that is the project's own
+ * always-loaded context, and a CLI inventing one leaves a stub nobody owns.
+ * The user's ~/.claude/CLAUDE.md is created when `create` is set.
+ */
+export function addTaskRule(file, { dry = false, create = false, keep = false } = {}) {
+  if (!existsSync(file)) {
+    if (!create) return { status: "no-file", file };
+    if (!dry) put(file, `# Personal working agreement\n\n${TASK_RULE}\n`);
+    return { status: "added", file, section: "new file" };
+  }
+  const text = readFileSync(file, "utf8");
+  if (/TaskCreate/.test(text)) return { status: "present", file };
+
+  // Prefer an operator-preferences section so the rule lands with the other
+  // instructions about how to work rather than orphaned at the bottom.
+  const heading = text.match(/^##\s+Operator preferences\s*$/m);
+  let next;
+  if (heading) {
+    const start = heading.index + heading[0].length;
+    const rest = text.slice(start);
+    const nextHeading = rest.search(/^##\s+/m);
+    const end = nextHeading === -1 ? text.length : start + nextHeading;
+    next = `${text.slice(0, end).replace(/\s*$/, "")}\n\n${TASK_RULE}\n\n${text.slice(end)}`;
+  } else {
+    next = `${text.replace(/\s*$/, "")}\n\n## Working agreement\n\n${TASK_RULE}\n`;
+  }
+  if (!dry) put(file, next.replace(/\n{4,}/g, "\n\n\n"), keep);
+  return { status: "added", file, section: heading ? "Operator preferences" : "Working agreement" };
+}
+
+/** Everything for one scope. */
+export function applyScope(scope, root, { dry = false } = {}) {
+  const p = paths(scope, root);
+  return {
+    scope,
+    label: p.label,
+    settings: mergeSettings(p.settings, { dry, keep: scope === "user" }),
+    rule: addTaskRule(p.claudeMd, { dry, create: scope === "user", keep: scope === "user" }),
+  };
+}
+
+export function describe(r, { dry }) {
+  const s = r.settings, lines = [];
+  const verb = dry ? "would add" : "added";
+  lines.push(`${r.label}  ${s.file}`);
+  if (s.status === "invalid") lines.push("  not valid JSON — left alone; fix it and re-run");
+  else {
+    lines.push(s.denyAdded.length
+      ? `  permissions.deny   ${verb} ${s.denyAdded.length} git write rule(s)${s.denyAdded.length < GIT_DENY.length ? ` (${GIT_DENY.length - s.denyAdded.length} already there)` : ""}`
+      : `  permissions.deny   git write protection already complete`);
+    lines.push({
+      added: `  env.${TODO_ENV}  ${verb} "1"`,
+      present: `  env.${TODO_ENV}  already on`,
+      conflict: `  env.${TODO_ENV}  is "${s.current}" — left as set`,
+    }[s.env]);
+    if (s.status === "changed" && !dry && r.scope === "user" && existsSync(`${s.file}.agent-os.bak`)) lines.push(`  backup             ${s.file}.agent-os.bak`);
+  }
+  lines.push({
+    added: `  ${r.rule.file}  ${dry ? "would add" : "added"} the task-tracking rule (${r.rule.section})`,
+    present: `  ${r.rule.file}  task-tracking rule already there`,
+    "no-file": `  ${r.rule.file}  absent — /agent-os:init builds it`,
+  }[r.rule.status]);
+  return lines;
+}
+
+function main(argv) {
+  const arg = (k, d) => { const i = argv.indexOf(k); return i === -1 ? d : argv[i + 1]; };
+  const root = arg("--root", process.cwd());
+  const scope = arg("--scope", "both");
+  const dry = !argv.includes("--apply");
+  const scopes = scope === "both" ? ["project", "user"] : [scope];
+  if (!scopes.every((s) => s === "project" || s === "user")) {
+    console.error(`--scope must be project, user or both (got "${scope}")`);
+    process.exit(2);
+  }
+  const out = [`AGENT-OS SETTINGS  ${dry ? "preview — nothing written; re-run with --apply" : "applied"}`, ""];
+  for (const s of scopes) out.push(...describe(applyScope(s, root, { dry }), { dry }), "");
+  if (scopes.includes("user")) out.push("~/.claude applies to every project on this machine.");
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+const isMain = () => {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+};
+if (process.argv[1] && isMain()) main(process.argv.slice(2));

package/plugins/agent-os/skills/init/scripts/state.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * agent-os setup state — is this a fresh setup, a repair, or already healthy?
+ *
+ * Both `npx agent-os init` and `/agent-os:init` start here, so neither
+ * re-scaffolds a project that is set up, and both name exactly what a repair
+ * has to touch. Read-only: every check is a file read, and the settings checks
+ * are dry runs of what settings.mjs would write.
+ *
+ * The plugin check reads Claude Code's own records (installed_plugins.json,
+ * enabledPlugins, the marketplace cache) instead of calling the `claude` CLI,
+ * so it also works from inside a session.
+ *
+ * Usage: node state.mjs [projectDir]
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { addTaskRule, GIT_DENY, mergeSettings, paths, userDir } from "./settings.mjs";
+
+export const PLUGIN_ID = "agent-os@sayan-plugins";
+export const MARKETPLACE_NAME = "sayan-plugins";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
+const real = (p) => { try { return realpathSync(p); } catch { return p; } };
+
+/** -1, 0, 1 for dotted numeric versions; unknown sorts lowest. */
+export function cmpVersion(a, b) {
+  const pa = String(a || "0").split(/[.-]/).map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || "0").split(/[.-]/).map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/** The version of the plugin this script ships in. */
+export const bundledVersion = () => readJson(join(HERE, "../../../.claude-plugin/plugin.json"))?.version || null;
+
+/**
+ * What Claude Code has installed for this project.
+ * { installed, scope, version, enabled, latest } — latest is the version in the
+ * local marketplace cache, which is only as new as the last marketplace update.
+ */
+export function pluginState(root) {
+  const home = userDir();
+  const rootReal = real(root);
+  const records = readJson(join(home, "plugins/installed_plugins.json"))?.plugins?.[PLUGIN_ID] || [];
+  // Project and local installs belong to one directory; user installs to all.
+  const mine = records.filter((r) => r.scope === "user" || (r.projectPath && real(r.projectPath) === rootReal));
+  const pick = mine.find((r) => r.scope === "project" || r.scope === "local") || mine[0] || null;
+
+  const enabledIn = [
+    join(root, ".claude/settings.local.json"),
+    join(root, ".claude/settings.json"),
+    join(home, "settings.json"),
+  ].map((p) => readJson(p)?.enabledPlugins?.[PLUGIN_ID]).find((v) => v !== undefined);
+
+  const latest = readJson(join(home, "plugins/marketplaces", MARKETPLACE_NAME, "plugins/agent-os/.claude-plugin/plugin.json"))?.version || null;
+  return {
+    installed: !!pick,
+    scope: pick?.scope || null,
+    version: pick?.version || null,
+    enabled: pick ? enabledIn !== false : false,
+    latest,
+  };
+}
+
+/**
+ * Every check, then the verdict:
+ *   fresh    nothing of agent-os is here yet — run the whole setup
+ *   repair   some of it is — fix only the items marked missing
+ *   healthy  all of it is
+ * `expect` is the plugin version the caller wants at minimum (the CLI passes
+ * the version it bundles).
+ */
+export function setupState(root, { expect = bundledVersion() } = {}) {
+  const items = [];
+  const add = (key, label, ok, fix) => items.push({ key, label, ok, fix });
+
+  const hasSource = existsSync(join(root, ".agent-os/config.json"));
+  const claudeMd = (() => { try { return readFileSync(join(root, "CLAUDE.md"), "utf8"); } catch { return null; } })();
+  const hasMemory = existsSync(join(root, ".claude/agent-memory"));
+
+  add("source", ".agent-os/ source", hasSource, "npx @sayansr26/agent-os init");
+  add("claude-md", "CLAUDE.md", claudeMd !== null, "/init in Claude Code, then /agent-os:init");
+
+  for (const scope of ["project", "user"]) {
+    const p = paths(scope, root);
+    const s = mergeSettings(p.settings, { dry: true });
+    const where = scope === "user" ? "~/.claude/settings.json" : ".claude/settings.json";
+    if (s.status === "invalid") { add(`${scope}-settings`, `${where} is valid JSON`, false, `fix ${where} by hand`); continue; }
+    const have = GIT_DENY.length - s.denyAdded.length;
+    add(`${scope}-git`, `${where} git write protection (${have}/${GIT_DENY.length})`, !s.denyAdded.length, `agent-os settings --scope ${scope} --apply`);
+    add(`${scope}-todo`, `${where} task tools`, s.env !== "added", `agent-os settings --scope ${scope} --apply`);
+  }
+  if (claudeMd !== null) {
+    add("task-rule", "CLAUDE.md task-tracking rule", addTaskRule(join(root, "CLAUDE.md"), { dry: true }).status === "present", "agent-os settings --scope project --apply");
+    add("agents-section", "CLAUDE.md says when to use each agent", /agent-os:(feature-cartographer|builder|reviewer)/.test(claudeMd), "/agent-os:init (establishing.md, Step 4b)");
+  }
+
+  const pl = pluginState(root);
+  const want = [expect, pl.latest].filter(Boolean).sort((a, b) => cmpVersion(b, a))[0] || null;
+  add("plugin", "Claude Code plugin installed", pl.installed, "npx @sayansr26/agent-os init");
+  if (pl.installed) {
+    add("plugin-enabled", "plugin enabled", pl.enabled, `claude plugin enable ${PLUGIN_ID}`);
+    add("plugin-version", `plugin version ${pl.version}${want && cmpVersion(pl.version, want) < 0 ? ` (latest ${want})` : ""}`,
+      !want || cmpVersion(pl.version, want) >= 0, "npx @sayansr26/agent-os init  (or /plugin update, then /reload-plugins)");
+  }
+
+  // Settings alone do not count: deny rules may be the user's own.
+  const anything = hasSource || hasMemory || pl.installed || /agent-os/.test(claudeMd || "");
+  const missing = items.filter((i) => !i.ok);
+  const status = !anything ? "fresh" : missing.length ? "repair" : "healthy";
+  return { status, items, missing, plugin: pl };
+}
+
+export function describeState(st) {
+  const lines = [`SETUP  ${st.status.toUpperCase()}${st.status === "repair" ? `  — ${st.missing.length} item(s) to fix` : ""}`];
+  for (const i of st.items) lines.push(`  ${i.ok ? "ok     " : "MISSING"} ${i.label}${i.ok ? "" : `  → ${i.fix}`}`);
+  return lines;
+}
+
+const isMain = () => {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+};
+if (process.argv[1] && isMain()) {
+  const root = process.argv[2] || process.cwd();
+  process.stdout.write(describeState(setupState(root)).join("\n") + "\n");
+}

package/src/claude-setup.mjs

@@ -0,0 +1,12 @@
+/**
+ * The Claude Code settings that are not rules and not the plugin: git write
+ * protection, the todo tools flag, and the task-tracking rule.
+ *
+ * The logic lives in the plugin (`skills/init/scripts/settings.mjs`) so that
+ * `/agent-os:init` inside Claude Code and `agent-os init` in a terminal write
+ * exactly the same thing. This module is the CLI's door to it.
+ */
+export {
+  TODO_ENV, TASK_RULE, GIT_DENY, userDir, paths,
+  mergeSettings, addTaskRule, applyScope, describe,
+} from "../plugins/agent-os/skills/init/scripts/settings.mjs";

package/src/cli.mjs

@@ -5,7 +5,10 @@ import { join } from "node:path";
 import { detect, summarise, TOOLS } from "./detect.mjs";
 import { load, write, readIfExists, matches, BANNER, DIR } from "./source.mjs";
 import { adopt } from "./adopt.mjs";
-import { installPlugin, MARKETPLACE, MARKETPLACE_NAME, PLUGIN } from "./plugin.mjs";
+import { ensurePlugin, MARKETPLACE_NAME, PLUGIN } from "./plugin.mjs";
+import { setupState, describeState } from "../plugins/agent-os/skills/init/scripts/state.mjs";
+import { applyScope, describe } from "./claude-setup.mjs";
+import { createInterface } from "node:readline/promises";
 import { compile, TARGETS } from "./targets.mjs";
 
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -14,12 +17,14 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const USAGE = `
 ${bold("agent-os")} — one source of truth for AI coding agent config
 
-  agent-os init      detect your tools, create .agent-os/, compile
+  agent-os init      set up a fresh project, or repair and update an existing one
   agent-os sync      recompile after editing .agent-os/
   agent-os check     verify nothing drifted (exit 1 if it has) — for CI
   agent-os detect    list which tools this project is set up for
   agent-os audit     inspect the project's context layer and report findings
   agent-os memory    inspect and health-check every memory store
+  agent-os settings  preview git write protection + task tools for Claude Code
+                     (--scope project|user|both, --apply to write)
 
   Without a global install, prefix any of these with
   ${dim("npx @sayansr26/agent-os")}
@@ -28,7 +33,9 @@ Options
   --root <dir>   project directory (default: cwd)
   --dry-run      print what would change, write nothing
   --force        overwrite files agent-os did not generate (it refuses by default)
-  --no-plugin    skip installing the Claude Code plugin during init
+  --no-plugin    skip installing or updating the Claude Code plugin during init
+  --global       init: also write ~/.claude settings without asking
+  --no-global    init: leave ~/.claude alone
 `;
 
 function scaffold(root, found) {
@@ -115,6 +122,13 @@ export async function main(argv) {
     return;
   }
 
+  if (cmd === "settings") {
+    const i = argv.indexOf("--scope");
+    runScript("plugins/agent-os/skills/init/scripts/settings.mjs",
+      ["--root", root, "--scope", i === -1 ? "both" : argv[i + 1], ...(argv.includes("--apply") ? ["--apply"] : [])]);
+    return;
+  }
+
   if (cmd === "memory") {
     runScript("plugins/agent-os/skills/memory/scripts/memory.mjs", argv.includes("--stale") ? [root, "--stale"] : [root]);
     return;
@@ -122,14 +136,28 @@ export async function main(argv) {
 
   let adopted = new Set();
 
+  let before = null;
   if (cmd === "init") {
     console.log(`\n${bold("agent-os init")}  ${root}\n`);
+    // Decide fresh vs repair before touching anything, and say which, so a
+    // second run on a set-up project reads as a repair rather than a re-init.
+    before = setupState(root);
+    for (const l of describeState(before)) console.log(`  ${l}`);
+    console.log({
+      fresh: `\n  ${dim("Fresh setup: creating everything.")}`,
+      repair: `\n  ${dim("Existing setup: fixing the items marked MISSING, leaving the rest as it is.")}`,
+      healthy: `\n  ${dim("Setup is complete: re-syncing and checking the plugin for updates.")}`,
+    }[before.status]);
+    console.log("");
     console.log(summarise(found));
+    const hadSource = existsSync(join(root, DIR));
     const { present, taken } = scaffold(root, found);
     adopted = taken.paths;
     if (taken.from.length) {
       console.log(`\n  adopted into ${DIR}/ ${dim("— your existing files are now the source")}`);
       for (const f of taken.from) console.log(`    ${f}`);
+    } else if (hadSource) {
+      console.log(`\n  kept ${DIR}/ ${dim("— already the source; nothing re-scaffolded")}`);
     } else {
       console.log(`\n  created ${DIR}/ ${dim("(config.json, AGENTS.md, rules/example.md)")}`);
     }
@@ -210,19 +238,56 @@ Pick one:
     // The rules are done and safe at this point. The Claude Code plugin is the
     // other half — agents, skills, per-agent memory, the session hook — and it
     // installs from the same repo. Only on `init`, never on `sync`.
+    if (cmd === "init" && targets.includes("claude-code")) {
+      console.log(`\n${bold("Claude Code setup")}\n`);
+
+      // Project scope always: it travels with the repo. User scope protects
+      // every other project on the machine too, so it is asked once rather
+      // than assumed — unless --global / --no-global already answered.
+      for (const l of describe(applyScope("project", root, { dry }), { dry })) console.log(`  ${l}`);
+
+      let global = argv.includes("--global") ? true : argv.includes("--no-global") ? false : null;
+      if (global === null && !dry && process.stdin.isTTY && process.stdout.isTTY) {
+        console.log("");
+        for (const l of describe(applyScope("user", root, { dry: true }), { dry: true })) console.log(`  ${l}`);
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const a = (await rl.question(`\n  Apply the same to ~/.claude (every project on this machine)? [Y/n] `)).trim().toLowerCase();
+        rl.close();
+        global = a === "" || a === "y" || a === "yes";
+      }
+      if (global) {
+        console.log("");
+        for (const l of describe(applyScope("user", root, { dry }), { dry })) console.log(`  ${l}`);
+      } else if (global === null) {
+        console.log(`\n  ${dim("~/.claude left alone (not a terminal). To protect every project:")}`);
+        console.log(`  ${dim("npx @sayansr26/agent-os settings --scope user --apply")}`);
+      }
+    }
+
     if (cmd === "init" && targets.includes("claude-code") && !argv.includes("--no-plugin")) {
       console.log(`\n${bold("Claude Code plugin")} ${dim(`${PLUGIN}@${MARKETPLACE_NAME}`)}\n`);
-      const r = installPlugin({ dry });
+      const r = ensurePlugin({ root, dry });
       for (const line of r.done) console.log(`  ${dim(line)}`);
-      if (r.ok && r.reason === "installed") {
-        console.log(`\n  installed at project scope ${dim("— .claude/settings.json, so it travels with the repo")}`);
-        console.log(`  ${dim("restart Claude Code, or /reload-plugins, then run /agent-os:init")}`);
-      } else if (!r.ok) {
-        console.log("");
-        for (const line of r.hint) console.log(`  ${line}`);
-      }
+      if (r.ok) console.log({
+        installed: `\n  installed ${r.to || ""} at project scope ${dim("— .claude/settings.json, so it travels with the repo")}`,
+        updated: `\n  updated ${r.from} → ${r.to}`,
+        current: `\n  already the latest (${r.to})`,
+        "dry-run": `\n  ${dim(r.from ? `installed: ${r.from} — would refresh and update` : "not installed — would install")}`,
+      }[r.reason]);
+      for (const line of r.hint) console.log(`  ${r.ok ? dim(line) : line}`);
+      if (r.reason === "installed" || r.reason === "updated")
+        console.log(`  ${dim("restart Claude Code, or /reload-plugins, to load it")}`);
       console.log(`\n  ${dim("--no-plugin skips this")}`);
     }
+
+    if (cmd === "init" && !dry) {
+      const after = setupState(root);
+      console.log(`\n${bold("Result")}  ${before.status} → ${after.status}`);
+      if (after.missing.length) {
+        console.log(dim("  still to do:"));
+        for (const i of after.missing) console.log(`    ${i.label}  → ${i.fix}`);
+      }
+    }
     console.log("");
     return;
   }

package/src/plugin.mjs

@@ -1,23 +1,37 @@
 /**
- * Install the Claude Code half of agent-os during `init`.
+ * Install or update the Claude Code half of agent-os during `init`.
  *
  * The CLI compiles rules for every tool. Claude Code additionally gets the
- * agents, skills, per-agent memory and session hook, which ship as a plugin —
- * so `init` should install it rather than printing two slash commands and
- * hoping. `claude plugin ...` with `--yes` is the documented automation path.
+ * agents, skills, per-agent memory and hooks, which ship as a plugin. `init`
+ * brings that plugin to the latest version whatever state it finds:
  *
- * Everything here is best effort and reversible: if the `claude` CLI is not on
- * PATH, or a command fails, `init` reports it and carries on. The rules are the
- * part that must not depend on this.
+ *   not installed        marketplace add + install, at project scope
+ *   installed, disabled  enable
+ *   installed            refresh the marketplace, then update
+ *
+ * An installed plugin is never left behind: Claude Code pins the cached
+ * version, so a project installed once stays on that version until something
+ * updates it — which is how a project ended up running 0.4.1 hooks.
+ *
+ * Every command runs with the project as its working directory, so project
+ * scope means *this* project even with --root. Best effort throughout: if the
+ * `claude` CLI is missing or a command fails, `init` reports it and carries
+ * on. The rules are the part that must not depend on this.
  */
 import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { bundledVersion, cmpVersion } from "../plugins/agent-os/skills/init/scripts/state.mjs";
 
 export const MARKETPLACE = "sayansr26/agent-os";
 export const MARKETPLACE_NAME = "sayan-plugins";
 export const PLUGIN = "agent-os";
+const ID = `${PLUGIN}@${MARKETPLACE_NAME}`;
 
-const run = (args) =>
-  spawnSync("claude", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+const run = (args, cwd) =>
+  spawnSync("claude", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
+const json = (r) => { try { return JSON.parse(r.stdout); } catch { return null; } };
+const real = (p) => { try { return realpathSync(p); } catch { return p; } };
+const tail = (r) => (r.stderr || r.stdout || String(r.error || "")).trim().split("\n").slice(-3);
 
 /** Is the Claude Code CLI usable from here? */
 export function claudeAvailable() {
@@ -25,50 +39,77 @@ export function claudeAvailable() {
   return !r.error && r.status === 0;
 }
 
+/** This project's install of the plugin, per `claude plugin list --json`, or null. */
+export function installed(root) {
+  const list = json(run(["plugin", "list", "--json"], root));
+  if (!Array.isArray(list)) return null;
+  const mine = list.filter((p) => p.id === ID &&
+    (p.scope === "user" || (p.projectPath && real(p.projectPath) === real(root))));
+  return mine.find((p) => p.scope === "project" || p.scope === "local") || mine[0] || null;
+}
+
 /**
- * Add the marketplace and install the plugin at project scope, so the setup
- * travels with the repository instead of living on one machine.
+ * Bring the plugin to the latest version for this project.
+ * Returns { ok, reason, from, to, done, hint } with reason one of
+ * "installed" | "updated" | "current" | "dry-run" | "no-cli" | "failed".
  */
-export function installPlugin({ dry = false, scope = "project" } = {}) {
-  const steps = [
-    ["marketplace", ["plugin", "marketplace", "add", MARKETPLACE, "--scope", scope]],
-    ["plugin", ["plugin", "install", `${PLUGIN}@${MARKETPLACE_NAME}`, "--scope", scope, "--yes"]],
-  ];
-
+export function ensurePlugin({ root = process.cwd(), dry = false, scope = "project" } = {}) {
   if (!claudeAvailable())
     return {
-      ok: false,
-      reason: "no-cli",
-      done: [],
+      ok: false, reason: "no-cli", done: [],
       hint: [
-        "The `claude` CLI is not on PATH, so the plugin was not installed.",
+        "The `claude` CLI is not on PATH, so the plugin was not installed or updated.",
         "Inside Claude Code, run:",
         `  /plugin marketplace add ${MARKETPLACE}`,
-        `  /plugin install ${PLUGIN}@${MARKETPLACE_NAME}`,
+        `  /plugin install ${ID}     (or /plugin update ${ID} if it is already there)`,
       ],
     };
 
+  const before = installed(root);
+  const markets = json(run(["plugin", "marketplace", "list", "--json"], root));
+  const haveMarket = Array.isArray(markets) && markets.some((m) => m.name === MARKETPLACE_NAME);
+
+  const steps = [];
+  steps.push(haveMarket
+    ? ["plugin", "marketplace", "update", MARKETPLACE_NAME]
+    : ["plugin", "marketplace", "add", MARKETPLACE, "--scope", scope]);
+  if (!before) steps.push(["plugin", "install", ID, "--scope", scope, "--yes"]);
+  else {
+    if (before.enabled === false) steps.push(["plugin", "enable", ID, "--scope", before.scope]);
+    steps.push(["plugin", "update", ID, "--scope", before.scope, "--yes"]);
+  }
+
   if (dry)
-    return { ok: true, reason: "dry-run", done: steps.map(([, a]) => `claude ${a.join(" ")}`), hint: [] };
+    return { ok: true, reason: "dry-run", from: before?.version || null, done: steps.map((a) => `claude ${a.join(" ")}`), hint: [] };
 
   const done = [];
-  for (const [what, args] of steps) {
-    const r = run(args);
+  for (const args of steps) {
+    const r = run(args, root);
     if (r.status !== 0) {
-      const err = (r.stderr || r.stdout || "").trim().split("\n").slice(-3).join("\n");
       return {
-        ok: false,
-        reason: what,
-        done,
+        ok: false, reason: "failed", from: before?.version || null, done,
         hint: [
           `\`claude ${args.join(" ")}\` failed:`,
-          ...err.split("\n").map((l) => `  ${l}`),
-          "The rules above were still written. Install the plugin by hand inside",
-          `Claude Code: /plugin install ${PLUGIN}@${MARKETPLACE_NAME}`,
+          ...tail(r).map((l) => `  ${l}`),
+          "The rules and settings above were still written. Inside Claude Code:",
+          before ? `  /plugin update ${ID}, then /reload-plugins` : `  /plugin install ${ID}`,
         ],
       };
     }
     done.push(`claude ${args.join(" ")}`);
   }
-  return { ok: true, reason: "installed", done, hint: [] };
+
+  const after = installed(root);
+  const to = after?.version || null;
+  const from = before?.version || null;
+  const want = bundledVersion();
+  const hint = [];
+  // The marketplace serves what is pushed to GitHub; this package may be newer.
+  if (to && want && cmpVersion(to, want) < 0)
+    hint.push(`Marketplace still serves ${to}; this agent-os ships ${want}. It updates once ${MARKETPLACE} is pushed.`);
+  return {
+    ok: true,
+    reason: !before ? "installed" : from !== to ? "updated" : "current",
+    from, to, done, hint,
+  };
 }