@event4u/agent-config 9.27.0 → 9.28.0

package/src/scripts/_cli/cmd_settings_get.ts

@@ -0,0 +1,324 @@
+/**
+ * `agent-config settings:get <key>` — the value, and the file it came from.
+ *
+ * Phase 2.2 of `road-to-capability-answerability`, and the general answer to
+ * five separate settings-key defects rather than five prose edits. Before this
+ * verb, "what is this setting, and which file did it come from" was unanswerable
+ * by any command: `settings:check` validates, `settings:sync` merges,
+ * `settings:set` writes, and the one function that computes exactly
+ * `[key, value, source_path]` — `iter_setting_overrides` — had a test and no
+ * production caller at all. This exposes it.
+ *
+ * Read-only BY CONSTRUCTION, which is a design constraint and not a promise:
+ * this module imports no writer, opens no file for writing, and has no flag
+ * that could. The roadmap's Risk 3 names the failure it is avoiding — a read
+ * verb inviting a write verb until the C-class fence in `settings:set` has a
+ * general bypass beside it.
+ *
+ * Four things are reported, and the last two are why it is a probe:
+ *
+ * - **the effective value**, resolved through the same cascade the loader walks;
+ * - **the winning source path**, plus every layer that set the key, so a
+ *   surprising value can be traced to the file that caused it;
+ * - **absent ≠ default**, for the nine carved-out keys where a reader resolves
+ *   an absent key to something other than the template's default. Reporting
+ *   "not set" for `quality.local_auto_run` without saying that absent DISARMS
+ *   the gate the template arms would be a true statement that misleads;
+ * - **the silent whitelist drop**. `load_agent_settings` filters the user-global
+ *   layer through `MERGEABLE_KEYS` and discards everything else without a word.
+ *   A user who sets a non-whitelisted key user-globally gets no error, no
+ *   warning, and no effect. This verb says so.
+ *
+ * Exit codes: `0` answered (including "not set anywhere", which is an answer) ·
+ * `2` usage error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { load as yamlLoad } from 'js-yaml';
+
+import {
+    iter_setting_overrides,
+    load_agent_settings,
+    MERGEABLE_KEYS,
+    USER_GLOBAL_FILENAME,
+} from '../_lib/agent_settings.js';
+import { resolve_with_fallback, write_target } from '../_lib/user_global_paths.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
+import { SETTINGS_CARVE_OUT, type CarveOutKey } from '../../shared/settingsCarveOut.js';
+import {
+    buildSettingsClassIndex,
+    classOfPath,
+    getSettingsLeaf,
+    parseSettingsClassRows,
+    type SettingsClass,
+} from '../../shared/settingsClasses.js';
+
+const PACKAGE_ROOT = resolvePackageRoot(import.meta.url);
+
+/** Where the class contract ships, relative to the package root. */
+const CONTRACT_RELATIVE = 'docs/contracts/settings-classes.md';
+
+/** Where the shipped defaults live, relative to the package root. */
+const TEMPLATE_RELATIVE = path.join('src', 'config', 'agent-settings.template.yml');
+
+/**
+ * Key shapes whose VALUE is never printed, only its presence.
+ *
+ * A general settings reader is a general secret reader unless it is told
+ * otherwise, and the settings tree really does carry credentials — the
+ * user-global file on the machine this was built on holds
+ * `secrets.link_encryption_key`. The roadmap does not ask for this; it is the
+ * cross-cutting control the surface implies, and adding it after the verb
+ * shipped would mean the leak existed first.
+ *
+ * Matched on the dotted path, so both `secrets.*` and any leaf named like a
+ * credential are covered regardless of where they sit.
+ */
+const SECRET_KEY_RE = /(^|\.)(secrets?)(\.|$)|(^|\.)[a-z0-9_]*(api_key|token|password|passwd|secret|credential|private_key|encryption_key)$/i;
+
+/** `true` when the value for this dotted key must be masked in output. */
+export function isSecretKey(key: string): boolean {
+    return SECRET_KEY_RE.test(key);
+}
+
+/** The value as printed: masked for credential-shaped keys, verbatim otherwise. */
+export function displayValue(key: string, value: unknown): unknown {
+    if (value === undefined || value === null) return value;
+    return isSecretKey(key) ? '«redacted — credential-shaped key»' : value;
+}
+
+/** One layer that set the key, in cascade order (later wins). */
+export interface SettingsLayer {
+    value: unknown;
+    file: string;
+}
+
+export interface SettingsGetOptions {
+    key: string;
+    cwd: string;
+    packageRoot: string;
+    json: boolean;
+}
+
+export interface SettingsGetResult {
+    code: 0 | 2;
+    out: string[];
+    err: string[];
+}
+
+/**
+ * Every layer that set `key`, in cascade order.
+ *
+ * Delegates to `iter_setting_overrides` rather than re-walking the cascade:
+ * a probe that computed its own answer could disagree with the loader, and a
+ * settings probe that disagrees with the loader is worse than no probe.
+ */
+export function layersFor(key: string, cwd: string): SettingsLayer[] {
+    const layers: SettingsLayer[] = [];
+    for (const [dotted, value, file] of iter_setting_overrides({ cwd })) {
+        if (dotted === key) layers.push({ value, file });
+    }
+    return layers;
+}
+
+/** The template's shipped default for `key`, or `undefined` when it has none. */
+export function templateDefault(packageRoot: string, key: string): unknown {
+    let parsed: unknown;
+    try {
+        parsed = yamlLoad(fs.readFileSync(path.join(packageRoot, TEMPLATE_RELATIVE), 'utf-8'));
+    } catch {
+        return undefined;
+    }
+    return getSettingsLeaf(parsed, key);
+}
+
+/** The carve-out row for `key`, when absent does not mean the template default. */
+export function carveOutFor(key: string): CarveOutKey | undefined {
+    return SETTINGS_CARVE_OUT.find((c) => c.key === key);
+}
+
+/**
+ * `true` when the key is present in the user-global file but is NOT whitelisted,
+ * i.e. the loader read it and threw it away.
+ *
+ * Returns the resolved user-global path alongside so the report can name the
+ * file the user actually edited — telling somebody their value was dropped
+ * without telling them which file it was dropped from is half an answer.
+ */
+export function userGlobalDrop(key: string): { dropped: boolean; file: string } {
+    const file = resolve_with_fallback(USER_GLOBAL_FILENAME) ?? write_target(USER_GLOBAL_FILENAME);
+    if (MERGEABLE_KEYS.includes(key)) return { dropped: false, file };
+    let raw: unknown;
+    try {
+        raw = yamlLoad(fs.readFileSync(file, 'utf-8'));
+    } catch {
+        return { dropped: false, file };
+    }
+    return { dropped: getSettingsLeaf(raw, key) !== undefined, file };
+}
+
+/**
+ * The class governing `key`, or `null` when the contract is unreadable or has
+ * no row on the path.
+ *
+ * `classOfPath` rather than an exact lookup: a class-C key whose value is a map
+ * has children that never appear as their own rows, and reporting them as
+ * unclassified would understate the fence around them.
+ */
+function _classFor(packageRoot: string, key: string): SettingsClass | null {
+    let text: string;
+    try {
+        text = fs.readFileSync(path.join(packageRoot, CONTRACT_RELATIVE), 'utf-8');
+    } catch {
+        return null;
+    }
+    return classOfPath(buildSettingsClassIndex(parseSettingsClassRows(text)), key) ?? null;
+}
+
+export function runSettingsGet(opts: SettingsGetOptions): SettingsGetResult {
+    const out: string[] = [];
+    const err: string[] = [];
+
+    const merged = load_agent_settings({ cwd: opts.cwd });
+    const effective = getSettingsLeaf(merged, opts.key);
+    const layers = layersFor(opts.key, opts.cwd);
+    const winning = layers.length > 0 ? (layers[layers.length - 1] as SettingsLayer) : null;
+    const cls = _classFor(opts.packageRoot, opts.key);
+    const fallback = templateDefault(opts.packageRoot, opts.key);
+    const carveOut = carveOutFor(opts.key);
+    const drop = userGlobalDrop(opts.key);
+
+    if (opts.json) {
+        out.push(
+            JSON.stringify(
+                {
+                    key: opts.key,
+                    value: displayValue(opts.key, effective) ?? null,
+                    redacted: isSecretKey(opts.key),
+                    set: winning !== null,
+                    source: winning?.file ?? null,
+                    layers: layers.map((l) => ({ value: displayValue(opts.key, l.value), file: l.file })),
+                    class: cls,
+                    template_default: fallback ?? null,
+                    absent_is_not_default: carveOut
+                        ? { resolves_to: carveOut.absentResolvesTo, reader: carveOut.reader }
+                        : null,
+                    user_global_dropped: drop.dropped ? drop.file : null,
+                },
+                null,
+                2,
+            ),
+        );
+        return { code: 0, out, err };
+    }
+
+    if (winning !== null) {
+        out.push(`${opts.key} = ${JSON.stringify(displayValue(opts.key, effective))}`);
+        out.push(`  source    ${winning.file}`);
+    } else {
+        out.push(`${opts.key} — not set in any settings file`);
+        out.push(
+            `  default   ${
+                fallback === undefined
+                    ? '(none in the template)'
+                    : JSON.stringify(displayValue(opts.key, fallback))
+            }`,
+        );
+    }
+    out.push(`  class     ${cls ?? '(unclassified — no row in the class contract)'}`);
+
+    if (layers.length > 1) {
+        out.push('  layers    (cascade order, last wins)');
+        for (const layer of layers) {
+            out.push(`            ${JSON.stringify(displayValue(opts.key, layer.value))}  ←  ${layer.file}`);
+        }
+    }
+
+    if (winning === null && carveOut !== undefined) {
+        out.push(
+            '',
+            '⚠️  Absent is NOT the template default for this key.',
+            `    A reader resolves the absent key to: ${carveOut.absentResolvesTo}`,
+            `    Reader: ${carveOut.reader}`,
+            '    So "not set" and "set to the default" behave differently here.',
+        );
+    }
+
+    if (drop.dropped) {
+        out.push(
+            '',
+            '⚠️  This key IS present in your user-global file and is being discarded.',
+            `    File: ${drop.file}`,
+            '    Only the keys on the MERGEABLE_KEYS whitelist cascade from user-global into',
+            '    a project; everything else is filtered out silently by load_agent_settings.',
+            '    Set it in the project settings file, or the value has no effect anywhere.',
+        );
+    }
+
+    return { code: 0, out, err };
+}
+
+interface ParsedArgv {
+    ok: boolean;
+    message?: string;
+    key?: string;
+    json?: boolean;
+}
+
+export function parseArgv(argv: readonly string[]): ParsedArgv {
+    const positional: string[] = [];
+    let json = false;
+    for (const a of argv) {
+        if (a === '--json') {
+            json = true;
+        } else if (a === '-h' || a === '--help') {
+            return { ok: false, message: 'usage: agent-config settings:get <key> [--json]' };
+        } else if (a.startsWith('--')) {
+            return { ok: false, message: `unknown flag: ${a}` };
+        } else {
+            positional.push(a);
+        }
+    }
+    if (positional.length !== 1) {
+        return { ok: false, message: 'usage: agent-config settings:get <key> [--json]' };
+    }
+    return { ok: true, key: positional[0] as string, json };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const parsed = parseArgv(argv);
+    if (!parsed.ok) {
+        process.stderr.write(`${parsed.message ?? 'usage error'}\n`);
+        return 2;
+    }
+    const result = runSettingsGet({
+        key: parsed.key as string,
+        cwd: process.cwd(),
+        packageRoot: PACKAGE_ROOT,
+        json: parsed.json === true,
+    });
+    for (const line of result.out) process.stdout.write(`${line}\n`);
+    for (const line of result.err) process.stderr.write(`${line}\n`);
+    return result.code;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exitCode = main();
+}
+
+export { CONTRACT_RELATIVE, PACKAGE_ROOT, TEMPLATE_RELATIVE };

