@ai-substrate/engineering-harness 0.2.0-canary.45

package/harness/cli/dist/services/skills/skills-service.js

@@ -0,0 +1,132 @@
+/** GitHub `owner/repo` shorthand, optionally with a `/subdir` tail. */
+const GH_SHORTHAND = /^([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)(?:\/(.+))?$/;
+/** A bare GitHub repo URL (`https://github.com/owner/repo`, optional `.git` / trailing slash) — no further path. */
+const GH_URL = /^https?:\/\/github\.com\/([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+?)(?:\.git)?\/?$/;
+/**
+ * Translate a friendly `--source` (+ optional `--branch`, or a `#ref` suffix on
+ * the source) into the specifier the Vercel installer truly accepts.
+ *
+ * Why this exists: `npx skills add` has NO `--branch`/`--ref` flag and NO
+ * `owner/repo#ref` shorthand (vercel-labs/skills#42 is an open request for it).
+ * Its ONLY documented branch mechanism is a GitHub *tree URL*:
+ * `https://github.com/<owner>/<repo>/tree/<ref>[/<subdir>]`. So when the user
+ * names a branch, we rewrite the GitHub shorthand into that URL form.
+ *
+ * Invariants:
+ *   - **No ref → verbatim pass-through.** The source is returned unchanged (the
+ *     default `owner/repo` shorthand installs the default branch, exactly as
+ *     before this flag existed) — so every existing call site is untouched.
+ *   - **Ref precedence**: an explicit `branch` arg wins over a `#ref` suffix.
+ *   - **Slashed refs are rejected** (`ok:false`). The installer reads the first
+ *     path segment after `/tree/` as the *entire* ref, so `feat/x` would silently
+ *     mis-resolve to branch `feat` + subdir `x`. Failing fast (deterministic
+ *     backpressure) beats handing the installer a URL it will mis-parse.
+ *   - **Branch only applies to GitHub sources** (`owner/repo[/subdir]` or
+ *     `https://github.com/owner/repo`). A branch against a local path / GitLab /
+ *     generic git URL is rejected with guidance rather than ignored.
+ */
+export function resolveSkillsSource(rawSource, branch) {
+    const hashIdx = rawSource.indexOf('#');
+    const base = hashIdx === -1 ? rawSource : rawSource.slice(0, hashIdx);
+    const refFromHash = hashIdx === -1 ? undefined : rawSource.slice(hashIdx + 1);
+    const ref = (branch ?? refFromHash)?.trim() || undefined;
+    // No ref → preserve today's verbatim pass-through (installs the default branch).
+    if (!ref) {
+        return { ok: true, source: base };
+    }
+    if (ref.includes('/')) {
+        return {
+            ok: false,
+            reason: `branch '${ref}' contains a '/': the \`npx skills add\` GitHub tree-URL form cannot ` +
+                'express a slashed branch name (it reads the first path segment after /tree/ as the ' +
+                'whole ref). Use a single-segment branch, merge the skills to the default branch, or ' +
+                'pass a local --source path.',
+        };
+    }
+    // Local path or non-GitHub URL → branch translation doesn't apply.
+    const looksLocalOrUrl = base.startsWith('.') || base.startsWith('/') || (base.includes('://') && !GH_URL.test(base));
+    const shorthand = looksLocalOrUrl ? null : base.match(GH_SHORTHAND);
+    if (shorthand) {
+        const [, owner, repo, subdir] = shorthand;
+        const tail = subdir ? `/${subdir}` : '';
+        return {
+            ok: true,
+            source: `https://github.com/${owner}/${repo}/tree/${ref}${tail}`,
+            branch: ref,
+        };
+    }
+    const url = base.match(GH_URL);
+    if (url) {
+        const [, owner, repo] = url;
+        return { ok: true, source: `https://github.com/${owner}/${repo}/tree/${ref}`, branch: ref };
+    }
+    return {
+        ok: false,
+        reason: `--branch only applies to a GitHub \`owner/repo\` (optionally \`owner/repo/subdir\`) or ` +
+            `\`https://github.com/owner/repo\` source; '${base}' isn't one. Drop --branch, or point ` +
+            '--source at a GitHub repo.',
+    };
+}
+/**
+ * Pure `npx skills add …` argv builder — the one place the Vercel `skills` flag
+ * surface is encoded (Principle 8: wrap, don't rebuild). No I/O, no child spawn:
+ * the act feeds the returned argv to the injected `ExecPort`, and tests assert
+ * the exact array (Principle 3). The returned array is the args AFTER `npx`, i.e.
+ * `['skills@latest', 'add', <source>, '-a', <t>, …, '-g'?, '-s', <slug>, …, '-y']`.
+ *
+ * Invariants (AC3/AC4):
+ *   - always pins `skills@latest` and always appends `-y` (UNCONDITIONALLY — the
+ *     builder makes it impossible to construct a blocking invocation, so the
+ *     interactive picker never appears regardless of caller input);
+ *   - each target fans out as a repeated `-a <target>`;
+ *   - `-g` is present iff `global` is true.
+ *
+ * Precondition: `targets` is non-empty — enforced by the act (missing `--target`
+ * → `E108`) before this is ever called.
+ */
+export function buildInstallArgv(opts) {
+    const argv = ['skills@latest', 'add', opts.source];
+    for (const target of opts.targets) {
+        argv.push('-a', target);
+    }
+    if (opts.global) {
+        argv.push('-g');
+    }
+    for (const slug of opts.skills ?? []) {
+        argv.push('-s', slug);
+    }
+    // Unconditional: never let the Vercel interactive picker block (AC3).
+    argv.push('-y');
+    return argv;
+}
+/**
+ * Pure `npx skills remove …` argv builder — the PRUNE half of `harness skills
+ * update` (Principle 8: wrap, don't rebuild). No I/O. Renamed/removed skills are
+ * passed as POSITIONAL slugs; `npx skills remove` no-ops (exit 0) on any slug that
+ * isn't installed, so it is safe to call with the full legacy list every time.
+ * Like the install builder it fans out `-a <target>`, adds `-g` iff global, and
+ * always appends `-y` (never blocks). Returns the args AFTER `npx`:
+ * `['skills@latest', 'remove', <slug>, …, '-a', <t>, …, '-g'?, '-y']`.
+ *
+ * Precondition: `slugs` and `targets` are both non-empty — enforced by the act.
+ */
+export function buildRemoveArgv(opts) {
+    const argv = ['skills@latest', 'remove', ...opts.slugs];
+    for (const target of opts.targets) {
+        argv.push('-a', target);
+    }
+    if (opts.global) {
+        argv.push('-g');
+    }
+    // Unconditional: never let the Vercel interactive picker block (mirrors install).
+    argv.push('-y');
+    return argv;
+}
+/**
+ * The human-readable command line we announce before running (and echo in the JSON
+ * envelope). Generic over any `npx skills …` argv — used for both `add` and `remove`.
+ */
+export function formatInstallCommand(argv) {
+    return `npx ${argv.join(' ')}`;
+}
+//# sourceMappingURL=skills-service.js.map

package/harness/cli/dist/services/skills/skills-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-service.js","sourceRoot":"","sources":["../../../src/services/skills/skills-service.ts"],"names":[],"mappings":"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"}

package/harness/cli/dist/services/update/banner.d.ts

@@ -0,0 +1,26 @@
+import type { EnvPort } from '../../adapters/env/env-port.js';
+import type { FsPort } from '../../adapters/fs/fs-port.js';
+import type { Envelope, UpdateAvailable } from '../../output/envelope.js';
+import type { OutputMode, Writers } from '../../output/output-port.js';
+/**
+ * The single human-mode stderr notice (AC8), newline-terminated. Sourced from
+ * the field so the command shown always matches `update_available.command`.
+ */
+export declare function formatUpdateBanner(ua: UpdateAvailable): string;
+export interface BannerDecoratorDeps {
+    fs: FsPort;
+    env: EnvPort;
+    /** Installed version (readVersion()) compared against the cached latest. */
+    installed: string;
+    mode: OutputMode;
+    writers: Writers;
+}
+/**
+ * Build the exit-chokepoint banner decorator (wired via `setBannerDecorator` in
+ * T007). On each exit it does a SINGLE sync cache read — no network on the hot
+ * path (AC9). If a newer version is known it sets the additive `update_available`
+ * field (serialized by the JSON renderer on EVERY command, AC7) and, in human
+ * mode only, writes exactly one stderr line (AC8). Returns the structural
+ * `(env) => void` so the exit kernel never imports the service layer.
+ */
+export declare function buildBannerDecorator(deps: BannerDecoratorDeps): (env: Envelope) => void;

package/harness/cli/dist/services/update/banner.js

@@ -0,0 +1,28 @@
+import { bannerFromCache } from './update-service.js';
+/**
+ * The single human-mode stderr notice (AC8), newline-terminated. Sourced from
+ * the field so the command shown always matches `update_available.command`.
+ */
+export function formatUpdateBanner(ua) {
+    return `update available to ${ua.latest} from ${ua.installed} — run: ${ua.command}\n`;
+}
+/**
+ * Build the exit-chokepoint banner decorator (wired via `setBannerDecorator` in
+ * T007). On each exit it does a SINGLE sync cache read — no network on the hot
+ * path (AC9). If a newer version is known it sets the additive `update_available`
+ * field (serialized by the JSON renderer on EVERY command, AC7) and, in human
+ * mode only, writes exactly one stderr line (AC8). Returns the structural
+ * `(env) => void` so the exit kernel never imports the service layer.
+ */
+export function buildBannerDecorator(deps) {
+    return (env) => {
+        const ua = bannerFromCache(deps.fs, deps.env, deps.installed);
+        if (!ua)
+            return;
+        env.update_available = ua;
+        if (deps.mode === 'human') {
+            deps.writers.err(formatUpdateBanner(ua));
+        }
+    };
+}
+//# sourceMappingURL=banner.js.map

package/harness/cli/dist/services/update/banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"banner.js","sourceRoot":"","sources":["../../../src/services/update/banner.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAmB;IACpD,OAAO,uBAAuB,EAAE,CAAC,MAAM,SAAS,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,OAAO,IAAI,CAAC;AACxF,CAAC;AAWD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAyB;IAC5D,OAAO,CAAC,GAAa,EAAE,EAAE;QACvB,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9D,IAAI,CAAC,EAAE;YAAE,OAAO;QAChB,GAAG,CAAC,gBAAgB,GAAG,EAAE,CAAC;QAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/harness/cli/dist/services/update/cache.d.ts

@@ -0,0 +1,21 @@
+import type { EnvPort } from '../../adapters/env/env-port.js';
+import type { FsPort } from '../../adapters/fs/fs-port.js';
+export interface UpdateCheckCache {
+    /** ISO-8601 instant of the last SUCCESSFUL registry lookup. */
+    last_success_iso: string;
+    /** Latest version seen at that lookup, or null if the registry returned none. */
+    latest: string | null;
+}
+/** Absolute logical path to the cache file, or null if home is unresolved. */
+export declare function cachePath(env: EnvPort): string | null;
+/**
+ * Read + validate the cache. Returns null on any of: home unresolved, file
+ * missing/unreadable, non-JSON, or wrong shape — the caller treats null as
+ * "no cached info". Never throws.
+ */
+export declare function readCache(fs: FsPort, env: EnvPort): UpdateCheckCache | null;
+/**
+ * Write the cache under `~/.harness/` (creating the dir). No-op when home is
+ * unresolved — best-effort, the check still works off live lookups.
+ */
+export declare function writeCache(fs: FsPort, env: EnvPort, cache: UpdateCheckCache): void;

package/harness/cli/dist/services/update/cache.js

@@ -0,0 +1,61 @@
+import { posixJoin } from '../shared/posix-path.js';
+import { HARNESS_DIR } from '../shared/temp.js';
+/**
+ * User-global update-check cache: a tiny record under `~/.harness/` (NOT the
+ * repo's `.harness/`) remembering when the registry was last successfully
+ * queried and what it returned. Lets the check throttle to once / 24h and lets
+ * a known update keep showing through later lookup failures (AC5/AC6/AC9).
+ *
+ * All I/O is via `FsPort`; the home directory via `EnvPort.home()` — no `node:*`
+ * (P2). Reads are total: anything wrong ⇒ null, never a throw.
+ */
+const CACHE_FILE = 'update-check.json';
+/** `<home>/.harness`, or null when the home directory can't be resolved. */
+function harnessDir(env) {
+    const home = env.home();
+    return home ? posixJoin(home, HARNESS_DIR) : null;
+}
+/** Absolute logical path to the cache file, or null if home is unresolved. */
+export function cachePath(env) {
+    const dir = harnessDir(env);
+    return dir ? posixJoin(dir, CACHE_FILE) : null;
+}
+/**
+ * Read + validate the cache. Returns null on any of: home unresolved, file
+ * missing/unreadable, non-JSON, or wrong shape — the caller treats null as
+ * "no cached info". Never throws.
+ */
+export function readCache(fs, env) {
+    const path = cachePath(env);
+    if (!path)
+        return null;
+    const raw = fs.readText(path);
+    if (raw === null)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const obj = parsed;
+        if (typeof obj.last_success_iso !== 'string')
+            return null;
+        if (obj.latest !== null && typeof obj.latest !== 'string')
+            return null;
+        return { last_success_iso: obj.last_success_iso, latest: obj.latest ?? null };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the cache under `~/.harness/` (creating the dir). No-op when home is
+ * unresolved — best-effort, the check still works off live lookups.
+ */
+export function writeCache(fs, env, cache) {
+    const dir = harnessDir(env);
+    if (!dir)
+        return;
+    fs.mkdirp(dir);
+    fs.writeText(posixJoin(dir, CACHE_FILE), `${JSON.stringify(cache, null, 2)}\n`);
+}
+//# sourceMappingURL=cache.js.map

package/harness/cli/dist/services/update/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/services/update/cache.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;GAQG;AAEH,MAAM,UAAU,GAAG,mBAAmB,CAAC;AASvC,4EAA4E;AAC5E,SAAS,UAAU,CAAC,GAAY;IAC9B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACxB,OAAO,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,SAAS,CAAC,GAAY;IACpC,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,EAAU,EAAE,GAAY;IAChD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACvD,MAAM,GAAG,GAAG,MAAiC,CAAC;QAC9C,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1D,IAAI,GAAG,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACvE,OAAO,EAAE,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU,EAAE,GAAY,EAAE,KAAuB;IAC1E,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,CAAC,GAAG;QAAE,OAAO;IACjB,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACf,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAClF,CAAC"}

package/harness/cli/dist/services/update/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Update-domain constants. Plain strings, no I/O — safe to import from services,
+ * acts, and the composition root alike (the Node adapters receive these by
+ * injection, never importing the service layer themselves).
+ */
+/** The registry package the harness CLI is published as (plan 018). */
+export declare const PACKAGE_NAME = "@ai-substrate/engineering-harness";
+/** The exact command the update banner / next_action tells users to run. */
+export declare const UPDATE_COMMAND = "harness update";

package/harness/cli/dist/services/update/constants.js

@@ -0,0 +1,10 @@
+/**
+ * Update-domain constants. Plain strings, no I/O — safe to import from services,
+ * acts, and the composition root alike (the Node adapters receive these by
+ * injection, never importing the service layer themselves).
+ */
+/** The registry package the harness CLI is published as (plan 018). */
+export const PACKAGE_NAME = '@ai-substrate/engineering-harness';
+/** The exact command the update banner / next_action tells users to run. */
+export const UPDATE_COMMAND = 'harness update';
+//# sourceMappingURL=constants.js.map

package/harness/cli/dist/services/update/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/services/update/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEhE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC"}

package/harness/cli/dist/services/update/install.d.ts

@@ -0,0 +1,26 @@
+import type { ExecResult } from '../../adapters/exec/exec-port.js';
+/**
+ * Pure helpers for the global install path (`harness update` / `self-install`).
+ * Argv construction + failure classification live here (I/O-free, unit-testable);
+ * the act owns the announce-then-run + envelope rendering, shelling only through
+ * the injected `ExecPort` (the install itself is a `npm i -g` pass-through, P8).
+ */
+/** npm argv to install the harness globally at `spec` (a dist-tag like `latest`, or a concrete version). */
+export declare function npmInstallArgv(spec: string): string[];
+/** Render an npm argv as the exact command string (for the announce line + next_action). */
+export declare function formatNpmCommand(argv: string[]): string;
+/** Normalise a pin like `v0.3.0` → `0.3.0` (npm specs carry no leading `v`). */
+export declare function normalizePin(version: string): string;
+export interface InstallFailure {
+    code: string;
+    message: string;
+    next_action: string;
+}
+/**
+ * Classify a failed `npm i -g` result into an actionable error (AC10). Order is
+ * deliberate: npm-absent → auth → (pinned) version-not-found → permission →
+ * generic. `command` is echoed into the next_action so the user can re-run.
+ */
+export declare function classifyInstallFailure(result: ExecResult, command: string, opts?: {
+    pinned?: string;
+}): InstallFailure;

package/harness/cli/dist/services/update/install.js

@@ -0,0 +1,78 @@
+import { ErrorCodes } from '../../output/error-codes.js';
+import { PACKAGE_NAME } from './constants.js';
+/**
+ * Pure helpers for the global install path (`harness update` / `self-install`).
+ * Argv construction + failure classification live here (I/O-free, unit-testable);
+ * the act owns the announce-then-run + envelope rendering, shelling only through
+ * the injected `ExecPort` (the install itself is a `npm i -g` pass-through, P8).
+ */
+/** npm argv to install the harness globally at `spec` (a dist-tag like `latest`, or a concrete version). */
+export function npmInstallArgv(spec) {
+    return ['i', '-g', `${PACKAGE_NAME}@${spec}`];
+}
+/** Render an npm argv as the exact command string (for the announce line + next_action). */
+export function formatNpmCommand(argv) {
+    return `npm ${argv.join(' ')}`;
+}
+/** Normalise a pin like `v0.3.0` → `0.3.0` (npm specs carry no leading `v`). */
+export function normalizePin(version) {
+    const v = version.trim();
+    return v.startsWith('v') || v.startsWith('V') ? v.slice(1) : v;
+}
+/**
+ * Classify a failed `npm i -g` result into an actionable error (AC10). Order is
+ * deliberate: npm-absent → auth → (pinned) version-not-found → permission →
+ * generic. `command` is echoed into the next_action so the user can re-run.
+ */
+export function classifyInstallFailure(result, command, opts) {
+    const text = `${result.stderr}\n${result.stdout}`.toLowerCase();
+    if (result.code === 127 || /command not found|not recognized|spawn npm/.test(text)) {
+        return {
+            code: ErrorCodes.UPDATE_NPM_MISSING,
+            message: 'npm was not found on PATH.',
+            next_action: `Install Node.js + npm (https://nodejs.org), then re-run: ${command}`,
+        };
+    }
+    // A PINNED version that 404s genuinely doesn't exist — but ONLY when the npm
+    // text is VERSION-specific. A generic 404/"not found" on a pinned install is a
+    // registry / not-yet-published issue (not "that version is absent"), so it
+    // falls through to the registry branch below (companion F006).
+    if (opts?.pinned && /no matching version|no such version|notarget/.test(text)) {
+        return {
+            code: ErrorCodes.UPDATE_VERSION_NOT_FOUND,
+            message: `version ${opts.pinned} was not found in the registry.`,
+            next_action: 'Pick a published version (`harness update --check` shows the latest), then re-run with `--pin <version>`.',
+        };
+    }
+    // Registry trouble. For a PUBLIC npm package install needs no auth, so a 401/403
+    // almost always means npm is pointed at the wrong registry or carries a stale
+    // login; a NON-pinned (or generic) 404 means the package isn't published yet or
+    // the registry is unreachable. Neither is a token problem (FX001 — public npm).
+    {
+        const looksAuth = /\b(e?401|e?403)\b|unauthorized|forbidden|authentication|auth.*requir|need.*auth/.test(text);
+        const looks404 = /e?404|not found|no matching version|notarget|no such version/.test(text);
+        if (looksAuth || looks404) {
+            return {
+                code: ErrorCodes.UPDATE_AUTH_FAILED,
+                message: looksAuth
+                    ? `the npm registry rejected the install — ${PACKAGE_NAME} is public and needs no auth, so npm is likely pointed at the wrong registry or has a stale login.`
+                    : `${PACKAGE_NAME} could not be resolved — it may not be published yet, or the npm registry is unreachable.`,
+                next_action: `Confirm npm uses the public registry (\`npm config get registry\` → https://registry.npmjs.org) ` +
+                    `and that ${PACKAGE_NAME} is published on npmjs.com, then re-run: ${command}`,
+            };
+        }
+    }
+    if (/eacces|eperm|permission denied|access is denied/.test(text)) {
+        return {
+            code: ErrorCodes.UPDATE_PERMISSION_DENIED,
+            message: 'the global npm install was denied (permissions).',
+            next_action: `Use a Node version manager (nvm/Volta) or a prefix-writable/elevated npm, then re-run: ${command}`,
+        };
+    }
+    return {
+        code: ErrorCodes.UPDATE_FAILED,
+        message: `update failed (exit ${result.code}).`,
+        next_action: `Inspect the npm output above, then re-run: ${command}`,
+    };
+}
+//# sourceMappingURL=install.js.map

package/harness/cli/dist/services/update/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../../src/services/update/install.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;GAKG;AAEH,4GAA4G;AAC5G,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,YAAY,IAAI,IAAI,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC7C,OAAO,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACjC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IACzB,OAAO,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAkB,EAClB,OAAe,EACf,IAA0B;IAE1B,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC;IAEhE,IAAI,MAAM,CAAC,IAAI,KAAK,GAAG,IAAI,4CAA4C,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnF,OAAO;YACL,IAAI,EAAE,UAAU,CAAC,kBAAkB;YACnC,OAAO,EAAE,4BAA4B;YACrC,WAAW,EAAE,4DAA4D,OAAO,EAAE;SACnF,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,+EAA+E;IAC/E,2EAA2E;IAC3E,+DAA+D;IAC/D,IAAI,IAAI,EAAE,MAAM,IAAI,8CAA8C,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9E,OAAO;YACL,IAAI,EAAE,UAAU,CAAC,wBAAwB;YACzC,OAAO,EAAE,WAAW,IAAI,CAAC,MAAM,iCAAiC;YAChE,WAAW,EACT,2GAA2G;SAC9G,CAAC;IACJ,CAAC;IAED,iFAAiF;IACjF,8EAA8E;IAC9E,gFAAgF;IAChF,gFAAgF;IAChF,CAAC;QACC,MAAM,SAAS,GACb,iFAAiF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/F,MAAM,QAAQ,GAAG,8DAA8D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3F,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;YAC1B,OAAO;gBACL,IAAI,EAAE,UAAU,CAAC,kBAAkB;gBACnC,OAAO,EAAE,SAAS;oBAChB,CAAC,CAAC,2CAA2C,YAAY,oGAAoG;oBAC7J,CAAC,CAAC,GAAG,YAAY,2FAA2F;gBAC9G,WAAW,EACT,kGAAkG;oBAClG,YAAY,YAAY,4CAA4C,OAAO,EAAE;aAChF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,iDAAiD,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjE,OAAO;YACL,IAAI,EAAE,UAAU,CAAC,wBAAwB;YACzC,OAAO,EAAE,kDAAkD;YAC3D,WAAW,EAAE,0FAA0F,OAAO,EAAE;SACjH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,aAAa;QAC9B,OAAO,EAAE,uBAAuB,MAAM,CAAC,IAAI,IAAI;QAC/C,WAAW,EAAE,8CAA8C,OAAO,EAAE;KACrE,CAAC;AACJ,CAAC"}

package/harness/cli/dist/services/update/semver.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Minimal, pure SemVer "is-newer" comparison for the update check.
+ *
+ * Intentionally tiny — no dependency, no validation surface beyond what the
+ * update decision needs: is `latest` strictly newer than `installed`? It is
+ * pre-release aware (so a `-canary.N` build sorts below its release, per the
+ * SemVer spec) and **safe by default**: if either side is malformed it returns
+ * false — an unparseable version never produces a phantom "update available".
+ */
+/** True iff `v` is a valid, concrete SemVer version (used to reject dist-tag pins — companion F005). */
+export declare function isValidVersion(v: string): boolean;
+/**
+ * True iff `latest` is strictly newer than `installed`. Malformed input on
+ * either side ⇒ false (no update). Tolerates a leading `v`.
+ */
+export declare function isNewer(latest: string, installed: string): boolean;

package/harness/cli/dist/services/update/semver.js

@@ -0,0 +1,108 @@
+/**
+ * Minimal, pure SemVer "is-newer" comparison for the update check.
+ *
+ * Intentionally tiny — no dependency, no validation surface beyond what the
+ * update decision needs: is `latest` strictly newer than `installed`? It is
+ * pre-release aware (so a `-canary.N` build sorts below its release, per the
+ * SemVer spec) and **safe by default**: if either side is malformed it returns
+ * false — an unparseable version never produces a phantom "update available".
+ */
+const NUMERIC = /^\d+$/;
+/** A numeric identifier with no leading zero (SemVer §9 — `0` ok, `01` not). */
+const NUMERIC_NOLEAD = /^(0|[1-9]\d*)$/;
+/** A pre-release identifier's legal alphabet (SemVer §9). */
+const PRERELEASE_ID = /^[0-9A-Za-z-]+$/;
+/**
+ * Parse `vX.Y.Z[-pre][+build]` → Parsed, or null if it isn't a clean triple.
+ * Strict per SemVer §9 (companion F002): core/numeric-prerelease identifiers
+ * reject leading zeroes; pre-release identifiers reject illegal characters — so
+ * malformed input can never slip through and compare as "newer".
+ */
+function parse(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    let v = raw.trim();
+    if (v === '')
+        return null;
+    if (v[0] === 'v' || v[0] === 'V')
+        v = v.slice(1);
+    // Build metadata (+…) is ignored for precedence (SemVer §10).
+    const plus = v.indexOf('+');
+    if (plus !== -1)
+        v = v.slice(0, plus);
+    const dash = v.indexOf('-');
+    const core = dash === -1 ? v : v.slice(0, dash);
+    const pre = dash === -1 ? '' : v.slice(dash + 1);
+    const parts = core.split('.');
+    if (parts.length !== 3)
+        return null;
+    if (!parts.every((p) => NUMERIC_NOLEAD.test(p)))
+        return null; // reject leading zeroes / non-numeric
+    const prerelease = pre === '' ? [] : pre.split('.');
+    for (const id of prerelease) {
+        if (!PRERELEASE_ID.test(id))
+            return null; // empty or illegal character
+        if (NUMERIC.test(id) && !NUMERIC_NOLEAD.test(id))
+            return null; // numeric with a leading zero
+    }
+    return { major: Number(parts[0]), minor: Number(parts[1]), patch: Number(parts[2]), prerelease };
+}
+/** True iff `v` is a valid, concrete SemVer version (used to reject dist-tag pins — companion F005). */
+export function isValidVersion(v) {
+    return parse(v) !== null;
+}
+function compareCore(a, b) {
+    if (a.major !== b.major)
+        return a.major < b.major ? -1 : 1;
+    if (a.minor !== b.minor)
+        return a.minor < b.minor ? -1 : 1;
+    if (a.patch !== b.patch)
+        return a.patch < b.patch ? -1 : 1;
+    return 0;
+}
+/** SemVer §11.4 pre-release precedence. A release (no pre-release) outranks any. */
+function comparePrerelease(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1; // a is a release, b is a pre-release ⇒ a newer
+    if (b.length === 0)
+        return -1;
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const ai = a[i];
+        const bi = b[i];
+        const an = NUMERIC.test(ai);
+        const bn = NUMERIC.test(bi);
+        if (an && bn) {
+            const x = Number(ai);
+            const y = Number(bi);
+            if (x !== y)
+                return x < y ? -1 : 1;
+        }
+        else if (an !== bn) {
+            return an ? -1 : 1; // numeric identifiers rank lower than alphanumeric
+        }
+        else if (ai !== bi) {
+            return ai < bi ? -1 : 1; // lexical ASCII order
+        }
+    }
+    if (a.length !== b.length)
+        return a.length < b.length ? -1 : 1; // more fields win
+    return 0;
+}
+/**
+ * True iff `latest` is strictly newer than `installed`. Malformed input on
+ * either side ⇒ false (no update). Tolerates a leading `v`.
+ */
+export function isNewer(latest, installed) {
+    const l = parse(latest);
+    const i = parse(installed);
+    if (!l || !i)
+        return false;
+    const core = compareCore(l, i);
+    if (core !== 0)
+        return core > 0;
+    return comparePrerelease(l.prerelease, i.prerelease) > 0;
+}
+//# sourceMappingURL=semver.js.map

package/harness/cli/dist/services/update/semver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver.js","sourceRoot":"","sources":["../../../src/services/update/semver.ts"],"names":[],"mappings":"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"}

package/harness/cli/dist/services/update/update-service.d.ts

@@ -0,0 +1,46 @@
+import type { Clock } from '../../adapters/clock/clock-port.js';
+import type { EnvPort } from '../../adapters/env/env-port.js';
+import type { FsPort } from '../../adapters/fs/fs-port.js';
+import type { VersionLookupPort } from '../../adapters/version-lookup/version-lookup-port.js';
+import type { UpdateAvailable } from '../../output/envelope.js';
+/** The throttle window: at most one registry lookup per 24h. */
+export declare const CHECK_WINDOW_MS: number;
+/**
+ * Build the `update_available` field iff `latest` is strictly newer than
+ * `installed`. The command is pinned to "harness update" (AC7).
+ */
+export declare function toUpdateAvailable(installed: string, latest: string | null): UpdateAvailable | null;
+/**
+ * SYNC banner source for the hot path (T007): read the cache and, if its
+ * last-known latest is newer than the installed version, return the notice.
+ * No network, a single cache read — safe to call on every command exit.
+ */
+export declare function bannerFromCache(fs: FsPort, env: EnvPort, installed: string): UpdateAvailable | null;
+/** Whether the cache is stale enough to warrant a fresh lookup. */
+export declare function isDue(now: string, lastSuccessIso: string, windowMs?: number): boolean;
+export interface CheckResult {
+    installed: string;
+    /** Latest known — a fresh lookup, or last-known cache on skip/failure. */
+    latest: string | null;
+    update_available: UpdateAvailable | null;
+    /** True if a registry lookup actually ran this call. */
+    checked: boolean;
+    /** True if a lookup ran AND succeeded (cache advanced). */
+    refreshed: boolean;
+}
+export interface CheckDeps {
+    fs: FsPort;
+    env: EnvPort;
+    clock: Clock;
+    lookup: VersionLookupPort;
+}
+/**
+ * Throttled update check. Reads the cache; if `force` or the 24h window has
+ * elapsed, does exactly ONE registry lookup. A successful lookup (non-null)
+ * advances the cache (ts + latest); a failed/empty lookup (null or throw) keeps
+ * the cache untouched so a previously-known update survives (AC9). When not due,
+ * reports off the last-known cache with no network call (AC5).
+ */
+export declare function runCheck(deps: CheckDeps, installed: string, opts?: {
+    force?: boolean;
+}): Promise<CheckResult>;