@event4u/agent-config 9.7.0 → 9.9.0

package/dist/agent-src/templates/scripts/telemetry/engagement.ts

@@ -21,6 +21,10 @@
  *              (same PII-exclusion-by-construction shape as consulted).
  *       "outcomes":  ["blocked", "verification_failed", ...]  # optional
  *       "tokens_estimate": {"consulted_load": <int>}   # optional
+ *       "cross_source": [{"id": "d1", "type": "text-image", "asked": true}]  # optional
+ *              (road-to-feedback-9.2.0-followups 1.4): per-task ask-rate facet
+ *              for the cross-source-consistency rule. Structural only — id +
+ *              a closed type enum + a bool, no free-form fields.
  *     }
  */
 import * as fs from 'node:fs';
@@ -55,6 +59,18 @@ export const ALLOWED_OUTCOMES = [
 ] as const;
 export const MAX_OUTCOMES_PER_EVENT = ALLOWED_OUTCOMES.length;
 
+// cross_source facet (road-to-feedback-9.2.0-followups 1.4) — the
+// cross-source-consistency rule's discrepancy taxonomy (a)-(d) from
+// src/rules/cross-source-consistency.md.
+export const ALLOWED_CROSS_SOURCE_TYPES = [
+    'text-image',
+    'silent-needed',
+    'spec-code',
+    'intra-ticket',
+] as const;
+export const MAX_CROSS_SOURCE_PER_EVENT = 32;
+const _CROSS_SOURCE_KEYS = ['asked', 'id', 'type'] as const;
+
 // Phase 5 redaction validator — keep id fields from leaking paths,
 // free-text, or filenames.
 const _FORBIDDEN_ID_CHARS = ['/', '\\', '\n', '\r', '\t'] as const;
@@ -125,6 +141,13 @@ export function check_id_redaction(label: string, value: unknown): void {
     }
 }
 