package/src/scripts/_dispatch.bash

@@ -73,6 +73,12 @@ TS-shell native (run via the installed `agent-config` binary):
   ui:serve                   Start the local UI server (127.0.0.1, auto-picked port)
   workspaces ls              List workspaces from the discovery manifest
   packs ls                   List packs from the discovery manifest
+  brand:status               Is a consumer brand layer present, and at which of the
+                             four canonical tokens.json paths. Flags a dot-prefixed
+                             .tokens.json, which nothing reads.
+  packs:active               Which packs are active HERE, and from which file.
+                             Names the degraded case (settings file without a
+                             profile.id → zero packs) that nothing else reports.
   commands [ls|explain]      List/explain the command surface from the discovery manifest
   mcp-server                 Turnkey read-only stdio MCP server (no repo clone; ADR-085)
   doctor-shell               Probe the TS-shell environment
@@ -153,6 +159,13 @@ Tier 1 — power-user (release shape, audit, migration):
                              Usage: council:run <question> --output <path> --confirm
   council:render             Re-render a saved council responses JSON to markdown
                              Usage: council:render <responses.json>
+  council:status             Report whether an AI council is configured, and from where
+                             (no API call, no spend)
+  self-repair:status         List queued agent-config defect records (read-only)
+  self-repair:release        Publish one defect record — a PR when the fix can be
+                             pushed, else an issue. Running it is your Hard-Floor
+                             confirmation.
+                             Usage: self-repair:release <fingerprint> [--dry-run]
 EOF
   fi
 
