@ccoalm/ccl-skills 0.18.7 → 0.18.8

package/README.md

@@ -60,7 +60,7 @@ ccl-skills uninstall         # preview
 ccl-skills uninstall --yes   # remove host assets
 ```
 
-Limit any operation to one host with `--host claude`, `--host codex`, or `--host opencode`. Add `--json` for machine-readable output.
+Limit these operations to one host with `--host claude`, `--host codex`, or `--host opencode`. Add `--json` for machine-readable output.
 
 For `--host codex`, unreadable public plugin state returns exit `3` with `host-state-unknown`; a missing CLI or failed capability probe returns `4`. If that host failure occurs with a pending journal, recovery is deferred: exit `5` with `partial-journal` retains the journal and records `details.hostFailure`. Restore the CLI or readable public plugin state, then rerun the command. Other outcomes can share these exit codes, so inspect the JSON status as well.
 
@@ -70,9 +70,76 @@ Codex `doctor` also reads the native hook inventory. When every expected package
 
 After `ccl-skills uninstall --yes`, remove the CLI package itself with `npm uninstall --global @ccoalm/ccl-skills` if it is no longer needed.
 
+## Automatic CCL updates
+
+On macOS, explicitly enable daily CCL updates for one host:
+
+```bash
+# Existing Codex Git plugin; Codex is the default host
+npx --yes @ccoalm/ccl-skills@latest auto-update enable
+npx --yes @ccoalm/ccl-skills@latest auto-update status --json
+npx --yes @ccoalm/ccl-skills@latest auto-update disable
+
+# Existing npm-managed OpenCode skills, plugin and hooks
+npx --yes @ccoalm/ccl-skills@latest auto-update enable --host opencode
+npx --yes @ccoalm/ccl-skills@latest auto-update status --host opencode --json
+npx --yes @ccoalm/ccl-skills@latest auto-update disable --host opencode
+```
+
+With the CLI installed globally, replace `npx --yes @ccoalm/ccl-skills@latest` with `ccl-skills`. Each command acts on one host and executes directly; `--yes` and `--host all` are unsupported. Installation never enables scheduling. Separate launchd jobs run every 24 hours while logged in and when loaded at login. A non-root macOS user is required; other platforms return exit `4` with `unsupported-platform`.
+
+### Codex
+
+The target is `ccl-skills@ccl-skills` in the current `CODEX_HOME`, or `~/.codex` when unset. Its marketplace and plugin must use the canonical `ccoalm/ccl-skills` Git repository over HTTPS or SSH, and the plugin must be enabled. Codex must support `--no-daemon` and plugin JSON output.
+
+Each run checks public plugin state before and between these steps:
+
+```bash
+codex --no-daemon plugin marketplace upgrade ccl-skills
+codex --no-daemon plugin add ccl-skills@ccl-skills
+```
+
+An unsuccessful upgrade prevents the add step. Each update command has a two-minute limit; timeout terminates its child process group. Source changes are checked at those boundaries; Codex does not provide an atomic compare-and-update operation. Restart Codex to load changes. Hook trust follows Codex's normal policy.
+
+Codex npm installations use a local snapshot under `ccl-skills-npm`, which this scheduler refuses. Keep those current with `ccl-skills update --yes`. To migrate, preview removal with `ccl-skills uninstall --host codex`, then repeat with `--yes`. Register the Git installation explicitly:
+
+```bash
+codex --no-daemon plugin marketplace add https://github.com/ccoalm/ccl-skills.git
+codex --no-daemon plugin add ccl-skills@ccl-skills
+npx --yes @ccoalm/ccl-skills@latest auto-update enable
+```
+
+### OpenCode
+
+OpenCode requires an existing healthy npm-managed CCL installation with bundled assets. The scheduler updates only its CCL skills, native plugin and hook runtime under `~/.config/opencode`. It preserves OpenCode itself, application configuration, authentication, unrelated files and `~/.agents`. Restart OpenCode to load changes.
+
+Each run downloads `@ccoalm/ccl-skills@latest` from the public npm registry into a fresh private directory. It disables lifecycle scripts and package self-update, validates package identity, then invokes the fetched CLI's OpenCode doctor and update commands. It refuses missing installations, source overrides and locally changed managed files. A newer installed version is retained. Success requires a healthy receipt matching the fetched package version and bundled source.
+
+Source-checkout installs are unsupported. To migrate, first back up their CCL files and receipt, move only those verified CCL-owned files out of OpenCode's shared directories, then explicitly run the npm installer:
+
+```bash
+npx --yes @ccoalm/ccl-skills@latest install --host opencode
+npx --yes @ccoalm/ccl-skills@latest doctor --host opencode
+npx --yes @ccoalm/ccl-skills@latest auto-update enable --host opencode
+```
+
+The scheduler never adopts or deletes a source-copy installation. Resolve any collision or drift reported by the installer before enabling it.
+
+Package download has a three-minute limit; asset update has a two-minute limit. Cancellation sends SIGINT and allows ten seconds for rollback before forcing termination. A forced termination reports unknown finality; inspect `doctor --host opencode` before retrying. Fetch and preflight failures leave installed assets intact.
+
+### Status and recovery
+
+State lives in `$CODEX_HOME/ccl-skills-auto-update` for Codex and `~/.config/opencode/ccl-skills-auto-update` for OpenCode. Each profile has its own file in `~/Library/LaunchAgents`. The saved runner survives removal of an npx download and keeps the executable paths and profile selected at enable time. Those executables must remain installed. Re-enabling retains the saved runner; upgrading the npm CLI does not replace it.
+
+Commands receive fixed HOME/PATH plus CODEX_HOME and `GIT_TERMINAL_PROMPT=0` for Codex, or the self-update/notifier opt-outs for OpenCode. npm uses private empty config files and cache. Credentials and source/registry overrides from the enabling shell are not persisted; macOS may add runtime variables.
+
+`status` checks live registration and the latest bounded `last-run.json` record, which excludes raw command output. Failed or interrupted runs, registration errors and ownership errors return exit `5`. Restore the reported dependency and retry `enable` or `disable`. Overlapping runs are skipped. `disable` removes only that host's owned schedule and retains its runner, state and log. Disable first if removing the CLI should also stop updates.
+
+SIGINT and SIGTERM release owned locks, including between commands. A crash or forced kill can leave a `run.lock` or `manage.lock`. A lock at least 15 minutes old, or dated at least 15 minutes into the future, reports failure even if its PID is alive. The scheduler never removes these locks automatically. Inspect the recorded PID and launchd job; remove only that lock after confirming no updater owns it. Never remove a running updater's lock.
+
 ## Update notice
 
-Nothing here updates itself. An interactive run prints a one-line notice on **stderr** when a newer version exists, at most once a day per version:
+The npm package does not update itself automatically. An interactive run prints a one-line notice on **stderr** when a newer version exists, at most once a day per version:
 
 ```
 Update available: 0.2.0 -> 0.3.0