+/** One surfaced cross-source discrepancy — structural only, no free text. */
+export interface CrossSourceEntry {
+    id: string;
+    type: string;
+    asked: boolean;
+}
+
 export interface EngagementEventInit {
     ts: string;
     task_id: string;
@@ -134,6 +157,7 @@ export interface EngagementEventInit {
     loaded?: Record<string, string[]> | null;
     outcomes?: string[] | null;
     tokens_estimate?: Record<string, number> | null;
+    cross_source?: CrossSourceEntry[] | null;
     schema_version?: number;
 }
 
@@ -146,6 +170,7 @@ export class EngagementEvent {
     loaded: Record<string, string[]> | null;
     outcomes: string[] | null;
     tokens_estimate: Record<string, number> | null;
+    cross_source: CrossSourceEntry[] | null;
     schema_version: number;
 
     constructor(init: EngagementEventInit) {
@@ -157,6 +182,7 @@ export class EngagementEvent {
         this.loaded = init.loaded ?? null;
         this.outcomes = init.outcomes ?? null;
         this.tokens_estimate = init.tokens_estimate ?? null;
+        this.cross_source = init.cross_source ?? null;
         this.schema_version = init.schema_version ?? SCHEMA_VERSION;
     }
 
@@ -195,6 +221,9 @@ export class EngagementEvent {
         if (this.outcomes !== null) {
             _validate_outcomes(this.outcomes);
         }
+        if (this.cross_source !== null) {
+            _validate_cross_source(this.cross_source);
+        }
         if (this.tokens_estimate !== null) {
             if (!_isPlainObject(this.tokens_estimate)) {
                 throw new EngagementSchemaError(
@@ -236,6 +265,13 @@ export class EngagementEvent {
         if (this.outcomes && this.outcomes.length > 0) {
             out['outcomes'] = [...this.outcomes];
         }
+        if (this.cross_source && this.cross_source.length > 0) {
+            out['cross_source'] = this.cross_source.map((e) => ({
+                id: e.id,
+                type: e.type,
+                asked: e.asked,
+            }));
+        }
         if (this.tokens_estimate && Object.keys(this.tokens_estimate).length > 0) {
             out['tokens_estimate'] = { ...this.tokens_estimate };
         }
@@ -317,6 +353,46 @@ function _validate_outcomes(payload: unknown): void {
     }
 }
 
+function _validate_cross_source(payload: unknown): void {
+    if (!Array.isArray(payload)) {
+        throw new EngagementSchemaError('cross_source must be a list of dict or None');
+    }
+    if (payload.length > MAX_CROSS_SOURCE_PER_EVENT) {
+        throw new EngagementSchemaError(
+            `cross_source exceeds ${MAX_CROSS_SOURCE_PER_EVENT} entries`,
+        );
+    }
+    for (const entry of payload) {
+        if (!_isPlainObject(entry)) {
+            throw new EngagementSchemaError('cross_source entries must be dict[str, ...]');
+        }
+        const keys = Object.keys(entry);
+        const extra = keys.filter((k) => !(_CROSS_SOURCE_KEYS as readonly string[]).includes(k));
+        if (extra.length > 0) {
+            throw new EngagementSchemaError(
+                `cross_source entry has unexpected key(s): ${extra.sort().join(', ')}; `
+                + `allowed keys: ${_CROSS_SOURCE_KEYS.join(', ')}`,
+            );
+        }
+        for (const required of _CROSS_SOURCE_KEYS) {
+            if (!(required in entry)) {
+                throw new EngagementSchemaError(`cross_source entry missing required key '${required}'`);
+            }
+        }
+        check_id_redaction('cross_source.id', entry['id']);
+        const type_val = entry['type'];
+        if (typeof type_val !== 'string' || !(ALLOWED_CROSS_SOURCE_TYPES as readonly string[]).includes(type_val)) {
+            throw new EngagementSchemaError(
+                `cross_source.type must be one of ${_reprTuple(ALLOWED_CROSS_SOURCE_TYPES)}, `
+                + `got ${_reprScalar(type_val)}`,
+            );
+        }
+        if (typeof entry['asked'] !== 'boolean') {
+            throw new EngagementSchemaError('cross_source.asked must be a bool');
+        }
+    }
+}
+
 export function parse_event(line: string): EngagementEvent {
     if (typeof line !== 'string' || !line.trim()) {
         throw new EngagementSchemaError('line must be a non-empty JSONL record');
@@ -342,6 +418,7 @@ export function parse_event(line: string): EngagementEvent {
             : _orEmptyDict(r['loaded']),
         outcomes: (r['outcomes'] as string[] | null | undefined) ?? null,
         tokens_estimate: (r['tokens_estimate'] as Record<string, number> | null | undefined) ?? null,
+        cross_source: (r['cross_source'] as CrossSourceEntry[] | null | undefined) ?? null,
         schema_version: r['schema_version'] === undefined
             ? SCHEMA_VERSION
             : (r['schema_version'] as number),

package/dist/agent-src/templates/scripts/telemetry_record.ts

@@ -21,6 +21,7 @@ import * as path from 'node:path';
 import { record_event } from './telemetry/boundary.js';
 import {
     ALLOWED_OUTCOMES,
+    type CrossSourceEntry,
     EngagementEvent,
     EngagementSchemaError,
     now_utc_iso,
@@ -58,6 +59,30 @@ function _reprStr(s: string): string {
     return `'${s}'`;
 }
 
+/** Turn `["d1:text-image:ask", ...]` into cross_source entries. Unknown
+ *  `type` values are left to schema validation (consistent with how
+ *  `_parse_kv_list` leaves unknown artefact kinds to the schema); only
+ *  the CLI-only `id:type:ask|warn` shape is checked here. */
+function _parse_cross_source_list(values: string[]): CrossSourceEntry[] {
+    const out: CrossSourceEntry[] = [];
+    for (const raw of values) {
+        const parts = raw.split(':');
+        if (parts.length !== 3 || !parts[0] || !parts[1] || !parts[2]) {
+            throw new SystemExitError(
+                `❌  --cross-source must be 'id:type:ask|warn', got ${_reprStr(raw)}`,
+            );
+        }
+        const [id, type, verdict] = parts as [string, string, string];
+        if (verdict !== 'ask' && verdict !== 'warn') {
+            throw new SystemExitError(
+                `❌  --cross-source verdict must be 'ask' or 'warn', got ${_reprStr(verdict)}`,
+            );
+        }
+        out.push({ id, type, asked: verdict === 'ask' });
+    }
+    return out;
+}
+
 interface RecordArgs {
     task_id: string;
     boundary: string;
@@ -65,6 +90,7 @@ interface RecordArgs {
     applied: string[] | null;
     loaded: string[] | null;
     outcome: string[] | null;
+    cross_source: string[] | null;
     ts: string;
     payload_file: string | null;
     stdin: boolean;
@@ -81,6 +107,9 @@ function _build_event_from_args(args: RecordArgs): EngagementEvent {
         applied: _parse_kv_list(args.applied ?? []),
         loaded: args.loaded && args.loaded.length > 0 ? _parse_kv_list(args.loaded) : null,
         outcomes: args.outcome && args.outcome.length > 0 ? [...args.outcome] : null,
+        cross_source: args.cross_source && args.cross_source.length > 0
+            ? _parse_cross_source_list(args.cross_source)
+            : null,
     });
 }
 
@@ -106,6 +135,7 @@ function _build_event_from_payload(raw: string): EngagementEvent {
         loaded: d['loaded'] === undefined || d['loaded'] === null ? null : _orEmpty(d['loaded']),
         outcomes: (d['outcomes'] as string[] | null | undefined) ?? null,
         tokens_estimate: (d['tokens_estimate'] as Record<string, number> | null | undefined) ?? null,
+        cross_source: (d['cross_source'] as CrossSourceEntry[] | null | undefined) ?? null,
     });
 }
 
@@ -126,6 +156,7 @@ function _parseArgs(argv: string[]): RecordArgs {
         applied: null,
         loaded: null,
         outcome: null,
+        cross_source: null,
         ts: '',
         payload_file: null,
         stdin: false,
@@ -170,7 +201,8 @@ function _parseArgs(argv: string[]): RecordArgs {
                 );
             }
             (a.outcome ??= []).push(v);
-        } else if (tok === '--ts') a.ts = next();
+        } else if (tok === '--cross-source') (a.cross_source ??= []).push(next());
+        else if (tok === '--ts') a.ts = next();
         else if (tok === '--payload-file') a.payload_file = next();
         else if (tok === '--stdin') a.stdin = true;
         else if (tok === '--settings') a.settings = next();

package/dist/cli/commands/doctorShell.js

@@ -9,6 +9,7 @@
 import { existsSync } from 'node:fs';
 import { BASH_ENTRY, BASH_SHIM, CONSUMER_ROOT, PACKAGE_ROOT } from '../paths.js';
 import { logger } from '../log/logger.js';
+import { detectRtk } from '../../install/rtkDetection.js';
 function checkNode() {
     const required = 20;
     const version = process.versions.node;
@@ -45,12 +46,31 @@ function checkBashShim() {
         detail: ok ? BASH_SHIM : `${BASH_SHIM} (not found)`,
     };
 }
+/**
+ * rtk is an OPTIONAL third-party tool — its absence never fails the doctor
+ * (ok stays true for every state); the row is an informational readout of
+ * the two-stage identity probe (docs/contracts/rtk-detection.md).
+ */
+function checkRtk() {
+    const d = detectRtk();
+    if (!d.present)
+        return { name: 'rtk', ok: true, detail: 'not installed (optional; see `agent-config rtk:detect`)' };
+    switch (d.identity) {
+        case 'token-killer':
+            return { name: 'rtk', ok: true, detail: `Rust Token Killer${d.version !== undefined ? ` v${d.version}` : ''} (${d.binPath ?? 'on PATH'})` };
+        case 'unknown-rtk':
+            return { name: 'rtk', ok: true, detail: 'DIFFERENT TOOL on PATH (name collision, not Rust Token Killer) — see `agent-config rtk:detect`' };
+        default:
+            return { name: 'rtk', ok: true, detail: 'present but unverified — run `rtk gain` manually' };
+    }
+}
 export function runDoctorShell() {
     const checks = [
         checkNode(),
         checkPackageRoot(),
         checkBashEntry(),
         checkBashShim(),
+        checkRtk(),
     ];
     logger.info(`consumer_root: ${CONSUMER_ROOT}`);
     logger.info(`package_root:  ${PACKAGE_ROOT}`);

package/dist/cli/commands/doctorShell.js.map

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

package/dist/cli/commands/rtkDetect.js

@@ -0,0 +1,58 @@
+/**
+ * `rtk:detect` — native TS implementation.
+ *
+ * Stable rtk (Rust Token Killer) detection readout: the same two-stage
+ * probe (PATH presence + `rtk gain` output-signature identity) the wizard
+ * uses, exposed to the CLI so other tools (agent-switch's Tooling section,
+ * scripts, doctors) can consume one primary implementation instead of
+ * re-probing with their own drift-prone logic.
+ *
+ * Contract: docs/contracts/rtk-detection.md (versioned — bump `contract`
+ * on any breaking shape change).
+ */
+import { detectRtk, rtkInstallCommands, RTK_UPSTREAM_REPO } from '../../install/rtkDetection.js';
+import { logger } from '../log/logger.js';
+export const RTK_DETECT_CONTRACT_VERSION = 1;
+export function runRtkDetect(opts) {
+    const detection = detectRtk();
+    const installed = detection.present && detection.identity === 'token-killer';
+    if (opts.json === true) {
+        const payload = {
+            contract: RTK_DETECT_CONTRACT_VERSION,
+            installed,
+            present: detection.present,
+            identity: detection.identity ?? null,
+            version: detection.version ?? null,
+            binPath: detection.binPath ?? null,
+            platform: process.platform,
+            repo: RTK_UPSTREAM_REPO,
+            installCommands: detection.present ? null : rtkInstallCommands(process.platform),
+        };
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return 0;
+    }
+    if (!detection.present) {
+        const commands = rtkInstallCommands(process.platform);
+        logger.info('rtk: not installed');
+        logger.info(`  install (${commands.recommendedLabel}): ${commands.recommended}`);
+        if (commands.manual !== undefined) {
+            logger.info(`  manual (${commands.manualLabel ?? 'manual'}): ${commands.manual}`);
+        }
+        if (commands.note !== undefined)
+            logger.info(`  note: ${commands.note}`);
+        logger.info(`  upstream: ${RTK_UPSTREAM_REPO} (third-party, Apache-2.0)`);
+        return 0;
+    }
+    switch (detection.identity) {
+        case 'token-killer':
+            logger.info(`rtk: installed — Rust Token Killer${detection.version !== undefined ? ` v${detection.version}` : ''} (${detection.binPath ?? 'on PATH'})`);
+            return 0;
+        case 'unknown-rtk':
+            logger.info(`rtk: DIFFERENT TOOL — a binary named rtk is on PATH (${detection.binPath ?? ''}) but it is not Rust Token Killer (name collision with Rust Type Kit). See ${RTK_UPSTREAM_REPO}/blob/master/INSTALL.md`);
+            return 0;
+        default:
+            logger.info(`rtk: present but UNVERIFIED — the identity check failed; verify manually with \`rtk gain\` (Rust Token Killer renders a token-savings dashboard).`);
+            return 0;
+    }
+}
+//# sourceMappingURL=rtkDetect.js.map

package/dist/cli/commands/rtkDetect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rtkDetect.js","sourceRoot":"","sources":["../../../src/cli/commands/rtkDetect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACjG,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C,MAAM,UAAU,YAAY,CAAC,IAAwB;IACjD,MAAM,SAAS,GAAG,SAAS,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,IAAI,SAAS,CAAC,QAAQ,KAAK,cAAc,CAAC;IAE7E,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG;YACZ,QAAQ,EAAE,2BAA2B;YACrC,SAAS;YACT,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI,IAAI;YACpC,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,IAAI;YAClC,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,IAAI;YAClC,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,IAAI,EAAE,iBAAiB;YACvB,eAAe,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC;SACnF,CAAC;QACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9D,OAAO,CAAC,CAAC;IACb,CAAC;IAED,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,cAAc,QAAQ,CAAC,gBAAgB,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QACjF,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,CAAC,IAAI,CAAC,aAAa,QAAQ,CAAC,WAAW,IAAI,QAAQ,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS;YAAE,MAAM,CAAC,IAAI,CAAC,WAAW,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QACzE,MAAM,CAAC,IAAI,CAAC,eAAe,iBAAiB,4BAA4B,CAAC,CAAC;QAC1E,OAAO,CAAC,CAAC;IACb,CAAC;IACD,QAAQ,SAAS,CAAC,QAAQ,EAAE,CAAC;QACzB,KAAK,cAAc;YACf,MAAM,CAAC,IAAI,CAAC,qCAAqC,SAAS,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC,OAAO,IAAI,SAAS,GAAG,CAAC,CAAC;YACxJ,OAAO,CAAC,CAAC;QACb,KAAK,aAAa;YACd,MAAM,CAAC,IAAI,CAAC,wDAAwD,SAAS,CAAC,OAAO,IAAI,EAAE,8EAA8E,iBAAiB,yBAAyB,CAAC,CAAC;YACrN,OAAO,CAAC,CAAC;QACb;YACI,MAAM,CAAC,IAAI,CAAC,mJAAmJ,CAAC,CAAC;YACjK,OAAO,CAAC,CAAC;IACjB,CAAC;AACL,CAAC"}

package/dist/cli/configRoot.js

@@ -0,0 +1,112 @@
+/**
+ * Host-supplied config-root resolution (reciprocal-ecosystem Phase 2).
+ *
+ * A host that spawns `agent-config` per profile needs AC to read/write
+ * its own config/settings/state under a host-chosen directory instead of
+ * the shared `~/.event4u/agent-config/` default — otherwise two profiles
+ * silently collide on the same files.
+ *
+ * The seam is the existing single source of truth `event4u_root()`
+ * (`scripts/_lib/user_global_paths.ts`), which already honours the
+ * `EVENT4U_CONFIG_HOME` environment variable. This module layers a
+ * documented CLI flag on top and wires both into one precedence:
+ *
+ *   flag (`--config-root <path>`)  >  env (`EVENT4U_CONFIG_HOME`)  >  default
+ *
+ * The flag is applied by exporting its value into `EVENT4U_CONFIG_HOME`
+ * once at CLI entry (`applyConfigRootFromArgv`), so every downstream
+ * resolver — the scripts family via `event4u_root()`, the server family
+ * via the same seam, and every Bash-delegated subprocess (which inherits
+ * `process.env`) — observes the override through the same variable.
+ *
+ * With no flag and no env, this module has zero side effects and AC's
+ * behaviour is byte-identical to before.
+ */
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { event4u_root, EVENT4U_HOME_ENV } from '../scripts/_lib/user_global_paths.js';
+/** The documented CLI flag a host passes on spawn. */
+export const CONFIG_ROOT_FLAG = '--config-root';
+/**
+ * The environment variable the flag maps onto — the established
+ * config-home override honoured by `event4u_root()`. Reused (rather than
+ * introducing a second name) so there is exactly one override variable.
+ */
+export const CONFIG_ROOT_ENV = EVENT4U_HOME_ENV;
+/** Expand a leading `~` / `~/` like a shell would. */
+function expandHome(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    return p;
+}
+/**
+ * Resolve the effective config root for the given inputs, applying the
+ * `flag > env > default` precedence. Pure — no filesystem writes.
+ *
+ * The flag is expanded (`~`) and resolved to an absolute path; the env /
+ * default path is delegated to `event4u_root()` so there is a single
+ * source of truth for the non-flag branches.
+ */
+export function resolveConfigRoot(opts = {}) {
+    const flag = opts.flag?.trim();
+    if (flag !== undefined && flag.length > 0) {
+        return resolve(expandHome(flag));
+    }
+    return event4u_root(opts.env ?? null);
+}
+/**
+ * Validate and materialise a host-supplied config root: expand `~`,
+ * resolve to an absolute path, and create the directory (mode 0700) if
+ * missing. Throws on an empty value. Returns the absolute path.
+ */
+export function ensureConfigRoot(rawPath) {
+    const trimmed = rawPath.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`${CONFIG_ROOT_FLAG} requires a non-empty path`);
+    }
+    const abs = resolve(expandHome(trimmed));
+    mkdirSync(abs, { recursive: true, mode: 0o700 });
+    return abs;
+}
+/**
+ * Extract the first `--config-root <path>` / `--config-root=<path>` from
+ * `argv`, apply it (validate → mkdir 0700 → set `EVENT4U_CONFIG_HOME`),
+ * and return the cleaned `argv`.
+ *
+ * When the flag is absent this is a pure passthrough: a copy of `argv`,
+ * `configRoot: null`, and no environment or filesystem mutation — so the
+ * default behaviour is byte-identical.
+ *
+ * Throws (a clear message) when the flag is present without a value.
+ */
+export function applyConfigRootFromArgv(argv, env = process.env) {
+    const out = [];
+    let value = null;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (value === null && token === CONFIG_ROOT_FLAG) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('-')) {
+                throw new Error(`${CONFIG_ROOT_FLAG} requires a path argument`);
+            }
+            value = next;
+            i += 1; // consume the value token
+            continue;
+        }
+        if (value === null && token.startsWith(`${CONFIG_ROOT_FLAG}=`)) {
+            value = token.slice(CONFIG_ROOT_FLAG.length + 1);
+            continue;
+        }
+        out.push(token);
+    }
+    if (value === null) {
+        return { argv: out, configRoot: null };
+    }
+    const configRoot = ensureConfigRoot(value);
+    env[CONFIG_ROOT_ENV] = configRoot;
+    return { argv: out, configRoot };
+}
+//# sourceMappingURL=configRoot.js.map

package/dist/cli/configRoot.js.map

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

package/dist/cli/configRoot.test.js

@@ -0,0 +1,97 @@
+/**
+ * Unit tests for the host-supplied config-root seam.
+ *
+ *   - `resolveConfigRoot` applies `flag > env > default` precedence.
+ *   - `ensureConfigRoot` validates + creates the dir (0700), rejects empty.
+ *   - `applyConfigRootFromArgv` extracts the flag, exports the env, cleans
+ *     argv, and is a pure passthrough (no side effects) when absent.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { CONFIG_ROOT_ENV, applyConfigRootFromArgv, ensureConfigRoot, resolveConfigRoot, } from './configRoot.js';
+describe('config root', () => {
+    let scratch;
+    let savedEnv;
+    beforeEach(() => {
+        scratch = mkdtempSync(join(tmpdir(), 'configroot-'));
+        savedEnv = process.env[CONFIG_ROOT_ENV];
+        delete process.env[CONFIG_ROOT_ENV];
+    });
+    afterEach(() => {
+        rmSync(scratch, { recursive: true, force: true });
+        if (savedEnv === undefined) {
+            delete process.env[CONFIG_ROOT_ENV];
+        }
+        else {
+            process.env[CONFIG_ROOT_ENV] = savedEnv;
+        }
+    });
+    describe('resolveConfigRoot (precedence flag > env > default)', () => {
+        it('returns the flag value (absolute-resolved) when set — even if env is also set', () => {
+            const flag = join(scratch, 'from-flag');
+            const res = resolveConfigRoot({
+                flag,
+                env: { [CONFIG_ROOT_ENV]: join(scratch, 'from-env') },
+            });
+            expect(res).toBe(resolve(flag));
+        });
+        it('returns the env value when no flag is set', () => {
+            const envRoot = join(scratch, 'from-env');
+            const res = resolveConfigRoot({ env: { [CONFIG_ROOT_ENV]: envRoot } });
+            expect(res).toBe(envRoot);
+        });
+        it('returns the vendor-namespaced default when neither flag nor env is set', () => {
+            const res = resolveConfigRoot({ env: {} });
+            expect(res).toBe(join(homedir(), '.event4u', 'agent-config'));
+        });
+    });
+    describe('ensureConfigRoot', () => {
+        it('creates the directory (mode 0700, no group/other access)', () => {
+            const target = join(scratch, 'nested', 'root');
+            expect(existsSync(target)).toBe(false);
+            const abs = ensureConfigRoot(target);
+            expect(abs).toBe(resolve(target));
+            expect(statSync(abs).isDirectory()).toBe(true);
+            const mode = statSync(abs).mode & 0o777;
+            // Owner rwx present; group/other stripped (umask only restricts).
+            expect(mode & 0o700).toBe(0o700);
+            expect(mode & 0o077).toBe(0);
+        });
+        it('rejects an empty path', () => {
+            expect(() => ensureConfigRoot('   ')).toThrow(/non-empty/);
+        });
+    });
+    describe('applyConfigRootFromArgv', () => {
+        it('extracts `--config-root <path>`, exports the env, and cleans argv', () => {
+            const root = join(scratch, 'profile-a');
+            const env = {};
+            const res = applyConfigRootFromArgv(['config', '--config-root', root, '--port', '8080'], env);
+            expect(res.configRoot).toBe(resolve(root));
+            expect(env[CONFIG_ROOT_ENV]).toBe(resolve(root));
+            expect(res.argv).toEqual(['config', '--port', '8080']);
+            expect(existsSync(resolve(root))).toBe(true);
+        });
+        it('supports the `--config-root=<path>` form', () => {
+            const root = join(scratch, 'profile-b');
+            const env = {};
+            const res = applyConfigRootFromArgv([`--config-root=${root}`, 'setup'], env);
+            expect(res.configRoot).toBe(resolve(root));
+            expect(env[CONFIG_ROOT_ENV]).toBe(resolve(root));
+            expect(res.argv).toEqual(['setup']);
+        });
+        it('is a pure passthrough with no side effects when the flag is absent', () => {
+            const env = {};
+            const res = applyConfigRootFromArgv(['config', '--port', '8080'], env);
+            expect(res.configRoot).toBeNull();
+            expect(env[CONFIG_ROOT_ENV]).toBeUndefined();
+            expect(res.argv).toEqual(['config', '--port', '8080']);
+        });
+        it('throws when the flag is present without a value', () => {
+            expect(() => applyConfigRootFromArgv(['config', '--config-root'], {})).toThrow(/requires a path/);
+            expect(() => applyConfigRootFromArgv(['--config-root', '--port'], {})).toThrow(/requires a path/);
+        });
+    });
+});
+//# sourceMappingURL=configRoot.test.js.map

package/dist/cli/configRoot.test.js.map

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

package/dist/cli/firstRunNotice.js

@@ -0,0 +1,70 @@
+/**
+ * One-time GUI notice on the first interactive CLI invocation
+ * (road-to-feedback-9.8.0-followups § Phase 0, install-time side-effect
+ * honesty).
+ *
+ * The package deliberately has NO install-time side effect (no postinstall,
+ * no GUI auto-launch — removal owned by road-to-credible-install Phase 0).
+ * The discoverability that a postinstall banner would have provided moves
+ * here instead: the FIRST interactive invocation prints one stderr line
+ * pointing at the browser GUI and naming the suppress variable, then never
+ * again (marker file under the user-global root).
+ *
+ * Silent by construction for every machine surface: requires a stderr TTY,
+ * no `CI`, no `AGENT_CONFIG_NO_UI` — hooks, MCP serving, pipes, and CI runs
+ * never see it. Failures (unwritable root, races) degrade to silence; the
+ * notice is informational, never load-bearing.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { event4u_root } from '../scripts/_lib/user_global_paths.js';
+const MARKER_BASENAME = 'first-run-notice-shown';
+export const FIRST_RUN_NOTICE = 'agent-config has a browser GUI — run `agent-config setup` to open it. ' +
+    '(Set AGENT_CONFIG_NO_UI=1 to suppress GUI launches; this notice prints once.)\n';
+/** Commands that already ARE the GUI — mark as seen without printing. */
+const GUI_COMMANDS = new Set([
+    'setup', 'install', 'init', 'config', 'settings', 'ui:serve',
+]);
+/**
+ * Print the one-time GUI notice when appropriate. Returns true when the
+ * notice was printed this call (test seam); marker is written on both the
+ * printed and the GUI-command path so the notice fires at most once ever.
+ */
+export function maybePrintFirstRunNotice(head, io = {}) {
+    const env = io.env ?? process.env;
+    const ci = (env['CI'] ?? '').trim();
+    if (ci && ci !== '0')
+        return false;
+    const noUi = (env['AGENT_CONFIG_NO_UI'] ?? '').trim();
+    if (noUi && noUi !== '0')
+        return false;
+    const tty = io.isStderrTty ?? process.stderr.isTTY === true;
+    if (!tty)
+        return false;
+    let root;
+    try {
+        root = io.root ?? event4u_root(env);
+    }
+    catch {
+        return false;
+    }
+    const marker = join(root, MARKER_BASENAME);
+    try {
+        if (existsSync(marker))
+            return false;
+        mkdirSync(root, { recursive: true });
+        writeFileSync(marker, `${new Date().toISOString()}\n`, { flag: 'wx' });
+    }
+    catch {
+        // Race (another invocation won `wx`) or unwritable root → stay silent.
+        return false;
+    }
+    if (head !== undefined && GUI_COMMANDS.has(head)) {
+        // The user is already opening the GUI — notice would be noise.
+        return false;
+    }
+    const write = io.write ?? ((text) => process.stderr.write(text));
+    write(FIRST_RUN_NOTICE);
+    return true;
+}
+//# sourceMappingURL=firstRunNotice.js.map

package/dist/cli/firstRunNotice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firstRunNotice.js","sourceRoot":"","sources":["../../src/cli/firstRunNotice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEpE,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEjD,MAAM,CAAC,MAAM,gBAAgB,GACzB,wEAAwE;IACxE,iFAAiF,CAAC;AAEtF,yEAAyE;AACzE,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC;IAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU;CAC/D,CAAC,CAAC;AASH;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACpC,IAAwB,EACxB,KAAuB,EAAE;IAEzB,MAAM,GAAG,GAAG,EAAE,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IAClC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpC,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,IAAI,IAAI,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;IAC5D,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IAEvB,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACD,IAAI,GAAG,EAAE,CAAC,IAAI,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IAC3C,IAAI,CAAC;QACD,IAAI,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC;QACrC,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrC,aAAa,CAAC,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACL,uEAAuE;QACvE,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,IAAI,IAAI,KAAK,SAAS,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,+DAA+D;QAC/D,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACzE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/dist/cli/help.js

@@ -15,7 +15,10 @@ export function buildHelp() {
         'Usage:',
         '  agent-config <command> [options]',
         '  agent-config --help',
-        '  agent-config --version',
+        '  agent-config --version [--json]',
+        '',
+        'Global options:',
+        '  --config-root <path>       Config/settings/state home (else $EVENT4U_CONFIG_HOME, else ~/.event4u/agent-config)',
         '',
         'Native commands (TS shell):',
     ];