@@ -163,6 +176,9 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   mcp:render                 Render mcp.json → .cursor/mcp.json, .windsurf/mcp.json
                              (pass --claude-desktop to also write user-scope config)
   mcp:check                  Dry-run mcp:render; exit non-zero if targets are stale
+  mcp:available              What is declared in mcp.json, whether each server's
+                             command is launchable, and the separate static tool
+                             registry. No handshake — says so in the output.
   mcp:setup                  Verify the tsx runtime + MCP server module and
                              print the client config snippet
                              (one-line MCP server onboarding; idempotent)
@@ -199,6 +215,9 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              ~/.event4u/agent-config/ (the global-only consumer surface,
                              ADR-020). Idempotent; --force overwrites a non-empty global
                              file, --dry-run lists intended copies with zero writes.
+  settings:get               Read one setting: its value, the file it came from, its
+                             class, and whether "absent" differs from the default.
+                             Usage: settings:get <key> [--json]
   settings:set               Set one setting in the global file. Refuses every class-C
                              (guarded) key from docs/contracts/settings-classes.md, and
                              refuses everything when that contract is unreadable.
@@ -595,6 +614,26 @@ cmd_sessions_claim() {
   exec_ts "$PACKAGE_ROOT/src/scripts/sessions_cli.ts" claim "$@"
 }
 