package/dist/assets/release.json

@@ -1,8 +1,8 @@
 {
   "schema": 1,
   "npmPackage": "@ccoalm/ccl-skills",
-  "version": "0.18.7",
-  "sourceCommit": "dcdc9ba9c54f708348dbfc46fb4964ec8d452001",
+  "version": "0.18.8",
+  "sourceCommit": "32941fa8b6a3d9d98779f18802dea0c21d3b61ff",
   "sourceState": "clean",
   "files": [
     {
@@ -3352,6 +3352,16 @@
     }
   ],
   "runtime": [
+    {
+      "path": "auto-update.d.ts",
+      "sha256": "980512a33d96d431e4ddfa3eae73e1921cd7353c6edcd0590aba38cf3fd9c8fc",
+      "mode": 420
+    },
+    {
+      "path": "auto-update.js",
+      "sha256": "a77be76bb68c1281d9ad046add1b2f3713337001754fd6339792c7fb0550122a",
+      "mode": 420
+    },
     {
       "path": "claude-adapter.d.ts",
       "sha256": "c4a33e6f04af043351174c4df0b2f66a0f76300a82d16598ae7fb4767fe11b8f",
@@ -3374,12 +3384,12 @@
     },
     {
       "path": "cli.d.ts",
-      "sha256": "1d7fe97a500b56e7d8c18f1cd38fbd946828506cf53ba64bc9582d1d58831469",
+      "sha256": "8cad36e2eba4bd3d62ab660050bca95dc3b2c204dd791e18a1bf0c82531985a2",
       "mode": 420
     },
     {
       "path": "cli.js",
-      "sha256": "5b5ab7f39b7faa81ea209b3e479295da64f2a834969ee5ac8d76354a182c2822",
+      "sha256": "eeebfd87d3b83885e683698e10596d8fc8b3a25e6b6ddf609cbf8e8e00506373",
       "mode": 493
     },
     {
@@ -3449,7 +3459,7 @@
     },
     {
       "path": "opencode-adapter.js",
-      "sha256": "213ee1d313a8318617f3865ca261718830c497f9de79ec35f7523bd100ad9c95",
+      "sha256": "b2eb03764adb252924d355281bffa8532f6add36d06cb2a6b907b4406b4e4c13",
       "mode": 420
     },
     {
@@ -3523,5 +3533,5 @@
       "mode": 420
     }
   ],
-  "snapshotHash": "ba46e55d708e08e62b84b47d83c333b50a91b1ea66c25a01c9b8430689cf3e3f"
+  "snapshotHash": "9f8142a50f984550552470abdd4c051e69831d649394c5fce0e70da6d59fff8f"
 }

package/dist/auto-update.d.ts

@@ -0,0 +1,26 @@
+import type { Result } from "./types.js";
+export type AutoUpdateAction = "enable" | "disable" | "status";
+export interface CommandResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    failure?: string;
+}
+export interface CommandOptions {
+    cwd?: string;
+    graceful?: boolean;
+}
+export type Command = (file: string, args: string[], env: NodeJS.ProcessEnv, timeout: number, options?: CommandOptions) => Promise<CommandResult>;
+export type AutoUpdateHost = "codex" | "opencode";
+export interface AutoUpdateDeps {
+    host?: AutoUpdateHost;
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+    command?: Command;
+    node?: string;
+}
+/** Kill the owned process group on timeout/cancellation, including Git children.
+ * Output is bounded and never persisted: child diagnostics can contain secrets. */
+export declare const runCommand: Command;
+export declare function autoUpdate(action: AutoUpdateAction, deps?: AutoUpdateDeps): Promise<Result>;
+export declare function runScheduled(env?: NodeJS.ProcessEnv, execute?: Command, host?: AutoUpdateHost): Promise<Result>;

package/dist/auto-update.js

