@stravica-ai/digital-operator-pa 0.1.66 → 0.1.68

package/dist/engineering-pa-cli/docs/coordinator-hook.md

@@ -156,6 +156,19 @@ quietly widen the policy.
 Wire the hook up in your OWN `~/.claude/settings.json` (per-machine operator
 territory — this package never writes to it):
 
+The command is the launcher the scaffold writes into a new instance's
+`.claude/settings.json` (copy it from that file): it walks up from
+`$CLAUDE_PROJECT_DIR` to the nearest installed
+`node_modules/@stravica-ai/digital-operator-pa/bin/pa-coordinator-hook` and
+needs only `node` on the hook PATH.
+
+This launcher, like the other PreToolUse gate, has no stdout latch. The
+scaffold's SessionStart launchers do: once their bin has written a byte to
+fd 1 they print nothing of their own. That latch counts only
+`process.stdout.write` and `fs.writeSync` to fd 1, so a SessionStart bin that
+writes with async `fs.write`, `fs.writev` or `fs.writeFileSync(1)` bypasses
+it. No shipped bin writes that way.
+
 ```jsonc
 {
   "hooks": {
@@ -165,7 +178,7 @@ territory — this package never writes to it):
         "hooks": [
           {
             "type": "command",
-            "command": "pa-coordinator-hook"
+            "command": "node -e 'var P=require(\"path\"),d=process.env.CLAUDE_PROJECT_DIR,q=\"node_modules/@stravica-ai/digital-operator-pa/bin/pa-coordinator-hook\",y=e=>x(e?.message||e),x=r=>process.exit(console.error(\"pa-coordinator-hook could not run: \"+r)|1);for(var c=P.resolve(d||x(\"no CLAUDE_PROJECT_DIR\")),b,n;!require(\"fs\").existsSync(b=P.join(c,q));c=n)if(c==(n=P.dirname(c)))x(\"no \"+q+\" above \"+d);process.argv.splice(1,0,b);import(require(\"url\").pathToFileURL(b)).catch(e=>process.listenerCount(\"uncaughtException\")?process.nextTick(()=>{throw e}):y(e))'"
           }
         ]
       }

package/dist/engineering-pa-cli/src/agent/cli.mjs

@@ -18,7 +18,9 @@
 //
 // Cache: <repo-root>/.session/agent-audit.json.
 // Staleness: 60 minutes, override via operator/config/preferences.json:
-//            agentAudit.cacheStalenessMinutes.
+//            agentAudit.cacheStalenessMinutes. A cache whose manifestVersion
+//            differs from the bundled manifest's (or that has none) is stale
+//            at any age, so a package update shows new capabilities at once.
 //
 // Performance target: cache-read <2s (session-boot budget), refresh <3s
 // on a real estate. All probes are Node-only synchronous, so the whole
@@ -52,7 +54,8 @@ Global flags:
 
 Cache file: <repo-root>/.session/agent-audit.json.
 Staleness threshold: 60 minutes (override via operator/config/preferences.json:
-agentAudit.cacheStalenessMinutes).
+agentAudit.cacheStalenessMinutes). A cache written under another manifest
+version is rebuilt at any age.
 
 Exit codes (tooling standard §6):
   0 ok | 1 usage | 2 unresolvable state | 2 --strict fail
@@ -129,11 +132,12 @@ async function runAudit({ flags, forceRefresh }) {
     err.exitCode = 2;
     throw err;
   }
+  const manifest = loadBundledManifestSync();
   const cached = forceRefresh ? null : readCache(cachePath);
-  const stale = cached ? isStale(cached, staleness) : true;
+  const stale = cached ? isStale(cached, staleness, manifest.manifestVersion) : true;
   let audit;
   if (!cached || stale) {
-    audit = performAudit({ repoRoot, paName });
+    audit = performAudit({ repoRoot, paName, manifest });
     writeCache(cachePath, audit);
   } else {
     audit = cached;
@@ -153,8 +157,8 @@ async function runAudit({ flags, forceRefresh }) {
  * Perform a fresh audit — pure orchestration around the manifest loader
  * and the audit runner. Exported for the boot-context hook and tests.
  */
-export function performAudit({ repoRoot, paName, now, hostname }) {
-  const manifest = loadBundledManifestSync();
+export function performAudit({ repoRoot, paName, now, hostname, manifest }) {
+  manifest = manifest ?? loadBundledManifestSync();
   const ctx = {
     repoRoot,
     paName,
@@ -192,11 +196,17 @@ function writeCache(path, cache) {
   }
 }
 
-function isStale(cache, stalenessMinutes) {
+/**
+ * A cache is stale when it was written under another manifest version (or
+ * carries none), so an upgraded package never serves the old capability
+ * list, or when it is older than the staleness threshold.
+ */
+export function isStale(cache, stalenessMinutes, manifestVersion, nowMs = Date.now()) {
+  if (cache?.manifestVersion === undefined || cache.manifestVersion !== manifestVersion) return true;
   if (!cache?.capturedAt) return true;
   const capturedMs = Date.parse(cache.capturedAt);
   if (!Number.isFinite(capturedMs)) return true;
-  const ageMs = Date.now() - capturedMs;
+  const ageMs = nowMs - capturedMs;
   return ageMs > stalenessMinutes * 60 * 1000;
 }
 

package/dist/engineering-pa-cli/src/agent/probes.mjs

@@ -33,6 +33,8 @@ export function runProbe(probe, ctx) {
       case 'knowledge-doc-exists': return probeKnowledgeDocExists(probe, ctx);
       case 'schedule-defined':     return probeScheduleDefined(probe, ctx);
       case 'json-field-includes':  return probeJsonFieldIncludes(probe, ctx);
+      case 'settings-hook-includes': return probeSettingsHookIncludes(probe, ctx);
+      case 'file-includes':        return probeFileIncludes(probe, ctx);
       default:
         return {
           outcome: UNVERIFIED,
@@ -234,3 +236,95 @@ function probeJsonFieldIncludes(probe, ctx) {
   }
   return { outcome: PASS, detail: `${rel}: '${field}' includes ${JSON.stringify(value)}` };
 }
+
+function probeSettingsHookIncludes(probe, ctx) {
+  // Reads every candidate that exists: `path` (the scaffold writes
+  // `.claude/settings.json` at the repo root) and each `altPaths` entry
+  // (an agent-folder settings file). A session may load only one of them,
+  // so the probe passes when any candidate holds the hook: some entry under
+  // `hooks.<event>` with a matcher containing `matcherIncludes` and a
+  // command hook whose command contains every `commandIncludes` string.
+  // A candidate that is not valid JSON (or cannot be read) does not stop
+  // the search. With no pass, the result is unverified-here when some
+  // candidate was invalid, else fail; the detail names each candidate read.
+  // No candidate at all fails.
+  const candidates = [...new Set([probe.path, ...(Array.isArray(probe.altPaths) ? probe.altPaths : [])]
+    .filter((p) => typeof p === 'string' && p.length > 0)
+    .map((p) => expandTemplate(p, ctx)))];
+  const present = candidates.filter((r) => existsSync(join(ctx.repoRoot, r)));
+  if (!present.length) {
+    return { outcome: FAIL, detail: `settings file missing: ${candidates.join(' or ')}` };
+  }
+  const misses = [];
+  let invalid = false;
+  for (const rel of present) {
+    const r = settingsFileHook(rel, probe, ctx);
+    if (r.pass) return { outcome: PASS, detail: r.detail };
+    if (r.invalid) invalid = true;
+    misses.push(r.detail);
+  }
+  return { outcome: invalid ? UNVERIFIED : FAIL, detail: misses.join('; ') };
+}
+
+/** One settings file: { pass, invalid, detail }. Never throws. */
+function settingsFileHook(rel, probe, ctx) {
+  let text;
+  try {
+    text = readFileSync(join(ctx.repoRoot, rel), 'utf8');
+  } catch (err) {
+    return { pass: false, invalid: true, detail: `${rel} could not be read: ${err.message}` };
+  }
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch (err) {
+    return { pass: false, invalid: true, detail: `${rel} not valid JSON: ${err.message}` };
+  }
+  const event = probe.event;
+  const wants = Array.isArray(probe.commandIncludes) ? probe.commandIncludes : [];
+  const matcherWant = typeof probe.matcherIncludes === 'string' ? probe.matcherIncludes : null;
+  const entries = doc?.hooks?.[event];
+  if (!Array.isArray(entries)) {
+    return { pass: false, invalid: false, detail: `${rel}: no hooks.${event} entries` };
+  }
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object') continue;
+    const matcher = typeof entry.matcher === 'string' ? entry.matcher : '';
+    if (matcherWant !== null && !matcher.includes(matcherWant)) continue;
+    for (const hook of Array.isArray(entry.hooks) ? entry.hooks : []) {
+      if (!hook || hook.type !== 'command' || typeof hook.command !== 'string') continue;
+      if (wants.every((w) => hook.command.includes(w))) {
+        return { pass: true, invalid: false, detail: `${rel}: hooks.${event} matcher ${JSON.stringify(matcher)} runs ${JSON.stringify(hook.command)}` };
+      }
+    }
+  }
+  const matcherText = matcherWant === null ? '' : ` with a matcher containing ${JSON.stringify(matcherWant)}`;
+  return {
+    pass: false,
+    invalid: false,
+    detail: `${rel}: no hooks.${event} entry${matcherText} runs a command containing ${JSON.stringify(wants)}`,
+  };
+}
+
+function probeFileIncludes(probe, ctx) {
+  const rel = expandTemplate(probe.path, ctx);
+  const abs = join(ctx.repoRoot, rel);
+  if (!existsSync(abs)) {
+    return { outcome: FAIL, detail: `missing: ${rel}` };
+  }
+  let text;
+  try {
+    if (!statSync(abs).isFile()) {
+      return { outcome: FAIL, detail: `path exists but is not a file: ${rel}` };
+    }
+    text = readFileSync(abs, 'utf8');
+  } catch (err) {
+    return { outcome: UNVERIFIED, detail: `read failed for ${rel}: ${err.message}` };
+  }
+  const wants = Array.isArray(probe.includes) ? probe.includes : [];
+  const missing = wants.filter((w) => !text.includes(w));
+  if (missing.length) {
+    return { outcome: FAIL, detail: `${rel} does not include ${JSON.stringify(missing)}` };
+  }
+  return { outcome: PASS, detail: `${rel} includes ${JSON.stringify(wants)}` };
+}