@event4u/agent-config 8.4.1 → 8.6.0

package/src/scripts/_cli/cmd_migrate.ts

@@ -2,8 +2,8 @@
  * `agent-config migrate` — one-shot, opinionated migration off every legacy
  * install / state shape (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_migrate.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_migrate.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects. No behaviour changes — latent quirks are
  * replicated and flagged inline, not fixed.
@@ -82,7 +82,7 @@ import { resolve_project_root } from '../_lib/agent_settings.js';
 // specifier into the uncompiled template tree (`.ts` only) and crash the whole
 // CLI at module load — breaking every command (e.g. `agent-config init`).
 // `_load_state_migrator` spawns it via tsx instead (the install orchestrator
-// pattern), keeping the migrator lazy like the Python original.
+// pattern), keeping the migrator lazy like the retired Python implementation.
 
 const PACKAGE_NAME_NPM = '@event4u/agent-config';
 const PACKAGE_NAME_COMPOSER = 'event4u/agent-config';

package/src/scripts/_cli/cmd_prune.ts

@@ -1,8 +1,8 @@
 /**
  * `agent-config prune` — remove orphaned project bridge markers (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_prune.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_prune.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects. No behaviour changes — latent quirks are
  * replicated and flagged inline, not fixed.

package/src/scripts/_cli/cmd_refresh.ts

@@ -3,8 +3,8 @@
  * `agent-config refresh` — idempotent re-install, no version change
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_refresh.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_refresh.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects, same subprocess argv/cwd/env. No behaviour
  * changes — latent quirks are replicated and flagged inline, not fixed.
@@ -145,7 +145,7 @@ const CONSUMER_BRIDGE_MARKER_RELPATH = path.join('agents', '.event4u-bridge.yml'
  * agent-config package source tree. Shared by the bridge-marker writer guard
  * and the `_is_source_repo` monorepo probe so the literal lives in one place
  * (the only other textual mention is the `_is_source_repo` docstring, matching
- * the Python original's two occurrences for the ADR-051 path-count parity).
+ * the retired Python implementation's two occurrences for the ADR-051 path-count parity).
  */
 const SRC_MARKER_DIR = '.agent-src.uncondensed';
 
@@ -215,7 +215,7 @@ function atomicWrite0644(target: string, body: string, prefix: string): void {
 }
 
 /**
- * Twin of `install._write_consumer_bridge_marker` (module-private). Returns the
+ * Mirrors `install._write_consumer_bridge_marker` (module-private). Returns the
  * written path, or `null` when skipped (dev mode / source repo).
  */
 function _write_consumer_bridge_marker(

package/src/scripts/_cli/cmd_settings_check.ts

@@ -2,8 +2,8 @@
  * `agent-config settings:check` — validate `.agent-settings.yml` against the
  * supported YAML subset (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_settings_check.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_settings_check.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output. Read-only — no filesystem mutation, no network. No behaviour
  * changes; latent quirks are replicated and flagged inline, not fixed.

package/src/scripts/_cli/cmd_settings_migrate.ts

@@ -2,8 +2,8 @@
  * `agent-config settings:migrate` — lift project-local settings into the
  * global store (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_settings_migrate.py` (ADR-200,
- * py2ts migration). The CLI contract mirrors the Python original EXACTLY —
+ * Ported from the retired Python `src/scripts/_cli/cmd_settings_migrate.py` (ADR-200,
+ * py2ts migration). The CLI contract pins the historical contract exactly —
  * same flags, same exit codes, same stdout/stderr split, byte-identical
  * emitted output, same filesystem effects. No behaviour changes; latent quirks
  * are replicated and flagged inline, not fixed.

package/src/scripts/_cli/cmd_sync.ts

@@ -2,8 +2,8 @@
  * `agent-config sync` — replay the installed-tools manifest (ADR-008)
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_sync.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_sync.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same installer invocation. No behaviour changes; latent quirks are
  * replicated and flagged inline, not fixed.

package/src/scripts/_cli/cmd_uninstall.ts

@@ -1,8 +1,8 @@
 /**
  * `agent-config uninstall` — remove bridge markers (Phase 4.1) (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_uninstall.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_uninstall.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects. No behaviour changes — latent quirks are
  * replicated and flagged inline, not fixed.

package/src/scripts/_cli/cmd_update.ts

@@ -2,8 +2,8 @@
  * `agent-config update` — explicit, opt-in update of the version pin
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_update.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_update.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects, same subprocess argv/cwd/env. No behaviour
  * changes — latent quirks are replicated and flagged inline, not fixed.
@@ -140,23 +140,23 @@ function _splitlinesKeepends(text: string): string[] {
 // Replicated module-private helpers (see header parity note)
 // ---------------------------------------------------------------------------
 
-/** Twin of `agent_settings._canonical_settings_path` (file-local private). */
+/** Mirrors `agent_settings._canonical_settings_path` (file-local private). */
 function _canonical_settings_path(project_root: string): string {
     return path.join(project_root, ...LOCAL_PROJECT_SUBDIR, DEFAULT_PROJECT_FILE);
 }
 
-/** Twin of `agent_settings._local_settings_path` (file-local private). */
+/** Mirrors `agent_settings._local_settings_path` (file-local private). */
 function _local_settings_path(project_root: string): string {
     return path.join(project_root, ...LOCAL_PROJECT_SUBDIR, LOCAL_PROJECT_FILE);
 }
 
-/** Twin of `agent_settings._resolve` — absolute, normalised path. */
+/** Mirrors `agent_settings._resolve` — absolute, normalised path. */
 function _resolve(p: string): string {
     return path.resolve(p);
 }
 
 /**
- * Twin of `agent_settings._resolve_cascade_paths` (file-local private).
+ * Mirrors `agent_settings._resolve_cascade_paths` (file-local private).
  *
  * Returns the ordered cascade of in-project settings files (shallow → deep).
  */
@@ -199,7 +199,7 @@ function _resolve_cascade_paths(cwd: string | null, project_path: string | null)
     return out;
 }
 
-/** Twin of `update_check._read_state` (module-private). */
+/** Mirrors `update_check._read_state` (module-private). */
 function _read_state(state_path: string): Record<string, unknown> {
     try {
         const raw = fs.readFileSync(state_path, 'utf-8');
@@ -213,7 +213,7 @@ function _read_state(state_path: string): Record<string, unknown> {
     return {};
 }
 
-/** Twin of `update_check._write_state` (module-private). */
+/** Mirrors `update_check._write_state` (module-private). */
 function _write_state(state_path: string, payload: Record<string, unknown>): void {
     const parent = path.dirname(state_path);
     fs.mkdirSync(parent, { recursive: true });

package/src/scripts/_cli/cmd_upgrade.ts

@@ -3,8 +3,8 @@
  * `agent-config upgrade` — fetch + install the latest global binary + refresh
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_upgrade.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_upgrade.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects, same subprocess argv/cwd/env. No behaviour
  * changes — latent quirks are replicated and flagged inline, not fixed.
@@ -644,7 +644,8 @@ export async function main(argv: string[] | null = null, options: MainOptions =
     _print(
         out,
         '✅  agent-config upgraded' +
-            (doctor_rc === 0 ? ' — doctor green.' : ' — review the doctor findings above.'),
+            (doctor_rc === 0 ? ' — doctor green.' : ' — review the doctor findings above.') +
+            ' Tune settings any time with `agent-config config`.',
     );
     return 0;
 }

package/src/scripts/_cli/cmd_validate.ts

@@ -3,8 +3,8 @@
  * `agent-config validate` — drift detection for the installed-tools manifest
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_validate.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_validate.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem semantics. No behaviour changes — latent quirks are
  * replicated, not fixed.
@@ -77,7 +77,7 @@ class ArgparseExit extends Error {
 /**
  * `pathlib.Path(p)` string form — collapse repeated separators and strip a
  * trailing separator (Python `str(Path("~/.cursor/"))` → `~/.cursor`), keeping
- * a lone root `/`. Mirrors how the Python original wraps every marker/anchor in
+ * a lone root `/`. Mirrors how the retired Python implementation wraps every marker/anchor in
  * `Path(...)` before `str()`-ing it into a message.
  */
 function pyPathStr(p: string): string {

package/src/scripts/_cli/cmd_versions.ts

@@ -1,8 +1,8 @@
 /**
  * `agent-config versions` — list available package versions (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_versions.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_versions.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same subprocess invocation. Read-only (queries npm; never mutates).
  * No behaviour changes; latent quirks are replicated and flagged inline.

package/src/scripts/_cli/explain_last/assumptions.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `assumptions` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/assumptions.py`
- * (ADR-200). Behaviour mirrors the Python original EXACTLY — same string /
+ * Ported from the retired Python `src/scripts/_cli/explain_last/assumptions.py`
+ * (ADR-200). Behaviour pins the historical contract exactly — same string /
  * dict normalisation, same 120-code-point id slice, same `or`-fallback
  * order, same always-array return. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/council.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `council` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/council.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same candidate glob,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/council.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same candidate glob,
  * same ±1h run window, same most-recent pick, same member extraction
  * (first stripped line, 200-code-point slice), and the same deliberate
  * omission of cost-metadata fields. No behaviour changes.

package/src/scripts/_cli/explain_last/halt.ts

@@ -1,8 +1,8 @@
 /**
  * Builder for the `trace.halt` slot.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/halt.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same `halts[-1]` pick,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/halt.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same `halts[-1]` pick,
  * same `None` branches, same scrub passes, same `step` empty-string
  * fallback. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/index.ts

@@ -1,8 +1,8 @@
 /**
  * `agent-config explain last` — execution-trace builder.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/__init__.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same subject derivation,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/__init__.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same subject derivation,
  * same run-id derivation (with the UTC-mtime ISO fallback), same slot
  * aggregation order and key shape, same scrub pass on the run id. No
  * behaviour changes.

package/src/scripts/_cli/explain_last/inputs.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `inputs` and `pack` why-slots for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/inputs.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same resolver reuse,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/inputs.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same resolver reuse,
  * same `None`-on-error branches, same per-knob source attribution, same
  * pack-marker discovery order and key shape. No behaviour changes.
  *
@@ -30,9 +30,9 @@ const _SILENCED_LOGGERS: readonly string[] = [
 ];
 
 /**
- * Faithful twin of the Python `_silence_resolver_warnings` context manager.
+ * Port of the retired Python `_silence_resolver_warnings` context manager.
  *
- * The Python original raises the level of the `scripts.config.profiles` /
+ * the retired Python implementation raises the level of the `scripts.config.profiles` /
  * `scripts.config.presets` loggers to ERROR so a profile/preset read
  * failure does not leak an absolute path on stderr. The TypeScript config
  * twins funnel through a single shared `agent_settings.logger` that only

package/src/scripts/_cli/explain_last/memory.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `memory` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/memory.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same two sources, same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/memory.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same two sources, same
  * coercion order, same `float()` semantics, same `None`-on-empty branch.
  * No behaviour changes.
  *

package/src/scripts/_cli/explain_last/provider.ts

@@ -1,8 +1,8 @@
 /**
  * Builder for the `trace.provider` slot.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/provider.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same video-only gate,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/provider.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same video-only gate,
  * same `video_provider` / `contract.video_provider` extraction order, same
  * `None` branches, same scrub passes. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/render.ts

@@ -1,8 +1,8 @@
 /**
  * Deterministic Markdown projection of an `ExplainTrace`.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/render.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same fixed section
+ * Ported from the retired Python `src/scripts/_cli/explain_last/render.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same fixed section
  * order, same skip-empty-chunk join, same `rstrip()` + trailing newline,
  * same tip-footer text and `with_footer` gate. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/route.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `route` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/route.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same router lookup, same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/route.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same router lookup, same
  * `None`-on-missing-router branch, same scrub passes, same key shape. No
  * behaviour changes.
  *

package/src/scripts/_cli/explain_last/scrubber.ts

@@ -1,8 +1,8 @@
 /**
  * PII / cost-metadata scrubber for the `explain last` trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/scrubber.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same regex sources, same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/scrubber.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same regex sources, same
  * resolution order, same idempotence, same long-string threshold and
  * summary text. No behaviour changes — latent bugs are replicated, not
  * fixed.

package/src/scripts/_cli/explain_last/sections/assumptions.ts

@@ -1,9 +1,9 @@
 /**
  * Render the `Assumptions` section.
  *
- * TypeScript twin of
+ * Ported from the retired Python
  * `src/scripts/_cli/explain_last/sections/assumptions.py` (ADR-200).
- * Byte-identical to the Python original — note the DOUBLE space before the
+ * byte-stable — downstream consumers and checksum gates pin these bytes — note the DOUBLE space before the
  * em-dash in the item line (`{ident}  — recorded`). No behaviour changes.
  */
 

package/src/scripts/_cli/explain_last/sections/council.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Council` section.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/council.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/council.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  */
 
 function _pyTruthy(value: unknown): boolean {

package/src/scripts/_cli/explain_last/sections/halt.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Why halted?` section.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/halt.py`
- * (ADR-200). Byte-identical to the Python original — note the surface
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/halt.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes — note the surface
  * lines are indented by exactly two spaces (`f"  {line}"`). No behaviour
  * changes.
  *

package/src/scripts/_cli/explain_last/sections/header.ts

@@ -1,8 +1,8 @@
 /**
  * Render the trace header (title + subject + started-at).
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/header.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/header.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  */
 
 function _pyTruthy(value: unknown): boolean {

package/src/scripts/_cli/explain_last/sections/index.ts

@@ -1,7 +1,7 @@
 /**
  * Section renderers for the `explain last` Markdown projection.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/__init__.py`
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/__init__.py`
  * (ADR-200). Re-exports each section module under the same name so the
  * orchestrator (`render.ts`) calls them in fixed order, keeping the
  * Markdown output byte-deterministic for the same input `ExplainTrace`.

package/src/scripts/_cli/explain_last/sections/inputs.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Why this profile / preset?` knob table.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/inputs.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/inputs.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  */
 
 function _pyTruthy(value: unknown): boolean {

package/src/scripts/_cli/explain_last/sections/memory.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Memory hits influencing this run` section.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/memory.py`
- * (ADR-200). Byte-identical to the Python original — same `:.2f` score
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/memory.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes — same `:.2f` score
  * formatting, same `score n/a` fallback for non-numeric scores. No
  * behaviour changes.
  *

package/src/scripts/_cli/explain_last/sections/pack.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Active pack` section (Phase 4-discovery aware).
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/pack.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/pack.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  */
 
 function _pyTruthy(value: unknown): boolean {

package/src/scripts/_cli/explain_last/sections/provider.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Why this provider?` section.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/provider.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/provider.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  *
  * Only emitted when `trace.provider` is non-null (the v1 schema bounds this
  * to `subject == "video"` runs where the engine wrote a provider selection

package/src/scripts/_cli/explain_last/sections/route.ts

@@ -1,8 +1,8 @@
 /**
  * Render the `Why this route?` section.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/sections/route.py`
- * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ * Ported from the retired Python `src/scripts/_cli/explain_last/sections/route.py`
+ * (ADR-200). byte-stable — downstream consumers and checksum gates pin these bytes. No behaviour changes.
  */
 
 function _pyTruthy(value: unknown): boolean {

package/src/scripts/_cli/explain_last/state_loader.ts

@@ -1,8 +1,8 @@
 /**
  * Read and validate the persisted `.work-state.json` envelope.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/state_loader.py`
- * (ADR-200). Behaviour mirrors the Python original EXACTLY — the same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/state_loader.py`
+ * (ADR-200). Behaviour pins the historical contract exactly — the same
  * three raising failure modes, the same exit codes (1 / 2 / 0), and the
  * same byte-identical messages (including the `version={value!r}` Python
  * repr). No behaviour changes.

package/src/scripts/_dispatch.bash

@@ -64,6 +64,19 @@ Tier 0 — daily-driver (init → sync → validate → work):
                              (Option-A loop; called by the /implement-ticket command)
   help                       Show this help (default Tier-0; --tier=1|all expands)
   --version, -V              Print package version
+
+TS-shell native (run via the installed `agent-config` binary):
+  setup                      Open the onboarding wizard in the browser (UI server)
+  install                    Open the install wizard (UI server, Step 1 / AI tools)
+  config                     Open the configuration GUI (global default; --project for the project surface)
+  settings                   Open the local Settings GUI (alias of config)
+  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
+  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
+  eval:record                Record a live trigger-eval result into a corpus manifest
 EOF
 
   if [[ "$tier" == "1" || "$tier" == "all" ]]; then
@@ -110,6 +123,11 @@ Tier 1 — power-user (release shape, audit, migration):
                              user-authored files; persists standing consent
                              (install.auto_converge) on first use.
                              Flags: --dry-run | --yes
+  conformance                Consumer conformance contract: doctor --ci +
+                             installed-and-firing checks. Exits non-zero on
+                             a failed check.
+  use                        Switch the active experience/profile
+                             (writes profile.id). Usage: use <profile-id>
   explain                    Read-only decision-chain trace.
                              Usage: explain config | explain rule <name>
                                   | explain route "<text>"
@@ -206,13 +224,14 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   telemetry:record           Append one artefact-engagement event (default-off)
   telemetry:status           Print artefact-engagement telemetry status (read-only)
   telemetry:report           Aggregate the engagement log into a quartile report
+  analyze-session            Read-only post-session report from on-disk runtime state
 EOF
   fi
 
   if [[ "$tier" == "0" ]]; then
     cat <<'EOF'
 
-(Hidden: 15 Tier-1 + 24 Tier-2 commands. Run `./agent-config --help --tier=1`
+(Hidden: Tier-1 and Tier-2 commands. Run `./agent-config --help --tier=1`
 or `--tier=all` to see them. Tier criteria: docs/contracts/command-surface-tiers.md.)
 EOF
   fi

package/src/scripts/_lib/agent_settings.ts

@@ -1,7 +1,7 @@
 /**
  * Centralized loader for `.agent-settings.yml` with user-global fallback.
  *
- * TypeScript twin of `src/scripts/_lib/agent_settings.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/_lib/agent_settings.py` (ADR-200,
  * Phase 2 / Wave 2a). Mirrors the Python module's public API exactly —
  * same exported snake_case names, same semantics, same cascade / anchor /
  * whitelist / merge behavior, same YAML load tolerance, same error types.

package/src/scripts/_lib/agent_src.ts

@@ -1,14 +1,14 @@
 /**
  * Locate artefact source roots across the monorepo physical layout.
  *
- * TypeScript twin of `src/scripts/_lib/agent_src.py` (ADR-200, Phase 2
- * Wave 2a). The public API mirrors the Python module EXACTLY — same
+ * Ported from the retired Python `src/scripts/_lib/agent_src.py` (ADR-200, Phase 2
+ * Wave 2a). The public API pins the historical contract exactly — same
  * exported snake_case names, same root ordering, same logical-relpath
  * computation, same first-win precedence when a logical path resolves
  * across multiple roots, and the same error behaviour
  * (`logical_relpath` throws when a path is under no known root; the
  * collision guard in `_root_specs` throws on duplicate non-empty
- * prefixes). No behaviour changes — latent bugs replicated.
+ * prefixes). Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Phase 4 of the monorepo migration (ADR-017) physically moves source
  * artefacts out of the flat `.agent-src.uncondensed/` directory into
@@ -32,10 +32,10 @@
  *   but accepts repo-relative POSIX strings (used by the condenseor's
  *   output-path computation and the LEGACY_SRC_PREFIX logic).
  *
- * Path handling note: the Python original uses `pathlib.Path` objects.
+ * Path handling note: the retired Python implementation uses `pathlib.Path` objects.
  * This twin uses absolute POSIX path strings as the `Path` equivalent
  * (the host filesystem on the supported platforms is POSIX). All public
- * functions that the Python original typed as `Path` accept/return
+ * functions that the retired Python implementation typed as `Path` accept/return
  * strings here; semantics — `.relative_to`, `.as_posix`, `.resolve`,
  * `.rglob`, `.is_dir`, `.is_file`, `.exists` — are reproduced via the
  * helpers below.
@@ -46,7 +46,7 @@ import { fileURLToPath } from 'node:url';
 
 // --- Path-root configuration (mutable to mirror Python module attributes) ----
 //
-// The Python original derives ROOT from `Path(__file__).resolve().parents[3]`
+// the retired Python implementation derives ROOT from `Path(__file__).resolve().parents[3]`
 // and every other root from it as module-level constants. Tests in
 // `tests/test_agent_src_domains.py` reassign `agent_src.SRC_DOMAINS` directly
 // and clear `agent_src._slug_prefix_cache` to point the resolver at a tmp
@@ -474,7 +474,7 @@ export function* iter_all_sources(): Generator<[string, string]> {
             if (!_isFile(p)) {
                 continue;
             }
-            // The Python original guards `relative_to` with try/except
+            // the retired Python implementation guards `relative_to` with try/except
             // ValueError; here `p` is always under `root` by construction, but
             // we mirror the guard for fidelity.
             if (p !== root && !_isUnder(p, root)) {

package/src/scripts/_lib/agents_overlay.ts

@@ -1,7 +1,7 @@
 /**
  * Resolve files under `agents/<kind>/<name>.md` via the cascade.
  *
- * TypeScript twin of `src/scripts/_lib/agents_overlay.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/_lib/agents_overlay.py` (ADR-200,
  * Phase 2 / Wave 2b). Companion to `agent_settings`: where the settings
  * loader merges YAML, this resolves single-file overlays — overrides,
  * contexts, decisions — to a single deepest match across the in-project