agentic-workflow-manager 9.21.0 → 9.22.1

package/dist/src/core/changes/receipt.js

@@ -5,6 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isFullSelection = isFullSelection;
 exports.sensorPairs = sensorPairs;
+exports.allowsUnmeasuredRelaxation = allowsUnmeasuredRelaxation;
+exports.measuredPathSet = measuredPathSet;
+exports.filterLateFilesForReceipt = filterLateFilesForReceipt;
 exports.computeReceiptDigest = computeReceiptDigest;
 exports.buildReceipt = buildReceipt;
 exports.writeReceipt = writeReceipt;
@@ -22,14 +25,20 @@ const paths_1 = require("../paths");
 const types_1 = require("./types");
 const text_safety_1 = require("./text-safety");
 const worktree_1 = require("./worktree");
-const RECEIPT_KEYS = ['schema', 'commit', 'ranAt', 'cliVersion', 'overall', 'sensors', 'digest'];
+const inputs_digest_1 = require("../../commands/sensors/inputs-digest");
+const contract_1 = require("../../commands/sensors/compatibility/contract");
+const RECEIPT_KEYS_V1 = ['schema', 'commit', 'ranAt', 'cliVersion', 'overall', 'sensors', 'digest'];
+const RECEIPT_KEYS_V2 = [...RECEIPT_KEYS_V1, 'measurements', 'alwaysMeasuredPaths'];
 const MAX_RECEIPT_BYTES = 1024 * 1024;