+# Capability probes (road-to-capability-answerability). All three resolve from
+# PACKAGE_ROOT rather than the consumer projection: each imports package-internal
+# libraries under src/scripts/_lib/ or src/shared/, which are never projected into
+# dist/agent-src/scripts/. Same shape as cmd_settings_set.
+cmd_packs_active() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_packs_active.ts" "$@"
+}
+
+cmd_settings_get() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_settings_get.ts" "$@"
+}
+
+cmd_mcp_available() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_mcp_available.ts" "$@"
+}
+
+cmd_brand_status() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_brand_status.ts" "$@"
+}
+
 cmd_roadmap_progress() {
   local script
   script="$(resolve_script "dist/agent-src/scripts/update_roadmap_progress.ts" ".augment/scripts/update_roadmap_progress.ts")"
@@ -1047,6 +1086,17 @@ cmd_council() {
   exec_ts "$script" "$sub" "$@"
 }
 
+# `self-repair:{status,release}` — the queued-defect reader and the single
+# gated outward step. `release` publishes (a PR, else an issue); running it IS
+# the user's Hard-Floor confirmation, which is why nothing else in the loop
+# may publish on its own.
+cmd_self_repair() {
+  local sub="$1"; shift || true
+  local script
+  script="$(resolve_script "src/scripts/self_repair_cli.ts")" || return 1
+  exec_ts "$script" "$sub" "$@"
+}
+
 # `use --profile=<id>` — switch the active experience/profile. Writes
 # profile.id into the canonical .agent-settings.yml; the explicit
 # profile-switch seam named by ADR-040 (road-to-6.0.0-a Step 8).
@@ -1270,6 +1320,10 @@ main() {
     conformance:behavior)    cmd_conformance_behavior "$@" ;;
     sessions:list)           cmd_sessions_list "$@" ;;
     sessions:claim)          cmd_sessions_claim "$@" ;;