@@ -0,0 +1,551 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, rmSync, openSync, closeSync, fsyncSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const OWNER = "ccl-skills-auto-update-v1";
+const SOURCES = new Set(["https://github.com/ccoalm/ccl-skills.git", "git@github.com:ccoalm/ccl-skills.git", "ssh://git@github.com/ccoalm/ccl-skills.git"]);
+const REF = "ccl-skills@ccl-skills";
+const LAUNCHCTL = "/bin/launchctl";
+const MAX_LOCK_AGE_MS = 15 * 60 * 1000;
+const digest = (text) => createHash("sha256").update(text).digest("hex");
+const clean = (value) => value.length > 0 && !/[\x00-\x1f\x7f]/.test(value);
+/** Kill the owned process group on timeout/cancellation, including Git children.
+ * Output is bounded and never persisted: child diagnostics can contain secrets. */
+export const runCommand = (file, args, env, timeout, options = {}) => new Promise((done) => {
+    const child = spawn(file, args, { env, cwd: options.cwd, stdio: ["ignore", "pipe", "pipe"], detached: true });
+    const stdout = [], stderr = [];
+    let stdoutBytes = 0, stderrBytes = 0, failure;
+    let grace;
+    const signalGroup = (signal) => {
+        if (child.pid) {
+            try {
+                process.kill(-child.pid, signal);
+            }
+            catch {
+                child.kill(signal);
+            }
+        }
+    };
+    const kill = (reason) => {
+        if (failure)
+            return;
+        failure = reason;
+        if (options.graceful) {
+            signalGroup("SIGINT");
+            grace = setTimeout(() => { failure = `${reason}-forced-finality-unknown`; signalGroup("SIGKILL"); }, 10000);
+        }
+        else
+            signalGroup("SIGKILL");
+    };
+    const interrupt = () => kill("interrupted");
+    process.once("SIGINT", interrupt);
+    process.once("SIGTERM", interrupt);
+    const timer = setTimeout(() => kill("timeout"), timeout);
+    child.stdout.on("data", (chunk) => {
+        if (stdoutBytes + chunk.length > 4 * 1024 * 1024) {
+            kill("output-limit");
+            return;
+        }
+        stdoutBytes += chunk.length;
+        stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+        if (stderrBytes + chunk.length > 64 * 1024) {
+            kill("output-limit");
+            return;
+        }
+        stderrBytes += chunk.length;
+        stderr.push(chunk);
+    });
+    child.on("error", () => { failure ||= "unavailable"; });
+    child.on("close", (code) => {
+        clearTimeout(timer);
+        if (grace)
+            clearTimeout(grace);
+        process.removeListener("SIGINT", interrupt);
+        process.removeListener("SIGTERM", interrupt);
+        done({ code, stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString(), ...(failure ? { failure } : {}) });
+    });
+});
+// Child cancellation belongs to runCommand; this scope also covers the gaps
+// between children and keeps repeated signals from bypassing owned cleanup.
+function interruptionScope(execute) {
+    let interrupted = false;
+    const interrupt = () => { interrupted = true; };
+    const check = () => {
+        if (interrupted)
+            throw new Error("Automatic-update operation interrupted; inspect host state before retrying");
+    };
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", interrupt);
+    const command = async (...args) => {
+        check();
+        const result = await execute(...args);
+        // Promise continuations can outrun queued signal callbacks. Yield to the
+        // event loop before accepting a result or starting another command.
+        await new Promise(resolve => setImmediate(resolve));
+        // Preserve child failures, including forced termination's unknown finality.
+        if (!result.failure)
+            check();
+        return result;
+    };
+    return { command, dispose: () => {
+            process.removeListener("SIGINT", interrupt);
+            process.removeListener("SIGTERM", interrupt);
+        } };
+}
+function owned(path, directory = false) {
+    try {
+        const s = lstatSync(path);
+        if (s.isSymbolicLink() || (directory ? !s.isDirectory() : !s.isFile() || s.nlink !== 1) || s.uid !== process.getuid?.() || (s.mode & 0o022))
+            throw new Error(`Unsafe ownership or file type: ${path}`);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function directory(path) {
+    if (owned(path, true))
+        return;
+    directory(dirname(path));
+    mkdirSync(path, { mode: 0o700 });
+}
+function atomic(path, contents) {
+    owned(dirname(path), true);
+    owned(path);
+    const temp = `${path}.${randomUUID()}.tmp`;
+    const fd = openSync(temp, "wx", 0o600);
+    try {
+        try {
+            writeFileSync(fd, contents);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        owned(path);
+        renameSync(temp, path);
+    }
+    finally {
+        if (existsSync(temp))
+            unlinkSync(temp);
+    }
+}
+function context(env, host = "codex") {
+    if (host !== "codex" && host !== "opencode")
+        throw new Error("Unsupported auto-update host");
+    if (!env.HOME || !isAbsolute(env.HOME) || !clean(env.HOME))
+        throw new Error("HOME must be an existing absolute directory");
+    const home = realpathSync(env.HOME), profileInput = host === "codex" ? env.CODEX_HOME || join(home, ".codex") : join(home, ".config", "opencode");
+    if (!isAbsolute(profileInput) || !clean(profileInput))
+        throw new Error("Host profile must be an existing absolute directory");
+    if (!existsSync(profileInput))
+        throw new Error(`${host} profile is absent; install CCL for this host before enabling automatic updates`);
+    const profile = realpathSync(profileInput), uid = process.getuid?.();
+    if (!clean(home) || !clean(profile))
+        throw new Error("Canonical HOME and host profile paths must not contain control characters");
+    if (uid === undefined || uid === 0)
+        throw new Error("Automatic updates require a non-root user");
+    owned(home, true);
+    owned(profile, true);
+    owned(join(home, "Library"), true);
+    owned(join(home, "Library", "LaunchAgents"), true);
+    const root = join(profile, "ccl-skills-auto-update"), label = `com.ccoalm.ccl-skills.${host}.${digest(profile).slice(0, 16)}`;
+    return { host, home, profile, uid, root, label, plist: join(home, "Library", "LaunchAgents", `${label}.plist`), runner: join(root, "runner.mjs"), config: join(root, "state.json"), log: join(root, "last-run.json") };
+}
+function readState(c) {
+    if (!owned(c.root, true))
+        return null;
+    if (!owned(c.config))
+        throw new Error("Automatic-update directory has no ownership record; leave it intact and inspect it manually");
+    const s = JSON.parse(readFileSync(c.config, "utf8"));
+    const keys = ["host", ...(c.host === "opencode" ? ["npm"] : []), "owner", "schema", "home", "profile", "uid", "label", "node", "binary", "path", "runnerHash", "enabled"];
+    if (Object.keys(s).sort().join() !== keys.sort().join() || s.host !== c.host || s.owner !== OWNER || s.schema !== 1 || s.home !== c.home || s.profile !== c.profile || s.uid !== c.uid || s.label !== c.label || typeof s.enabled !== "boolean" || !/^[a-f0-9]{64}$/.test(s.runnerHash) || ![s.node, s.binary, s.path].every(v => typeof v === "string" && clean(v)) || !isAbsolute(s.node) || !isAbsolute(s.binary) || !s.path.split(":").every(isAbsolute) || (c.host === "opencode" && (typeof s.npm !== "string" || !clean(s.npm) || !isAbsolute(s.npm))))
+        throw new Error("Invalid automatic-update ownership record; no files were changed");
+    return s;
+}
+function executable(name, path) {
+    for (const dir of path.split(":")) {
+        const file = join(dir, name);
+        try {
+            accessSync(file, constants.X_OK);
+            if (lstatSync(realpathSync(file)).isFile())
+                return file;
+        }
+        catch { /* try the next PATH entry */ }
+    }
+    throw new Error(`${name} executable unavailable; install it and rerun auto-update enable`);
+}
+const runtimeEnv = (s) => s.host === "codex" ? { HOME: s.home, CODEX_HOME: s.profile, PATH: s.path, GIT_TERMINAL_PROMPT: "0" } : { HOME: s.home, PATH: s.path, CCL_SKILLS_SKIP_SELF_UPDATE: "1", CCL_SKILLS_NO_UPDATE_NOTIFIER: "1" };
+const xml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+function plist(c, s) {
+    const string = (v) => `<string>${xml(v)}</string>`;
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key>${string(c.label)}\n<key>ProgramArguments</key><array>${[s.node, c.runner, "--run", s.host].map(string).join("")}</array>\n<key>EnvironmentVariables</key><dict>${Object.entries(runtimeEnv(s)).map(([k, v]) => `<key>${k}</key>${string(v)}`).join("")}</dict>\n<key>ExitTimeOut</key><integer>30</integer>\n<key>StartInterval</key><integer>86400</integer>\n<key>RunAtLoad</key><true/>\n<key>WorkingDirectory</key>${string(c.home)}\n<key>StandardOutPath</key><string>/dev/null</string>\n<key>StandardErrorPath</key><string>/dev/null</string>\n</dict></plist>\n`;
+}
+function verifyFiles(c, s) {
+    if (owned(c.runner) && digest(readFileSync(c.runner, "utf8")) !== s.runnerHash)
+        throw new Error("Automatic-update runner changed; refusing to replace it");
+    if (owned(c.plist) && readFileSync(c.plist, "utf8") !== plist(c, s))
+        throw new Error("Schedule is not the owned automatic-update job; refusing to change it");
+}
+async function registration(c, s, command) {
+    const r = await command(LAUNCHCTL, ["print", `gui/${c.uid}/${c.label}`], runtimeEnv(s), 10000);
+    if (r.failure)
+        throw new Error(`launchctl inspection failed (${r.failure}); registration is unknown`);
+    if (r.code !== 0) {
+        if (/Could not find service|service could not be found/i.test(r.stderr))
+            return { registered: false };
+        throw new Error("launchctl inspection failed; registration is unknown. Run from your logged-in macOS session");
+    }
+    const match = r.stdout.match(/^\s*path = (.+)$/m);
+    if (!match || match[1] !== c.plist)
+        throw new Error("A foreign launchd job uses this label; no scheduling changes made");
+    const exit = r.stdout.match(/^\s*last exit code = (\d+)/m);
+    return { registered: true, running: /^\s*state = running\s*$/m.test(r.stdout), ...(exit ? { lastExit: Number(exit[1]) } : {}) };
+}
+async function validateCodex(s, command) {
+    const query = async (args) => {
+        const r = await command(s.binary, ["--no-daemon", "plugin", ...args, "--json"], runtimeEnv(s), 10000);
+        if (r.failure || r.code !== 0)
+            throw new Error("Codex public JSON query failed; install a Codex CLI supporting --no-daemon and plugin JSON queries, then retry");
+        try {
+            return JSON.parse(r.stdout);
+        }
+        catch {
+            throw new Error("Codex returned invalid JSON; plugin source is unknown");
+        }
+    };
+    const markets = await query(["marketplace", "list"]);
+    if (!Array.isArray(markets.marketplaces))
+        throw new Error("Codex marketplace state is unknown");
+    const matches = markets.marketplaces.filter((m) => m.name === "ccl-skills");
+    if (matches.length !== 1)
+        throw new Error("Requires an existing Git marketplace named ccl-skills. npm snapshots are not supported; use ccl-skills update --yes for npm-managed installs");
+    const source = matches[0].marketplaceSource;
+    if (source?.sourceType !== "git" || !SOURCES.has(source.source))
+        throw new Error("Requires the canonical ccl-skills Git marketplace. npm/local snapshots cannot auto-update; use ccl-skills update --yes or explicitly migrate to the Git install described in the README");
+    const plugins = await query(["list", "--marketplace", "ccl-skills"]);
+    if (!Array.isArray(plugins.installed))
+        throw new Error("Codex installed plugin state is unknown");
+    const installed = plugins.installed.filter((p) => p.pluginId === REF);
+    if (installed.length !== 1 || installed[0].installed !== true || installed[0].enabled !== true || installed[0].marketplaceName !== "ccl-skills" || installed[0].source?.source !== "git" || !SOURCES.has(installed[0].source?.url) || installed[0].marketplaceSource?.sourceType !== "git" || !SOURCES.has(installed[0].marketplaceSource?.source))
+        throw new Error("ccl-skills@ccl-skills must be installed and enabled from the canonical Git marketplace before enabling updates");
+}
+const PACKAGE = "@ccoalm/ccl-skills";
+const REGISTRY = "https://registry.npmjs.org/";
+const stableVersion = (value) => typeof value === "string" && /^\d+\.\d+\.\d+$/.test(value);
+function compareVersions(left, right) {
+    const a = left.split(".").map(BigInt), b = right.split(".").map(BigInt);
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return a[i] > b[i] ? 1 : -1;
+    return 0;
+}
+async function packageCommand(s, cli, action, command, cwd = s.home) {
+    const args = [cli, action, "--host", "opencode", ...(action === "update" ? ["--yes"] : []), "--json"];
+    const result = await command(s.node, args, runtimeEnv(s), action === "update" ? 120000 : 30000, { cwd, graceful: action === "update" });
+    if (result.failure)
+        throw new Error(`OpenCode ${action} ${result.failure}; inspect installed assets before retrying`);
+    let value;
+    try {
+        value = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new Error(`OpenCode ${action} returned invalid JSON; finality is unknown`);
+    }
+    if (!value || typeof value !== "object" || ![0, 1, 2, 3, 4, 5, 130].includes(value.code) || result.code !== value.code || typeof value.message !== "string" || typeof value.status !== "string" || !/^[a-z-]+$/.test(value.status))
+        throw new Error(`OpenCode ${action} returned an invalid result; finality is unknown`);
+    return value;
+}
+function healthyOpenCode(result, expected) {
+    if (result.code !== 0 || result.status !== "healthy" || result.details?.sourceKind !== "bundled" || !stableVersion(result.details?.version))
+        throw new Error(`OpenCode requires a healthy npm-managed bundled CCL installation (${result.status}). Repair drift first; for source-copy installs, back up the existing CCL files and explicitly migrate with the npm installer before enabling updates`);
+    if (expected && result.details.version !== expected)
+        throw new Error("OpenCode post-update version does not match the fetched package; finality is unknown");
+    return result.details.version;
+}
+async function validateInstallation(s, command) {
+    if (s.host === "codex")
+        return validateCodex(s, command);
+    const cli = fileURLToPath(new URL("./cli.js", import.meta.url));
+    healthyOpenCode(await packageCommand(s, cli, "doctor", command));
+}
+function jsonFile(path) {
+    if (!owned(path) || lstatSync(path).size > 1024 * 1024)
+        throw new Error("Fetched package metadata is missing or oversized");
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function verifyPrivateTree(root) {
+    owned(root, true);
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            verifyPrivateTree(path);
+        else
+            owned(path);
+    }
+}
+async function updateOpenCode(c, s, command) {
+    const pending = mkdtempSync(join(c.root, "refresh-"));
+    try {
+        const prefix = join(pending, "package"), cache = join(pending, "cache");
+        directory(prefix);
+        directory(cache);
+        const userConfig = join(pending, "user.npmrc"), globalConfig = join(pending, "global.npmrc");
+        atomic(userConfig, "");
+        atomic(globalConfig, "");
+        atomic(join(prefix, "package.json"), JSON.stringify({ private: true }));
+        const result = await command(s.npm, ["install", "--prefix", prefix, "--registry", REGISTRY, "--userconfig", userConfig, "--globalconfig", globalConfig, "--cache", cache, "--ignore-scripts", "--no-bin-links", "--no-audit", "--no-fund", "--package-lock=false", `${PACKAGE}@latest`], runtimeEnv(s), 180000, { cwd: prefix });
+        if (result.failure || result.code !== 0)
+            throw new Error(`OpenCode package refresh failed (${result.failure || `exit ${result.code}`}); installed assets were not changed`);
+        verifyPrivateTree(prefix);
+        const packageRoot = join(prefix, "node_modules", "@ccoalm", "ccl-skills"), pkg = jsonFile(join(packageRoot, "package.json")), release = jsonFile(join(packageRoot, "dist", "assets", "release.json"));
+        if (pkg.name !== PACKAGE || !stableVersion(pkg.version) || pkg.type !== "module" || pkg.bin?.["ccl-skills"] !== "dist/cli.js" || release.npmPackage !== PACKAGE || release.version !== pkg.version)
+            throw new Error("Fetched OpenCode package identity is invalid; installed assets were not changed");
+        const cli = join(packageRoot, "dist", "cli.js");
+        if (!owned(cli))
+            throw new Error("Fetched package CLI is missing");
+        const current = healthyOpenCode(await packageCommand(s, cli, "doctor", command, prefix));
+        if (compareVersions(pkg.version, current) < 0)
+            return `OpenCode retains newer installed CCL ${current}; registry latest is ${pkg.version}`;
+        if (!readState(c)?.enabled)
+            throw new Error("Schedule was disabled; OpenCode assets were not changed");
+        const updated = await packageCommand(s, cli, "update", command, prefix);
+        if (updated.code !== 0 || !["updated", "healthy"].includes(updated.status))
+            throw new Error(`OpenCode update returned ${updated.status}; inspect installed assets before retrying`);
+        healthyOpenCode(await packageCommand(s, cli, "doctor", command, prefix), pkg.version);
+        return `OpenCode CCL assets updated to ${pkg.version}; restart OpenCode to load changes`;
+    }
+    finally {
+        // Only this invocation's exclusive, freshly created prefix is removed.
+        owned(c.root, true);
+        owned(pending, true);
+        rmSync(pending, { recursive: true, force: true });
+    }
+}
+function lastRun(c) {
+    if (!owned(c.log))
+        return null;
+    const text = readFileSync(c.log, "utf8");
+    if (text.length > 16384)
+        throw new Error("Automatic-update run record exceeds its size limit");
+    const record = JSON.parse(text);
+    if (!record || record.owner !== OWNER || !["running", "success", "failed"].includes(record.status) || typeof record.message !== "string" || typeof record.finishedAt !== "string")
+        throw new Error("Invalid automatic-update run record; inspect the log before retrying");
+    return record;
+}
+function lockState(path) {
+    if (!owned(path))
+        return "absent";
+    const pid = Number(readFileSync(path, "utf8"));
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        throw new Error(`Invalid automatic-update lock: ${path}; inspect it manually`);
+    // PID liveness cannot establish process identity after a crash and reuse.
+    // A bounded age prevents indefinite healthy overlap; never reclaim the lock.
+    if (Math.abs(Date.now() - lstatSync(path).mtimeMs) >= MAX_LOCK_AGE_MS)
+        return "uncertain";
+    try {
+        process.kill(pid, 0);
+        return "active";
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return "stale";
+        throw error;
+    }
+}
+function lock(c, name = "run.lock") {
+    const path = join(c.root, name), state = lockState(path);
+    if (state === "stale")
+        throw new Error(`Stale automatic-update lock: ${path}. Confirm its PID has exited, remove only this lock file, then retry`);
+    if (state === "uncertain")
+        throw new Error(`Automatic-update lock is older than 15 minutes or its timestamp is uncertain: ${path}. Inspect the PID and job; remove only this lock after confirming no updater owns it`);
+    if (state === "active")
+        throw new Error("Automatic-update operation already running; retry after it finishes");
+    try {
+        const fd = openSync(path, "wx", 0o600);
+        try {
+            writeFileSync(fd, String(process.pid));
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new Error("Automatic-update operation already running; retry after it finishes");
+        throw error;
+    }
+    return () => { if (owned(path) && readFileSync(path, "utf8") === String(process.pid))
+        unlinkSync(path); };
+}
+export async function autoUpdate(action, deps = {}) {
+    if ((deps.platform || process.platform) !== "darwin")
+        return { code: 4, status: "unsupported-platform", message: "Automatic updates currently require macOS launchd. Use the documented manual update commands on other platforms." };
+    const env = deps.env || process.env;
+    const scope = interruptionScope(deps.command || runCommand), command = scope.command;
+    let release;
+    try {
+        const c = context(env, deps.host);
+        const name = c.host === "codex" ? "Codex" : "OpenCode";
+        let s = readState(c);
+        if (!s && action !== "enable")
+            return { code: 0, status: "disabled", message: `${name} automatic updates are not configured for this profile.` };
+        if (s)
+            verifyFiles(c, s);
+        if (action === "status") {
+            const registrationState = await registration(c, s, command), registered = registrationState.registered, last = lastRun(c);
+            const enabled = s.enabled && registered && owned(c.runner) && owned(c.plist);
+            const runLock = lockState(join(c.root, "run.lock"));
+            const manageLock = lockState(join(c.root, "manage.lock"));
+            const staleLock = runLock === "stale" || manageLock === "stale";
+            const uncertainLock = runLock === "uncertain" || manageLock === "uncertain";
+            const running = registrationState.running || runLock === "active";
+            const failed = staleLock || uncertainLock || last?.status === "failed" || !!registrationState.lastExit || (last?.status === "running" && !running);
+            const details = { registered, enabled, running, staleLock, uncertainLock, lastExit: registrationState.lastExit, profile: c.profile, label: c.label, log: c.log, lastRun: last };
+            if (!enabled) {
+                if (registered || s.enabled)
+                    return { code: 5, status: "scheduler-error", message: "Schedule registration is incomplete; rerun auto-update enable or disable to recover.", details };
+                return { code: 0, status: "disabled", message: `${name} automatic updates are disabled.`, details };
+            }
+            let summary = last?.status || "not yet recorded";
+            if (running)
+                summary = "running";
+            if (failed)
+                summary = "failed or interrupted; inspect the run log";
+            if (staleLock)
+                summary = "stale lock; confirm its PID has exited, remove only that lock file, then retry";
+            if (uncertainLock)
+                summary = "lock older than 15 minutes or timestamp uncertain; inspect its PID and job before recovery, never remove a running updater's lock";
+            return { code: failed ? 5 : 0, status: failed ? "update-failed" : "enabled", message: `${name} automatic updates are scheduled every 24 hours. Last run: ${summary}. Log: ${c.log}`, details };
+        }
+        if (!s) {
+            if (owned(c.plist))
+                throw new Error("A schedule already exists without our ownership record; refusing to replace it");
+            const path = (env.PATH || "/usr/bin:/bin").split(":").filter(p => isAbsolute(p) && clean(p)).join(":");
+            const source = readFileSync(fileURLToPath(import.meta.url), "utf8");
+            s = { host: c.host, ...(c.host === "opencode" ? { npm: executable("npm", path) } : {}), owner: OWNER, schema: 1, home: c.home, profile: c.profile, uid: c.uid, label: c.label, node: deps.node || executable("node", path), binary: executable(c.host, path), path, runnerHash: digest(source), enabled: false };
+            await validateInstallation(s, command);
+            if ((await registration(c, s, command)).registered)
+                throw new Error("A schedule is registered without our ownership record; refusing to change it");
+            mkdirSync(c.root, { mode: 0o700 });
+            atomic(c.config, JSON.stringify(s));
+        }
+        release = lock(c, "manage.lock");
+        s = readState(c);
+        verifyFiles(c, s);
+        const registered = (await registration(c, s, command)).registered;
+        if (action === "disable") {
+            s.enabled = false;
+            atomic(c.config, JSON.stringify(s));
+            if (registered) {
+                const result = await command(LAUNCHCTL, ["bootout", `gui/${c.uid}`, c.plist], runtimeEnv(s), 10000);
+                if (result.failure || result.code !== 0)
+                    throw new Error("Schedule was fenced but unload failed; rerun auto-update disable from your logged-in session");
+            }
+            if ((await registration(c, s, command)).registered)
+                throw new Error("Schedule remains registered; disabling is incomplete");
+            if (owned(c.plist))
+                unlinkSync(c.plist);
+            return { code: 0, status: "disabled", message: `${name} automatic updates are disabled. Runner and log retained at ${c.root}.` };
+        }
+        await validateInstallation(s, command);
+        if (registered && s.enabled && owned(c.runner) && owned(c.plist))
+            return { code: 0, status: "enabled", message: `${name} automatic updates are already scheduled every 24 hours. Log: ${c.log}`, details: { label: c.label, log: c.log } };
+        if (registered)
+            throw new Error("An incomplete schedule remains registered; run auto-update disable, then enable");
+        const source = readFileSync(fileURLToPath(import.meta.url), "utf8");
+        if (!owned(c.runner)) {
+            if (s.runnerHash !== digest(source))
+                throw new Error("Saved runner is missing and belongs to a different package version; restore the saved runner before retrying");
+            atomic(c.runner, source);
+        }
+        directory(dirname(c.plist));
+        atomic(c.plist, plist(c, s));
+        s.enabled = true;
+        atomic(c.config, JSON.stringify(s));
+        const result = await command(LAUNCHCTL, ["bootstrap", `gui/${c.uid}`, c.plist], runtimeEnv(s), 10000);
+        if (result.failure || result.code !== 0 || !(await registration(c, s, command)).registered)
+            throw new Error("Schedule registration failed; files retained for recovery. Rerun auto-update enable from your logged-in macOS session");
+        return { code: 0, status: "enabled", message: `${name} automatic updates are scheduled every 24 hours and at login. Log: ${c.log}`, details: { label: c.label, profile: c.profile, log: c.log } };
+    }
+    catch (error) {
+        return { code: 5, status: "auto-update-error", message: error instanceof Error ? error.message : "Automatic-update operation failed" };
+    }
+    finally {
+        try {
+            release?.();
+        }
+        finally {
+            scope.dispose();
+        }
+    }
+}
+export async function runScheduled(env = process.env, execute = runCommand, host = "codex") {
+    const scope = interruptionScope(execute), command = scope.command;
+    let release, c;
+    try {
+        c = context(env, host);
+        let s = readState(c);
+        if (!s || !s.enabled)
+            return { code: 0, status: "disabled", message: "Schedule disabled; no update performed" };
+        verifyFiles(c, s);
+        release = lock(c);
+        s = readState(c);
+        if (!s?.enabled)
+            return { code: 0, status: "disabled", message: "Schedule disabled; no update performed" };
+        const startedAt = new Date().toISOString();
+        const record = (status, message) => atomic(c.log, JSON.stringify({ owner: OWNER, status, startedAt, finishedAt: new Date().toISOString(), message }));
+        record("running", `Checking the installed ${s.host} CCL assets`);
+        try {
+            if (s.host === "opencode") {
+                const message = await updateOpenCode(c, s, command);
+                record("success", message);
+                return { code: 0, status: "updated", message };
+            }
+            await validateCodex(s, command);
+            for (const args of [["marketplace", "upgrade", "ccl-skills"], ["add", REF]]) {
+                if (!readState(c)?.enabled)
+                    throw new Error("Schedule was disabled; no further update commands performed");
+                const result = await command(s.binary, ["--no-daemon", "plugin", ...args], runtimeEnv(s), 120000);
+                if (result.failure || result.code !== 0)
+                    throw new Error(`${args[0]} failed (${result.failure || `exit ${result.code}`}); inspect Codex and retry on the next scheduled run`);
+                await validateCodex(s, command);
+            }
+            record("success", "Git marketplace refreshed and ccl-skills plugin installed; restart Codex to load changes");
+            return { code: 0, status: "updated", message: "ccl-skills Git plugin updated" };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Scheduled update failed";
+            record("failed", message);
+            return { code: 5, status: "update-failed", message };
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Scheduled update failed";
+        if (message.includes("already running"))
+            return { code: 0, status: "skipped", message };
+        if (release && c) {
+            try {
+                atomic(c.log, JSON.stringify({ owner: OWNER, status: "failed", finishedAt: new Date().toISOString(), message }));
+            }
+            catch { /* launchd last exit remains the independent failure signal */ }
+        }
+        return { code: 5, status: "auto-update-error", message };
+    }
+    finally {
+        try {
+            release?.();
+        }
+        finally {
+            scope.dispose();
+        }
+    }
+}
+if (process.argv[2] === "--run" && process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    runScheduled(process.env, runCommand, process.argv[3] || "codex").then(result => { process.exitCode = result.code; });
+}

package/dist/cli.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Worker } from "node:worker_threads";
 import type { Options, Result } from "./types.js";
+import { type AutoUpdateAction } from "./auto-update.js";
 type Parsed = {
     direct?: {
         code: number;
@@ -10,6 +11,7 @@ type Parsed = {
     command?: string;
     options?: Options;
     json?: boolean;
+    autoUpdateAction?: AutoUpdateAction;
 };
 export declare function parseArgs(args: string[]): Parsed;
 export type SupervisorDeps = {

package/dist/cli.js

@@ -5,8 +5,9 @@ import { Worker } from "node:worker_threads";
 import { spawn, spawnSync } from "node:child_process";
 import { paths } from "./paths.js";
 import { cachePath, emitNotice } from "./update-notice.js";
+import { autoUpdate } from "./auto-update.js";
 const pkg = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
-const HELP = `ccl-skills — npm snapshot installer for Claude Code, Codex, and OpenCode\n\nUsage:\n  ccl-skills install [--host claude|codex|opencode] [--json]\n  ccl-skills update [--host claude|codex|opencode] [--yes] [--allow-downgrade] [--json]\n  ccl-skills doctor [--host claude|codex|opencode] [--json]\n  ccl-skills uninstall [--host claude|codex|opencode] [--yes] [--json]\n\nWithout --host, every installed or package-owned host is selected.\nUpdate and uninstall are dry-run unless --yes is supplied.\nBy default update --yes upgrades the global npm package to @latest before refreshing assets.\nSet CCL_SKILLS_SKIP_SELF_UPDATE=1 for an assets-only refresh; --allow-downgrade always uses the invoked package without installing @latest first.\n\nAn interactive run prints an update notice on stderr at most once a day.\nSet CCL_SKILLS_NO_UPDATE_NOTIFIER=1 (or NO_UPDATE_NOTIFIER) to silence it; it is\nalready silent under --json, in CI, and when output is not a terminal.`;
+const HELP = `ccl-skills — npm snapshot installer for Claude Code, Codex, and OpenCode\n\nUsage:\n  ccl-skills install [--host claude|codex|opencode] [--json]\n  ccl-skills update [--host claude|codex|opencode] [--yes] [--allow-downgrade] [--json]\n  ccl-skills doctor [--host claude|codex|opencode] [--json]\n  ccl-skills uninstall [--host claude|codex|opencode] [--yes] [--json]\n  ccl-skills auto-update enable|disable|status [--host codex|opencode] [--json]\n\nAuto-update schedules an existing Codex Git or npm-managed OpenCode CCL installation on macOS; default host: codex.\nFor install/update/doctor/uninstall, omitting --host selects every installed or package-owned host.\nUpdate and uninstall are dry-run unless --yes is supplied.\nBy default update --yes upgrades the global npm package to @latest before refreshing assets.\nSet CCL_SKILLS_SKIP_SELF_UPDATE=1 for an assets-only refresh; --allow-downgrade always uses the invoked package without installing @latest first.\n\nAn interactive run prints an update notice on stderr at most once a day.\nSet CCL_SKILLS_NO_UPDATE_NOTIFIER=1 (or NO_UPDATE_NOTIFIER) to silence it; it is\nalready silent under --json, in CI, and when output is not a terminal.`;
 export function parseArgs(args) {
     if (!args.length ||
         args.includes("--help") ||
@@ -16,6 +17,27 @@ export function parseArgs(args) {
     if (args.includes("--version"))
         return { direct: { code: 0, stream: "stdout", text: pkg.version } };
     const command = args[0], flags = args.slice(1);
+    if (command === "auto-update") {
+        const action = flags[0];
+        let host = "codex", json = false, seenHost = false, invalid = false;
+        for (let index = 1; index < flags.length; index++) {
+            if (flags[index] === "--json" && !json)
+                json = true;
+            else if (flags[index] === "--host" && !seenHost) {
+                seenHost = true;
+                const value = flags[++index];
+                if (value !== "codex" && value !== "opencode")
+                    invalid = true;
+                else
+                    host = value;
+            }
+            else
+                invalid = true;
+        }
+        if (!["enable", "disable", "status"].includes(action) || invalid)
+            return { direct: { code: 2, stream: "stderr", text: "Usage: ccl-skills auto-update enable|disable|status [--host codex|opencode] [--json] (macOS; default: codex)." } };
+        return { command, autoUpdateAction: action, options: { host }, json };
+    }
     let host;
     const normalizedFlags = [];
     for (let index = 0; index < flags.length; index++) {
@@ -192,7 +214,10 @@ export async function main(args) {
     }
     const shouldSelfUpdate = parsed.command === "update" && parsed.options.yes && !parsed.options.allowDowngrade && process.env.CCL_SKILLS_SKIP_SELF_UPDATE !== "1";
     let result;
-    if (shouldSelfUpdate) {
+    if (parsed.autoUpdateAction) {
+        result = await autoUpdate(parsed.autoUpdateAction, { host: parsed.options.host });
+    }
+    else if (shouldSelfUpdate) {
         const preflight = await supervise("update", { ...parsed.options, yes: false });
         result = preflight.code === 0 ? selfUpdate(parsed.options) : preflight;
     }
@@ -204,7 +229,8 @@ export async function main(args) {
     write(process.stdout, parsed.json
         ? JSON.stringify(result)
         : `${result.status}: ${result.message}${result.plan ? `\n${result.plan.map((x) => `- ${x}`).join("\n")}` : ""}`);
-    notifyUpdate(!!parsed.json);
+    if (!parsed.autoUpdateAction)
+        notifyUpdate(!!parsed.json);
     return result.code;
 }
 export function isDirectEntrypoint(importMetaUrl, argv1) {

package/dist/opencode-adapter.js

@@ -330,7 +330,7 @@ function doctor(context) {
     }
     if (drift.length || reason)
         return { code: 3, status: "shared-drift", message: "OpenCode shared files changed after npm install; they will never be auto-deleted", details: { drift, ...(reason ? { reason } : {}) } };
-    return { code: 0, status: "healthy", message: `OpenCode uses @ccoalm/ccl-skills ${manifest.version}` };
+    return { code: 0, status: "healthy", message: `OpenCode uses @ccoalm/ccl-skills ${manifest.version}`, details: { version: manifest.version, sourceKind: manifest.sourceKind } };
 }
 function installOrUpdate(commandName, options, context) {
     const p = paths(context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccoalm/ccl-skills",
-	"version": "0.18.7",
+	"version": "0.18.8",
   "description": "Reusable workflows that help coding agents plan, build, test, review, and release software — for Claude Code, Codex, and OpenCode",
 	"keywords": ["skills", "agent-skills", "claude", "claude-code", "codex", "opencode", "agent", "ai", "ai-agents", "cli", "anthropic", "developer-tools"],
   "type": "module",