-/** True when the run covers every sensor: `--changed` never does, `--all` always does, `--fast` xor `--slow` is partial. */
+const MAX_MEASURED_PATHS = 50_000;
+/** True when the run covers every sensor: `--changed`/`--slice` never do, `--all` always does, `--fast` xor `--slow` is partial. */
 function isFullSelection(opts) {
     if (opts === null || typeof opts !== 'object')
         return false;
     if (opts.changed)
         return false;
+    if (opts.slice)
+        return false;
     if (opts.all)
         return true;
     return Boolean(opts.fast) === Boolean(opts.slow);
@@ -46,6 +55,108 @@ function sensorPairs(sensors) {
 function sortedSensors(sensors) {
     return Object.fromEntries(sensorPairs(sensors));
 }
+function sortedStrings(values) {
+    return [...values].sort(byName);
+}
+function isSha256Digest(v) {
+    return typeof v === 'string' && /^sha256:[0-9a-f]{64}$/.test(v);
+}
+function isPackageRootRel(v) {
+    return typeof v === 'string' && (v === '' || (0, inputs_digest_1.isSafeRepoRel)(v));
+}
+function measurementProblem(name, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return `measurement for ${name} must be an object`;
+    const m = value;
+    const keys = Object.keys(m);
+    if (keys.length !== 5 || !['inputs', 'packageRootRel', 'inputDigest', 'sensorFingerprint', 'measuredPaths'].every((k) => k in m)) {
+        return `measurement for ${name} must have exactly inputs, packageRootRel, inputDigest, sensorFingerprint, measuredPaths`;
+    }
+    if (!Array.isArray(m.inputs) || m.inputs.length === 0) {
+        return `measurement inputs for ${name} must be a nonempty array of single-line strings`;
+    }
+    try {
+        // RF-1.5: reuse the same glob grammar as authored sensor inputs (reject .., !, braces, extglobs).
+        (0, contract_1.parseSensorInputs)(m.inputs, 'receipt', `measurement[${name}].inputs`);
+    }
+    catch {
+        return `measurement inputs for ${name} must obey RF-1.5 sensor input glob rules`;
+    }
+    if (!isPackageRootRel(m.packageRootRel))
+        return `measurement packageRootRel for ${name} must be '' or a safe repo-root POSIX path`;
+    if (!isSha256Digest(m.inputDigest))
+        return `measurement inputDigest for ${name} must be sha256:<hex>`;
+    if (!isSha256Digest(m.sensorFingerprint))
+        return `measurement sensorFingerprint for ${name} must be sha256:<hex>`;
+    if (!Array.isArray(m.measuredPaths) || m.measuredPaths.length > MAX_MEASURED_PATHS) {
+        return `measurement measuredPaths for ${name} must be an array within bounds`;
+    }
+    if (m.measuredPaths.some((p) => typeof p !== 'string' || !(0, inputs_digest_1.isSafeRepoRel)(p))) {
+        return `measurement measuredPaths for ${name} must be safe repo-root POSIX paths`;
+    }
+    const sorted = sortedStrings(m.measuredPaths);
+    if (JSON.stringify(m.measuredPaths) !== JSON.stringify(sorted)) {
+        return `measurement measuredPaths for ${name} must be sorted`;
+    }
+    return null;
+}
+/**
+ * RF-4.6: schema-2 unmeasured-path relaxation applies only when every sensor on the
+ * receipt had effective authored inputs (a nonempty measurement.inputs entry).
+ */
+function allowsUnmeasuredRelaxation(receipt) {
+    if (receipt === null || typeof receipt !== 'object')
+        return false;
+    if (receipt.schema !== 2)
+        return false;
+    const names = Object.keys(receipt.sensors);
+    if (names.length === 0)
+        return false;
+    for (const name of names) {
+        const m = receipt.measurements[name];
+        if (!m || !Array.isArray(m.inputs) || m.inputs.length === 0)
+            return false;
+    }
+    return true;
+}
+/** Repo-root POSIX paths that count as measured for RF-4.5 late-path checks. */
+function measuredPathSet(receipt) {
+    const out = new Set();
+    for (const p of receipt.alwaysMeasuredPaths)
+        out.add(p);
+    for (const m of Object.values(receipt.measurements)) {
+        for (const p of m.measuredPaths)
+            out.add(p);
+    }
+    return out;
+}
+function isRuntimeStatePath(rel) {
+    return worktree_1.RUNTIME_STATE_EXCLUDES.some((ex) => rel === ex || rel.startsWith(`${ex}/`));
+}
+/** True when a late path is measured: frozen set OR rematch against any measurement's inputs (RF-4.5). */
+function latePathIsMeasured(repoRel, receipt, frozen) {
+    if (frozen.has(repoRel))
+        return true;
+    for (const m of Object.values(receipt.measurements)) {
+        if ((0, inputs_digest_1.repoPathMatchesInputGlobs)(repoRel, m.packageRootRel, m.inputs))
+            return true;
+    }
+    return false;
+}
+/**
+ * Filter late files for Change Record validate (RF-4.5/4.6). Schema 1 and incomplete
+ * schema 2 keep today's strict rule (only `docs/changes/` carved out). Complete schema 2
+ * keeps paths in the frozen measured ∪ always-measured union OR matching authored inputs
+ * globs (so new matching sources after verify are not a false green). Runtime-state never counts.
+ */
+function filterLateFilesForReceipt(files, receipt, recordDirPrefix) {
+    const outsideRecords = files.filter((f) => !f.startsWith(`${recordDirPrefix}/`));
+    if (receipt === null || receipt.schema !== 2 || !allowsUnmeasuredRelaxation(receipt)) {
+        return outsideRecords;
+    }
+    const measured = measuredPathSet(receipt);
+    return outsideRecords.filter((f) => !isRuntimeStatePath(f) && latePathIsMeasured(f, receipt, measured));
+}
 /**
  * sha256 over the canonical JSON of the receipt without its digest, `sensors` being the name-sorted pairs of sensorPairs (R2.2c).
  * The digest is local (receipts are not versioned and are rewritten by every full run), so changing its canonical form only
@@ -56,9 +167,33 @@ function computeReceiptDigest(body) {
         throw new Error((0, text_safety_1.esc)('invalid receipt: digest body must be an object'));
     if (body.sensors === null || typeof body.sensors !== 'object' || Array.isArray(body.sensors))
         throw new Error((0, text_safety_1.esc)('invalid receipt: digest body sensors must be an object'));
+    if (body.schema === 1) {
+        const canonical = JSON.stringify({
+            schema: body.schema, commit: body.commit, ranAt: body.ranAt, cliVersion: body.cliVersion,
+            overall: body.overall, sensors: sensorPairs(body.sensors),
+        });
+        return 'sha256:' + crypto_1.default.createHash('sha256').update(canonical).digest('hex');
+    }
+    if (body.schema !== 2)
+        throw new Error((0, text_safety_1.esc)('invalid receipt: digest body schema must be 1 or 2'));
+    const v2 = body;
+    if (v2.measurements === null || typeof v2.measurements !== 'object' || Array.isArray(v2.measurements)) {
+        throw new Error((0, text_safety_1.esc)('invalid receipt: digest body measurements must be an object'));
+    }
+    if (!Array.isArray(v2.alwaysMeasuredPaths))
+        throw new Error((0, text_safety_1.esc)('invalid receipt: digest body alwaysMeasuredPaths must be an array'));
+    const measurements = Object.fromEntries(Object.entries(v2.measurements).sort(([a], [b]) => byName(a, b)).map(([name, m]) => [name, {
+            inputs: m.inputs,
+            packageRootRel: m.packageRootRel,
+            inputDigest: m.inputDigest,
+            sensorFingerprint: m.sensorFingerprint,
+            measuredPaths: m.measuredPaths,
+        }]));
     const canonical = JSON.stringify({
-        schema: body.schema, commit: body.commit, ranAt: body.ranAt, cliVersion: body.cliVersion,
-        overall: body.overall, sensors: sensorPairs(body.sensors),
+        schema: v2.schema, commit: v2.commit, ranAt: v2.ranAt, cliVersion: v2.cliVersion,
+        overall: v2.overall, sensors: sensorPairs(v2.sensors),
+        measurements,
+        alwaysMeasuredPaths: v2.alwaysMeasuredPaths,
     });
     return 'sha256:' + crypto_1.default.createHash('sha256').update(canonical).digest('hex');
 }
@@ -70,11 +205,12 @@ function receiptProblem(x) {
     if (x === null || typeof x !== 'object' || Array.isArray(x))
         return 'receipt must be an object';
     const r = x;
+    if (r.schema !== 1 && r.schema !== 2)
+        return 'schema must be 1 or 2';
+    const expectedKeys = r.schema === 1 ? RECEIPT_KEYS_V1 : RECEIPT_KEYS_V2;
     const keys = Object.keys(r);
-    if (keys.length !== RECEIPT_KEYS.length || !RECEIPT_KEYS.every((k) => k in r))
+    if (keys.length !== expectedKeys.length || !expectedKeys.every((k) => k in r))
         return 'receipt must have exactly the schema keys';
-    if (r.schema !== 1)
-        return 'schema must be 1';
     if (!(0, types_1.isCommitId)(r.commit))
         return 'commit must be 40 or 64 lowercase hex characters';
     if (!(0, text_safety_1.isCanonicalIso)(r.ranAt))
@@ -92,6 +228,28 @@ function receiptProblem(x) {
         if (!(0, types_1.isSensorStatus)(status))
             return 'a sensor status is not a known status';
     }
+    if (r.schema === 2) {
+        const measurements = r.measurements;
+        if (measurements === null || typeof measurements !== 'object' || Array.isArray(measurements))
+            return 'measurements must be an object';
+        for (const [name, value] of Object.entries(measurements)) {
+            if (!(0, types_1.isSensorName)(name))
+                return `measurement sensor names must be a single line of 1 to ${types_1.MAX_SENSOR_NAME} characters`;
+            const problem = measurementProblem(name, value);
+            if (problem !== null)
+                return problem;
+        }
+        if (!Array.isArray(r.alwaysMeasuredPaths) || r.alwaysMeasuredPaths.length > MAX_MEASURED_PATHS) {
+            return 'alwaysMeasuredPaths must be an array within bounds';
+        }
+        if (r.alwaysMeasuredPaths.some((p) => typeof p !== 'string' || !(0, inputs_digest_1.isSafeRepoRel)(p))) {
+            return 'alwaysMeasuredPaths must be safe repo-root POSIX paths';
+        }
+        const sortedAlways = sortedStrings(r.alwaysMeasuredPaths);
+        if (JSON.stringify(r.alwaysMeasuredPaths) !== JSON.stringify(sortedAlways)) {
+            return 'alwaysMeasuredPaths must be sorted';
+        }
+    }
     if (typeof r.digest !== 'string')
         return 'digest must be a string';
     const { digest, ...body } = r;
@@ -99,14 +257,66 @@ function receiptProblem(x) {
         return 'digest does not match the content';
     return null;
 }
-/** Builds a receipt and fails closed: throws an Error naming the problem when the result is not one `readReceipt` would accept. */
+function extractMeasurements(sensors) {
+    const out = {};
+    for (const sensor of sensors) {
+        const m = sensor.measurement;
+        if (!m || typeof m !== 'object')
+            continue;
+        if (!Array.isArray(m.inputs) || m.inputs.length === 0)
+            continue;
+        if (!isPackageRootRel(m.packageRootRel))
+            continue;
+        if (!isSha256Digest(m.inputDigest) || !isSha256Digest(m.sensorFingerprint))
+            continue;
+        if (!Array.isArray(m.measuredPaths) || m.measuredPaths.some((p) => typeof p !== 'string' || !(0, inputs_digest_1.isSafeRepoRel)(p)))
+            continue;
+        out[sensor.name] = {
+            inputs: [...m.inputs],
+            packageRootRel: m.packageRootRel,
+            inputDigest: m.inputDigest,
+            sensorFingerprint: m.sensorFingerprint,
+            measuredPaths: sortedStrings(m.measuredPaths),
+        };
+    }
+    return Object.fromEntries(Object.entries(out).sort(([a], [b]) => byName(a, b)));
+}
+/** Builds a schema-2 receipt (RF-4.3). Schema 1 remains readable via `readReceipt` / `writeReceipt`. */
 function buildReceipt(input) {
     const out = input === null || typeof input !== 'object' ? undefined : input.output;
     if (out === null || typeof out !== 'object' || !Array.isArray(out.sensors) || out.sensors.some((s) => s === null || typeof s !== 'object')) {
         throw new Error('invalid receipt: run output must carry a sensors array');
     }
     const sensors = sortedSensors(Object.fromEntries(out.sensors.map((s) => [s.name, s.status])));
-    const body = { schema: 1, commit: input.commit, ranAt: input.ranAt, cliVersion: input.cliVersion, overall: out.overall, sensors };
+    const measurements = extractMeasurements(out.sensors);
+    const alwaysFromSensors = new Set();
+    for (const sensor of out.sensors) {
+        const extras = sensor.measurement?.alwaysMeasuredPaths;
+        if (!Array.isArray(extras))
+            continue;
+        for (const p of extras) {
+            if (typeof p === 'string' && (0, inputs_digest_1.isSafeRepoRel)(p))
+                alwaysFromSensors.add(p);
+        }
+    }
+    const provided = Array.isArray(input.alwaysMeasuredPaths) ? input.alwaysMeasuredPaths : [];
+    for (const p of provided) {
+        if (typeof p === 'string' && (0, inputs_digest_1.isSafeRepoRel)(p))
+            alwaysFromSensors.add(p);
+    }
+    // Validate always-measured always includes baseline (RF-2.12 / RF-4.5), even when empty.
+    alwaysFromSensors.add(inputs_digest_1.CACHE_DIGEST_BASELINE_REL);
+    const alwaysMeasuredPaths = sortedStrings([...alwaysFromSensors]);
+    const body = {
+        schema: 2,
+        commit: input.commit,
+        ranAt: input.ranAt,
+        cliVersion: input.cliVersion,
+        overall: out.overall,
+        sensors,
+        measurements,
+        alwaysMeasuredPaths,
+    };
     const receipt = { ...body, digest: computeReceiptDigest(body) };
     const problem = receiptProblem(receipt);
     if (problem !== null)

package/dist/src/core/changes/worktree.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REASON_GIT_FAILED = exports.REASON_NOT_REPO = exports.RUNTIME_STATE_EXCLUDES = void 0;
 exports.gitState = gitState;
+exports.treeDirty = treeDirty;
 const path_1 = __importDefault(require("path"));
 const git_env_1 = require("./git-env");
 const text_safety_1 = require("./text-safety");
@@ -39,15 +40,26 @@ function gitState(cwd, untracked, extraExcludes = []) {
     catch (error) {
         return gitFailure(error);
     }
+    const dirty = treeDirty(root, untracked, extraExcludes);
+    return dirty === null ? { kind: 'failed' } : { kind: 'ok', root, commit, dirty };
+}
+/**
+ * Only the dirty measure of `gitState`, for a caller that already knows the repository root and does not need HEAD: one
+ * `status` instead of three git processes. Null when git fails or an exclusion is unsafe (the caller fails closed). Never throws.
+ */
+function treeDirty(root, untracked, extraExcludes = []) {
+    if (typeof root !== 'string' || root.length === 0)
+        return null;
+    if (!Array.isArray(extraExcludes) || extraExcludes.length > MAX_EXTRA_EXCLUDES || !extraExcludes.every(text_safety_1.isSafeRelativePath))
+        return null;
     try {
         // Submodules are never hidden by config (`.gitmodules` ignore=all, diff.ignoreSubmodules). The pre-run measure counts everything
         // (`none`); the post-run recheck is about tracked files only, so it also ignores untracked content inside a submodule
         // (sensor build/coverage output) while still seeing a moved checkout or modified tracked content (`untracked`).
         const args = ['status', '--porcelain', untracked ? '--untracked-files=normal' : '--untracked-files=no', untracked ? '--ignore-submodules=none' : '--ignore-submodules=untracked', '--', '.', ...exports.RUNTIME_STATE_EXCLUDES.map((p) => `:(exclude)${p}`), ...extraExcludes.map((p) => `:(exclude,literal)${p}`)];
-        const status = (0, git_env_1.execGit)(root, args, { stderr: 'ignore', maxBuffer: MAX_GIT_OUTPUT });
-        return { kind: 'ok', root, commit, dirty: status.trim().length > 0 };
+        return (0, git_env_1.execGit)(root, args, { stderr: 'ignore', maxBuffer: MAX_GIT_OUTPUT }).trim().length > 0;
     }
     catch {
-        return { kind: 'failed' };
+        return null;
     }
 }

package/dist/src/core/init/steps.js

@@ -162,21 +162,16 @@ async function stepCache(d) {
         return failed('machine.cache', 'machine', msg);
     }
     // `syncRegistries()` reports per-registry failures as RESULTS, not throws
-    // (registries.ts), so the `try` above catches none of them. Ignoring them
-    // is what let an unavailable base registry degrade silently into some
-    // later step's failure — with its own cause already gone.
+    // (registries.ts), so the `try` above catches none of them. SG-7: init must
+    // fail closed on ANY sync/clone failure (usable on-disk cache is not enough).
     const errors = (0, registries_1.registrySyncErrors)(results);
     if (errors.length === 0)
         return ok('machine.cache', 'machine', 'applied');
-    // A registry that errored and has no content on disk is unusable, and every
-    // later step that reads it will fail for a reason that no longer names this
-    // cause — so machine.cache owns it here. One that errored but still has
-    // content is stale, not broken: record it and carry on.
     const unusable = (0, registries_1.unusableSyncedRegistries)(results);
     if (unusable.length > 0) {
         return failed('machine.cache', 'machine', `registry unavailable — ${(0, registries_1.describeRegistrySyncErrors)(unusable)}`);
     }
-    return ok('machine.cache', 'machine', 'applied', `stale registries — ${(0, registries_1.describeRegistrySyncErrors)(errors)}`);
+    return failed('machine.cache', 'machine', `registry sync failed — ${(0, registries_1.describeRegistrySyncErrors)(errors)}`);
 }
 /** Step 2 – Install the session-start hook for the target agent. */
 function stepHook(d) {

package/dist/src/core/registries.js

@@ -30,8 +30,9 @@ exports.assertRegistryGates = assertRegistryGates;
 // src/core/registries.ts
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const simple_git_1 = __importDefault(require("simple-git"));
 const registry_1 = require("./registry");
+const registry_git_1 = require("./registry-git");
+const registry_git_errors_1 = require("./registry-git-errors");
 const versioning_1 = require("./versioning");
 const cli_version_1 = require("./cli-version");
 const paths_1 = require("./paths");
@@ -229,8 +230,10 @@ function registriesNeedSync() {
     return listRegistries().some((registry) => !validateRegistryLayout(registry.contentRoot));
 }
 /** Sincroniza cada registry configurado al ref resuelto (pin > último tag > HEAD);
- *  re-clona si falta el dir. Errores por-registry NO fatales: se reportan en el resultado. */
+ *  re-clona si falta el dir. Errores por-registry se reportan en el resultado (clasificados SG-6);
+ *  si el llamador debe abortar lo decide la política SG-7 del comando. */
 async function syncRegistries() {
+    (0, registry_git_1.warnIgnoredGitEnvOnce)();
     const results = [];
     for (const reg of listRegistries()) {
         try {
@@ -241,7 +244,7 @@ async function syncRegistries() {
             if (freshClone) {
                 fs_1.default.mkdirSync(registriesDir(), { recursive: true });
                 try {
-                    await (0, simple_git_1.default)().clone(reg.remote, reg.contentRoot);
+                    await (0, registry_git_1.createRegistryGit)().clone(reg.remote, reg.contentRoot);
                 }
                 catch (e) {
                     fs_1.default.rmSync(reg.contentRoot, { recursive: true, force: true });
@@ -249,9 +252,9 @@ async function syncRegistries() {
                 }
             }
             else {
-                await (0, simple_git_1.default)(reg.contentRoot).reset(['--hard']);
+                await (0, registry_git_1.createRegistryGit)(reg.contentRoot).reset(['--hard']);
             }
-            const git = (0, simple_git_1.default)(reg.contentRoot);
+            const git = (0, registry_git_1.createRegistryGit)(reg.contentRoot);
             const previousVersion = freshClone ? null : await (0, versioning_1.currentVersion)(reg.contentRoot);
             const versionOpts = (0, versioning_1.machineVersionOpts)(reg.name);
             let resolved;
@@ -290,7 +293,11 @@ async function syncRegistries() {
             });
         }
         catch (e) {
-            results.push({ name: reg.name, action: 'error', error: e instanceof Error ? e.message : String(e) });
+            results.push({
+                name: reg.name,
+                action: 'error',
+                error: (0, registry_git_errors_1.formatClassifiedRegistryFailure)({ name: reg.name, remote: reg.remote, err: e }),
+            });
         }
     }
     return results;
@@ -309,15 +316,13 @@ function describeRegistrySyncErrors(errors) {
  * Registries that both errored during sync AND no longer have a usable content
  * layout afterwards — i.e. genuinely unusable, as opposed to merely stale.
  *
- * `syncRegistries()` deliberately reports per-registry failures as results
- * rather than throwing, so a flaky secondary registry never aborts a whole
- * run. Callers that go on to READ registry content (init) still need to know
- * whether what they are about to read remains usable: otherwise a missing,
- * empty, or unsafe registry
- * resurfaces much later as an unrelated step's failure, with its real cause
- * already discarded. Note that "usable" is deliberately about content on disk,
- * not about being a healthy git clone — a seeded content root with no `.git`
- * fails to sync every time and is still perfectly readable.
+ * `syncRegistries()` still reports per-registry failures as results rather than
+ * throwing (so callers can classify/format each one). Under SG-7, init / update /
+ * sync / registry add exit non-zero on ANY sync error; add / list may continue
+ * only when cached content remains usable — and this helper is what those soft
+ * paths consult. "Usable" is about content on disk, not a healthy git clone —
+ * a seeded content root with no `.git` fails to sync every time and is still
+ * readable.
  */
 function unusableSyncedRegistries(results) {
     const errors = registrySyncErrors(results);

package/dist/src/core/registry-git-errors.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactRemoteForDisplay = redactRemoteForDisplay;
+exports.extractFatalLine = extractFatalLine;
+exports.classifyRegistryGitError = classifyRegistryGitError;
+exports.formatClassifiedRegistryFailure = formatClassifiedRegistryFailure;
+const registry_git_1 = require("./registry-git");
+const text_safety_1 = require("./changes/text-safety");
+const REMEDIES = {
+    authentication: 'configure credential.helper (awm ignores ambient GIT_ASKPASS)',
+    tls: 'git config --global http.sslCAInfo <path> or http.sslCAPath (awm ignores ambient GIT_SSL_*)',
+    network: 'check connectivity / proxy via git config --global http.proxy (awm does not pass ambient GIT_* proxy vars)',
+    ssh: 'set core.sshCommand or ~/.ssh/config (awm ignores ambient GIT_SSH_COMMAND)',
+    'not-found': 'verify the remote URL and that the repository exists and is reachable',
+    // simple-git `timeout.block` resets on stdout/stderr activity — idle bound, not wall-clock.
+    // Only the plugin's "block timeout reached" is this class (audit M1); git/curl "timed out" → network.
+    timeout: `check network connectivity; registry git children are killed after ${registry_git_1.REGISTRY_GIT_TIMEOUT_MS / 1000}s `
+        + 'without stdout/stderr activity',
+};
+/**
+ * Strip credential-bearing userinfo from a remote URL (or URL-shaped substring) before
+ * echoing it to operators. HTTPS `user:token@host` / `user@host` → scheme://host… only.
+ * Does not JSON-escape or clip — callers run `cleanText`/`clipMessage`/`esc` for echo safety.
+ */
+function redactRemoteForDisplay(remote) {
+    if (typeof remote !== 'string' || !remote)
+        return '';
+    // https://user:pass@host/... or https://user@host/...
+    return remote.replace(/\b([a-z][a-z0-9+.-]*:\/\/)([^/@\s]+)@/gi, '$1');
+}
+function errorText(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+/** Extract the last line that looks like git's `fatal: …` diagnostic. */
+function extractFatalLine(text) {
+    const lines = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (/^fatal:/i.test(lines[i]))
+            return lines[i];
+    }
+    return null;
+}
+/**
+ * Map a registry git failure to a stable class + file-based remedy (SG-6).
+ * Heuristics are substring-based on message/stderr; never includes env values.
+ */
+function classifyRegistryGitError(err) {
+    const message = errorText(err);
+    const fatalLine = extractFatalLine(message);
+    let errorClass;
+    // Audit M1: only simple-git's idle-block plugin text is `timeout`. Git/curl
+    // "Connection timed out" / "timed out" are connectivity → `network`.
+    if (/block timeout reached/i.test(message)) {
+        errorClass = 'timeout';
+    }
+    else if (/ssl|tls|certificate|unable to get local issuer|certificate verify failed/i.test(message)) {
+        errorClass = 'tls';
+    }
+    else if (
+    // Score repository-shaped not-found BEFORE broad SSH wording — GitHub SSH
+    // often pairs "Repository not found" with "Could not read from remote repository".
+    /repository not found|remote:\s*.*not found|fatal:\s*repository .+ not found|404\b/i.test(message)) {
+        errorClass = 'not-found';
+    }
+    else if (/host key verification|permission denied \(publickey\)/i.test(message)) {
+        errorClass = 'ssh';
+    }
+    else if (
+    // Remaining SSH transport wording — but DNS/timeout under ssh: belongs to network.
+    /\bssh\b/i.test(message)
+        && !/could not resolve|name or service not known|timed?\s*out|connection timed out|terminal prompts disabled|authentication failed|could not read username/i.test(message)) {
+        errorClass = 'ssh';
+    }
+    else if (/terminal prompts disabled|authentication failed|could not read username|auth(entication)? (fail|required)|401\b|403\b|invalid credentials/i.test(message)) {
+        errorClass = 'authentication';
+    }
+    else if (/could not resolve host|could not resolve hostname|failed to connect|connection refused|network is unreachable|unable to connect|proxy|name or service not known|timed?\s*out|connection timed out/i.test(message)) {
+        errorClass = 'network';
+    }
+    else {
+        // Default: treat unknown transport failures as network.
+        errorClass = 'network';
+    }
+    const rawFatal = fatalLine ?? (message.trim() ? message.trim().split(/\r?\n/).pop().slice(0, 240) : null);
+    return {
+        class: errorClass,
+        fatalLine: rawFatal === null ? null : redactRemoteForDisplay(rawFatal),
+        remedy: REMEDIES[errorClass],
+    };
+}
+/**
+ * Operator-facing SG-6 line: registry name, remote when known, class, fatal, remedy.
+ * Never includes ambient env values or URL userinfo credentials.
+ */
+function formatClassifiedRegistryFailure(opts) {
+    const classified = classifyRegistryGitError(opts.err);
+    const remotePart = opts.remote
+        ? `; remote=${(0, text_safety_1.clipMessage)((0, text_safety_1.cleanText)(redactRemoteForDisplay(opts.remote)))}`
+        : '';
+    const fatalPart = classified.fatalLine
+        ? `; fatal: ${(0, text_safety_1.clipMessage)((0, text_safety_1.cleanText)(classified.fatalLine.replace(/^fatal:\s*/i, '')))}`
+        : '';
+    return (`registry ${(0, text_safety_1.esc)(opts.name)} sync failed (class=${classified.class}${remotePart}${fatalPart}); `
+        + `remedy: ${classified.remedy}`);
+}

package/dist/src/core/registry-git.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGISTRY_GIT_TIMEOUT_MS = void 0;
+exports.buildRegistryGitEnv = buildRegistryGitEnv;
+exports.listIgnoredGuardedGitEnvNames = listIgnoredGuardedGitEnvNames;
+exports.formatIgnoredGitEnvNotice = formatIgnoredGitEnvNotice;
+exports.resetIgnoredGitEnvNoticeForTests = resetIgnoredGitEnvNoticeForTests;
+exports.warnIgnoredGitEnvOnce = warnIgnoredGitEnvOnce;
+exports.createRegistryGit = createRegistryGit;
+const simple_git_1 = require("simple-git");
+exports.REGISTRY_GIT_TIMEOUT_MS = 60_000;
+/**
+ * Non-`GIT_*` keys that simple-git 4 treats as guarded when supplied via `.env()`.
+ * Omit them from the copy so `.env(copy)` does not reject (editor/pager/visual family).
+ * Kept in sync with `@simple-git/argv-parser` GitEnvKeys non-prefix entries.
+ */
+const NON_PREFIX_GUARDED_ENV = new Set(['editor', 'pager', 'prefix', 'ssh_askpass', 'visual']);
+/**
+ * Ambient names that affect registry transport/auth and are stripped by the factory.
+ * SG-5 warns only for these (audit M2) — not GIT_EDITOR / GIT_PAGER / GIT_AUTHOR_*.
+ * Includes SSH_ASKPASS (audit B2), which simple-git also guards without a GIT_ prefix.
+ */
+function isTransportRelevantIgnoredEnv(key) {
+    const lower = key.toLowerCase();
+    if (lower === 'ssh_askpass')
+        return true;
+    if (!lower.startsWith('git_'))
+        return false;
+    if (lower === 'git_terminal_prompt')
+        return false;
+    return (lower.startsWith('git_ssl_')
+        || lower === 'git_askpass'
+        || lower.startsWith('git_ssh')
+        || lower.startsWith('git_proxy')
+        || lower.startsWith('git_http_')
+        || lower.startsWith('git_curl_')
+        || lower.startsWith('git_config'));
+}
+/** Copy parent env without guarded GIT_* / editor keys, then force non-interactive prompts. */
+function buildRegistryGitEnv(parent = process.env) {
+    const env = {};
+    for (const [key, value] of Object.entries(parent)) {
+        if (value === undefined)
+            continue;
+        const lower = key.toLowerCase();
+        if (lower.startsWith('git_'))
+            continue;
+        if (NON_PREFIX_GUARDED_ENV.has(lower))
+            continue;
+        env[key] = value;
+    }
+    env.GIT_TERMINAL_PROMPT = '0';
+    return env;
+}
+/** Names of stripped transport/auth vars worth warning about (SG-5) — never values. */
+function listIgnoredGuardedGitEnvNames(parent = process.env) {
+    return Object.keys(parent)
+        .filter((key) => isTransportRelevantIgnoredEnv(key))
+        .sort((a, b) => a.localeCompare(b));
+}
+/** Operator notice for SG-5 — names only, never values. */
+function formatIgnoredGitEnvNotice(names) {
+    const listed = names.join(', ');
+    return (`⚠ Ignoring ambient transport/auth env vars: ${listed}. `
+        + 'Use file-based git config instead '
+        + '(e.g. git config --global http.sslCAInfo <path>, credential.helper, core.sshCommand / ~/.ssh/config).');
+}
+let ignoredGitEnvWarned = false;
+/** Test seam: clear the once-per-process SG-5 flag. */
+function resetIgnoredGitEnvNoticeForTests() {
+    ignoredGitEnvWarned = false;
+}
+/**
+ * Before the first network registry git op: warn once listing ignored ambient
+ * transport/auth env names (except GIT_TERMINAL_PROMPT) and point at file-based remedies (SG-5).
+ */
+function warnIgnoredGitEnvOnce(log = (message) => console.warn(message), parent = process.env) {
+    if (ignoredGitEnvWarned)
+        return;
+    const names = listIgnoredGuardedGitEnvNames(parent);
+    if (names.length === 0)
+        return;
+    ignoredGitEnvWarned = true;
+    log(formatIgnoredGitEnvNotice(names));
+}
+function createRegistryGit(baseDir) {
+    const git = (0, simple_git_1.simpleGit)({
+        ...(baseDir !== undefined ? { baseDir } : {}),
+        allowEnvironment: ['GIT_TERMINAL_PROMPT'],
+        timeout: { block: exports.REGISTRY_GIT_TIMEOUT_MS },
+    });
+    return git.env(buildRegistryGitEnv());
+}