+    packs:active)            cmd_packs_active "$@" ;;
+    settings:get)            cmd_settings_get "$@" ;;
+    mcp:available)           cmd_mcp_available "$@" ;;
+    brand:status)            cmd_brand_status "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     roadmap:archive)         cmd_roadmap_archive "$@" ;;
@@ -1311,6 +1365,9 @@ main() {
     council:estimate)        cmd_council estimate "$@" ;;
     council:run)             cmd_council run "$@" ;;
     council:render)          cmd_council render "$@" ;;
+    council:status)         cmd_council status "$@" ;;
+    self-repair:status)      cmd_self_repair status "$@" ;;
+    self-repair:release)     cmd_self_repair release "$@" ;;
     update)                  cmd_update "$@" ;;
     upgrade)                 cmd_upgrade "$@" ;;
     refresh)                 cmd_refresh "$@" ;;

package/src/scripts/_lib/agent_settings.ts

@@ -191,13 +191,60 @@ export function DEFAULT_USER_GLOBAL_FILE(): string {
     return user_global_paths.write_target(USER_GLOBAL_FILENAME);
 }
 
-/** Return the active user-global settings path with legacy fallback. */
-function _resolve_user_global_file(): string {
-    const found = user_global_paths.resolve_with_fallback(USER_GLOBAL_FILENAME);
-    if (found !== null) {
-        return found;
+/**
+ * The canonical user-global settings file — `<event4u_root>/settings/.agent-settings.yml`.
+ *
+ * This is what the GUI settings route, the wizard route, and the installer all
+ * write, mirroring the project layer's `agents/settings/.agent-settings.yml`
+ * convention. Until `road-to-capability-answerability` 4.1 the loader did not
+ * read it at all: three writers, one reader, and the reader was looking at the
+ * other file. Every value a user set through the only surfaces that write it was
+ * therefore inert, silently — the exact shape of defect this roadmap closes.
+ */
+export const USER_GLOBAL_CANONICAL_RELATIVE = 'settings/.agent-settings.yml';
+
+/**
+ * Every user-global settings file to merge, in precedence order (later wins).
+ *
+ * Two entries, deliberately, rather than a replacement:
+ *
+ * - the FLAT `agent-settings.yml` stays first because it is not dead. It is the
+ *   file `link_crypto.ts` reads directly for `secrets.link_encryption_key`, and
+ *   dropping it from the cascade would change behaviour for anyone who put a
+ *   whitelisted key there;
+ * - the CANONICAL `settings/.agent-settings.yml` is layered ON TOP, so the file
+ *   the writers actually produce wins per key.
+ *
+ * Additive by construction: nothing that resolved before resolves differently
+ * unless the canonical file sets that key, and the user-global layer is filtered
+ * through {@link MERGEABLE_KEYS} downstream regardless — so the reachable blast
+ * radius is those keys, not the whole document.
+ */
+export function user_global_settings_paths(): string[] {
+    const paths: string[] = [];
+    const flat = user_global_paths.resolve_with_fallback(USER_GLOBAL_FILENAME);
+    if (flat !== null) {
+        paths.push(flat);
     }
-    return DEFAULT_USER_GLOBAL_FILE();
+    const canonical = user_global_paths.resolve_with_fallback(USER_GLOBAL_CANONICAL_RELATIVE);
+    if (canonical !== null) {
+        paths.push(canonical);
+    }
+    if (paths.length === 0) {
+        paths.push(DEFAULT_USER_GLOBAL_FILE());
+    }
+    return paths;
+}
+
+/**
+ * Return the active user-global settings path with legacy fallback.
+ *
+ * The HIGHEST-precedence existing file, so callers that want a single path (a
+ * report, an error message) name the one that actually decided the value.
+ */
+function _resolve_user_global_file(): string {
+    const paths = user_global_settings_paths();
+    return paths[paths.length - 1] as string;
 }
 
 /**
@@ -206,11 +253,25 @@ function _resolve_user_global_file(): string {
  * the user-global file. Adding a key requires an ADR.
  */
 export const MERGEABLE_KEYS: readonly string[] = [
+    // `name`, `ide` and `personal.bot_icon` are the PRE-MIGRATION spellings.
+    // `install.ts` migrates `ide` → `personal.ide` and `pr_comment_bot_icon`
+    // into its `personal.` home, and this list was never moved with them — so
+    // the whitelist named keys the template does not have while the keys it
+    // does have were filtered out silently. A user setting either preference
+    // user-globally got no error, no warning, and no effect
+    // (road-to-capability-answerability 4.3, ADR-219).
+    //
+    // Both spellings are listed rather than replaced: a legacy file that still
+    // uses the old name keeps working, and nothing that resolved before
+    // resolves differently. `name` has no reader anywhere and no template key;
+    // it is kept only so this change stays purely additive.
     'name',
     'ide',
+    'personal.ide',
     'rule_loading_tier',
     'memory.cadence',
     'personal.bot_icon',
+    'personal.pr_comment_bot_icon',
     'personal.autonomy',
     'telegraph.speak_scope',
     // Knowledge-card global cross-project sharing is a USER-GLOBAL setting
@@ -676,8 +737,12 @@ export function load_agent_settings(
     const verbose = options.verbose ?? false;
     const cwd = options.cwd ?? null;
 
-    const user_global_raw =
-        _read_yaml(user_global_path ? user_global_path : _resolve_user_global_file()) ?? {};
+    // An explicit path is a caller override (tests, tooling) and stays single;
+    // otherwise every user-global file merges in precedence order.
+    const user_global_raw: SettingsDict = {};
+    for (const p of user_global_path ? [user_global_path] : user_global_settings_paths()) {
+        _deep_merge(user_global_raw, _read_yaml(p) ?? {});
+    }
 
     const [user_global_filtered, ignored] = _filter_whitelist(user_global_raw, MERGEABLE_KEYS);
     if (verbose && ignored.length > 0) {
@@ -923,14 +988,15 @@ export function* iter_setting_overrides(
     const user_global_path = options.user_global_path ?? null;
     const cwd = options.cwd ?? null;
 
-    const user_global_path_resolved = user_global_path
-        ? user_global_path
-        : _resolve_user_global_file();
-    const user_global_raw = _read_yaml(user_global_path_resolved) ?? {};
-    const [user_global_filtered] = _filter_whitelist(user_global_raw, MERGEABLE_KEYS);
-    if (Object.keys(user_global_filtered).length > 0) {
-        for (const key of _leaf_paths(user_global_filtered)) {
-            yield [key, _get_dotted(user_global_filtered, key), user_global_path_resolved];
+    // One yield PER FILE, not one per merged user-global layer: the whole point
+    // of this generator is that the third element names the file that set the
+    // value, and collapsing two user-global files into one would attribute a
+    // value to a file that does not contain it.
+    for (const p of user_global_path ? [user_global_path] : user_global_settings_paths()) {
+        const raw = _read_yaml(p) ?? {};
+        const [filtered] = _filter_whitelist(raw, MERGEABLE_KEYS);
+        for (const key of _leaf_paths(filtered)) {
+            yield [key, _get_dotted(filtered, key), p];
         }
     }