@event4u/agent-config 14.23.0 → 16.0.0

package/src/server/io/yamlIO.ts

@@ -40,6 +40,25 @@ function formatScalar(value: unknown): string {
     return yamlDump(value, { lineWidth: -1, flowLevel: 0 }).replace(/\n$/, '').trim();
 }
 
+/**
+ * A NESTED mapping key, as both the presence probe and the insertion walk read
+ * one. Shared so the writer and its own existence-probe cannot drift apart —
+ * that drift is the shape this file has now hit four times.
+ *
+ * `-` is in the class because a dashed key is ordinary YAML (`first-name`,
+ * `dry-run`, `retry-count`) and `detectIndentWidth` already accepted one.
+ * While this pattern did not, `findScalarLine` could never find such a key:
+ * `mergeIntoTemplate` then wrote a bogus top-level `x.first-principles:` line
+ * beside the real nested one and the intended value was never written — a save
+ * that silently did nothing — and `upsertScalar` appended another child line on
+ * EVERY call, growing without bound until the file stopped parsing.
+ *
+ * `.` stays OUT, deliberately. A dotted key is the FLAT form, which
+ * `replaceFlatDottedKey` owns; letting this pattern match `a.b:` would make the
+ * nested probe claim a line that is one key literally named "a.b".
+ */
+const NESTED_KEY_RE = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:/;
+
 interface FlatEntry {
     path: string[];
     value: unknown;
@@ -68,6 +87,25 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
     const key = dottedPath[dottedPath.length - 1];
 
     const lines = template.split('\n');
+    const at = findScalarLine(lines, sections, key);
+    if (at === -1) return template;
+    const width = detectIndentWidth(lines);
+    lines[at] = `${' '.repeat(width * sections.length)}${key}: ${formatScalar(value)}`;
+    return lines.join('\n');
+}
+
+/**
+ * Index of the line holding the scalar at `sections`/`key`, or -1.
+ *
+ * Split out of `replaceScalar` so that "is this path present?" is answerable
+ * WITHOUT writing. `mergeIntoTemplate` used to infer presence from
+ * `replaceScalar` returning a changed string, which conflates "absent" with
+ * "present and already equal to the value being written" — under that test a
+ * no-op write reads as a miss and the caller appends a duplicate mapping key.
+ * A presence question answered by a mutation's side effect is the shape to
+ * look for here; the file already carries two earlier rounds of it.
+ */
+function findScalarLine(lines: readonly string[], sections: readonly string[], key: string | undefined): number {
     // The document's own width, the same read `upsertScalar` performs.
     //
     // R2 round 5, finding 1, and it is the second half of round 4's finding 7.
@@ -84,9 +122,7 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
     // A writer and its own existence-probe disagreeing about the format is the
     // shape to look for whenever one of a pair is taught something new.
     const width = detectIndentWidth(lines);
-    const targetIndent = ' '.repeat(width * sections.length);
     const currentPath: (string | null)[] = new Array<string | null>(sections.length).fill(null);
-    const formatted = formatScalar(value);
 
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
@@ -98,7 +134,7 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
         const level = indentLen / width;
         if (level > sections.length) continue;
 
-        const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(stripped);
+        const m = NESTED_KEY_RE.exec(stripped);
         if (!m) continue;
         const lineKey = m[1];
         if (lineKey === undefined) continue;
@@ -115,10 +151,9 @@ export function replaceScalar(template: string, dottedPath: string[], value: unk
         const parentsMatch = sections.every((s, idx) => currentPath[idx] === s);
         if (!parentsMatch) continue;
         if (lineKey !== key) continue;
-        lines[i] = `${targetIndent}${key}: ${formatted}`;
-        return lines.join('\n');
+        return i;
     }
-    return template;
+    return -1;
 }
 
 /**
@@ -182,11 +217,21 @@ export function detectIndentWidth(lines: readonly string[]): number {
  */
 export function upsertScalar(template: string, dottedPath: string[], value: unknown): string {
     if (dottedPath.length === 0) return template;
-    const replaced = replaceScalar(template, dottedPath, value);
-    if (replaced !== template) return replaced;
-
     const sections = dottedPath.slice(0, -1);
     const key = dottedPath[dottedPath.length - 1] as string;
+
+    // Presence is asked, never inferred from the write changing the text. The
+    // string compare that used to stand here read "key already holds this
+    // value" as "key absent" and fell through to the append below — so saving
+    // the wizard's council page twice WITHOUT changing a toggle wrote a second
+    // `api_on_quota:` into the same block, over two `{ok: true}` responses, and
+    // left `.ai-council.yml` rejected by a strict parser. Third instance of one
+    // shape in this file; `findScalarLine` exists to end it, and a fix that
+    // taught only `mergeIntoTemplate` would have left the live path here.
+    if (findScalarLine(template.split('\n'), sections, key) !== -1) {
+        return replaceScalar(template, dottedPath, value);
+    }
+
     const formatted = formatScalar(value);
     const lines = template.split('\n');
     // The document's OWN indent width, not an assumed two.
@@ -228,7 +273,7 @@ export function upsertScalar(template: string, dottedPath: string[], value: unkn
             if (line.trim() === '' || line.trim().startsWith('#')) continue;
             const indentLen = line.length - line.trimStart().length;
             if (indentLen !== indent.length) continue;
-            const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(line.trim());
+            const m = NESTED_KEY_RE.exec(line.trim());
             if (m !== null && m[1] === want) {
                 found = i;
                 break;
@@ -269,23 +314,136 @@ export function upsertScalar(template: string, dottedPath: string[], value: unkn
     return lines.join('\n');
 }
 
+/**
+ * Rewrite an existing top-level `a.b.c: value` line — the FLAT form
+ * `mergeIntoTemplate` itself appends when a path has no template entry.
+ * Returns the template unchanged when no such line exists.
+ *
+ * `replaceScalar` cannot see this line: its key pattern is
+ * `[A-Za-z_][A-Za-z0-9_]*`, with no dot, so a path this module appended on
+ * one pass is invisible to the probe on the next and `mergeIntoTemplate`
+ * appends a SECOND copy. Two wizard saves therefore produce a file carrying
+ * duplicate mapping keys — a strict parser rejects it outright, which is what
+ * wedged `task release`: its `sync` step exits 2 with "Map keys must be
+ * unique" before the release does any git work.
+ *
+ * A pre-existing duplicate run is COLLAPSED, not merely updated: the first
+ * occurrence keeps its position and takes the new value, every later one is
+ * dropped. Collapsing is value-neutral — a lenient reader already resolved
+ * such a run last-wins — and it is the only way a file corrupted by the old
+ * behaviour becomes parseable again through the ordinary write path.
+ *
+ * Deliberately NOT folded into `replaceScalar`: `upsertScalar` calls that
+ * probe and documents the flat form as the WRONG shape for a nested key (a
+ * reader sees one key literally named "a.b"). Teaching the shared probe to
+ * match it would make `upsertScalar` write into that broken line instead of
+ * creating the nesting. The flat form is legitimate only here, where this
+ * function is the one that wrote it.
+ */
+function replaceFlatDottedKey(
+    template: string,
+    dottedPath: string[],
+    value: unknown,
+): { found: boolean; body: string } {
+    if (dottedPath.length < 2) return { found: false, body: template };
+    const flat = dottedPath.join('.');
+    const lines = template.split('\n');
+    const hits: number[] = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined) continue;
+        // Top level only — an indented `a.b:` is somebody else's child key.
+        if (line.length !== line.trimStart().length) continue;
+        const m = /^([A-Za-z_][A-Za-z0-9_.-]*)\s*:/.exec(line);
+        if (m === null || m[1] !== flat) continue;
+        hits.push(i);
+    }
+    if (hits.length === 0) return { found: false, body: template };
+    lines[hits[0] as number] = `${flat}: ${formatScalar(value)}`;
+    // Drop the later copies back-to-front so the earlier indices stay valid.
+    for (let i = hits.length - 1; i >= 1; i--) lines.splice(hits[i] as number, 1);
+    return { found: true, body: lines.join('\n') };
+}
+
+/**
+ * Drop every top-level `a.b.c:` line for a path whose NESTED form the caller
+ * has just resolved.
+ *
+ * Which reader this preserves, because the two forms can disagree and only one
+ * of them is ever consulted: by YAML semantics `a.b.c` is reached by walking
+ * the `a` mapping, so a top-level key literally named "a.b.c" is a DIFFERENT
+ * path that no lookup of the dotted one visits. Removing it therefore changes
+ * no reader's answer — strict and lenient alike already resolve through the
+ * nesting — while leaving it keeps the one line a human scanning the file
+ * reads as the value, saying something the program never agreed with. It
+ * cannot self-heal either: the duplicate-key pass sees a single occurrence,
+ * and `mergeIntoTemplate` writes the nested side, so the line is permanent.
+ *
+ * The nested twin IS the safety argument, not a convenience. A flat `a.b:`
+ * standing ALONE is a key somebody may have meant — `mergeIntoTemplate`'s own
+ * fallback branch writes exactly that shape for a path the template lacks — and
+ * this function is never reached for one: the caller takes the
+ * `replaceFlatDottedKey` branch instead, which updates that line in place.
+ *
+ * Two bounds, each of which turns the sweep into a data-loss bug if dropped:
+ *
+ *   - Two segments minimum. A one-segment path joins to a name with no dot, so
+ *     the match below would hit the very line `replaceScalar` just wrote and
+ *     delete the key the caller asked to set — a rewrite silently becoming a
+ *     removal. Same guard, same reason, as `replaceFlatDottedKey`.
+ *   - Top level only, the bound `replaceFlatDottedKey` also draws: an INDENTED
+ *     `a.b:` is somebody else's child key (`parent:` / `  a.b:` means
+ *     `parent['a.b']`), an unrelated path this sweep has no claim on.
+ */
+function dropFlatDottedTwins(template: string, dottedPath: string[]): string {
+    if (dottedPath.length < 2) return template;
+    const flat = dottedPath.join('.');
+    const lines = template.split('\n');
+    const kept = lines.filter((line) => {
+        if (line.length !== line.trimStart().length) return true;
+        const m = /^([A-Za-z_][A-Za-z0-9_.-]*)\s*:/.exec(line);
+        return m === null || m[1] !== flat;
+    });
+    if (kept.length === lines.length) return template;
+    return kept.join('\n');
+}
+
 /**
  * Apply every leaf change from `newValues` to `templateBody`. Paths that
  * are not present in the template are appended at the end. Comments are
  * preserved for every key that already exists in the template.
+ *
+ * Idempotent: applying the same values twice yields the same document, so a
+ * second wizard save re-writes the flat block instead of duplicating it.
  */
 export function mergeIntoTemplate(templateBody: string, newValues: Record<string, unknown>): string {
     let body = templateBody;
     const appended: string[] = [];
     for (const entry of flatten(newValues)) {
-        const before = body;
-        body = replaceScalar(body, entry.path, entry.value);
-        if (body === before) {
-            // Path is not in the template — append a flat key=value at EOF.
-            // Form coverage is asserted by parity test, so this branch only
-            // fires on hand-edited templates.
-            appended.push(`${entry.path.join('.')}: ${formatScalar(entry.value)}`);
+        const sections = entry.path.slice(0, -1);
+        const leaf = entry.path[entry.path.length - 1];
+        // Presence is asked, never inferred from the write changing the text —
+        // see `findScalarLine`. Writing the value it already holds is a hit.
+        if (findScalarLine(body.split('\n'), sections, leaf) !== -1) {
+            body = replaceScalar(body, entry.path, entry.value);
+            // The nested form won, so any flat twin of this same path is dead
+            // and stays dead. The probe above is what licenses the removal:
+            // without a nested key to resolve through, a flat `a.b:` is the
+            // real entry and the branch below owns it.
+            body = dropFlatDottedTwins(body, entry.path);
+            continue;
+        }
+        // Not in the template's nested form. It may still be here as a flat
+        // dotted line this function appended on an earlier pass.
+        const flat = replaceFlatDottedKey(body, entry.path, entry.value);
+        if (flat.found) {
+            body = flat.body;
+            continue;
         }
+        // Genuinely absent — append a flat key=value at EOF. Form coverage is
+        // asserted by parity test, so this branch only fires on hand-edited
+        // templates.
+        appended.push(`${entry.path.join('.')}: ${formatScalar(entry.value)}`);
     }
     if (appended.length > 0) {
         if (!body.endsWith('\n')) body += '\n';

package/src/server/schemas/settings.ts

@@ -173,7 +173,7 @@ export const settingsSchema = z.object({
     }),
     chat_history: z.object({
         enabled: z.boolean().default(true).describe(
-            'Persist a structured log of every chat turn to .agent-config/chat-history/ so /chat-history:show, :import, and :learn can replay sessions. Turn off if you never want chat transcripts on disk.',
+            'Persist a structured log of every chat turn to agents/runtime/.agent-chat-history (JSONL). Recording only — no command in this package replays a session from the file; it is a record on disk that a human or a later tool can read. Turn off if you never want chat transcripts on disk.',
         ),
         frequency: chatFreq.default('per_turn').describe(
             'How often the chat-history writer flushes to disk. per_turn = after every user / agent exchange (default, lowest data loss on crash). per_phase = at phase boundaries (cheaper I/O). per_tool = after every tool call (highest fidelity, noisiest log).',
@@ -247,7 +247,27 @@ export const settingsSchema = z.object({
         fidelity_mode: fidelityMode.default('strict').describe(
             'How strictly the agent must follow a user-provided prototype / mockup / design system (consumed by the design-fidelity rule). strict = build 1:1, every visible deviation needs confirmation; structural = structure locked, silent gaps fillable with a stated assumption; hard-floor = any deviation is never autonomous.',
         ),
-    }).default({ fidelity_mode: 'strict' }),
+        approximation: z
+            .object({
+                enabled: z.boolean().default(false).describe(
+                    'Whether a value INSIDE the configured tolerance may be replaced by the project\'s own token without a per-value confirmation. Ships false. The distance from the artifact\'s value to the nearest project token is computed and REPORTED on every value row regardless of this switch — what it decides is whether the agent may act on it without asking. Turning it on for a whole install is a consumer-facing default flip and is owner-reserved (agents/roadmaps/stubs/road-to-frontend-power-default-flip.md); design.fidelity_mode: hard-floor overrides it to off.',
+                ),
+                tolerance: z
+                    .object({
+                        color: z.number().nullable().default(null).describe(
+                            'Colour distance below which a value may be reconciled, in OKLab ΔEOK. Ships null, and null means "preserve and report" rather than "reconcile freely". No number is set because none is supported: zero of seven design-to-code benchmarks in the evidence set score token conformance, and a number in a config file — even flagged unmeasured — shapes behavior and acquires the authority of a default. Not an RGB channel delta: RGB distance is not perceptually uniform.',
+                        ),
+                        length: z.number().nullable().default(null).describe(
+                            'Length distance below which a value may be reconciled, in absolute CSS pixels. Ships null, same reasoning as color. GitHub Primer\'s ±1px spacing widening is recorded as an externally observed candidate in src/scripts/_lib/design_tolerance.ts and is deliberately not the shipped value; max(1px, 2%) was rejected for growing more permissive at large dimensions with no evidence that this is wanted.',
+                        ),
+                    })
+                    .default({ color: null, length: null }),
+            })
+            .default({ enabled: false, tolerance: { color: null, length: null } }),
+    }).default({
+        fidelity_mode: 'strict',
+        approximation: { enabled: false, tolerance: { color: null, length: null } },
+    }),
     consistency: z.object({
         cross_source: crossSourceMode.default('on').describe(
             'Consumed by the cross-source-consistency rule. When the agent works from multiple sources (ticket text, an attached image/mockup, the spec, the codebase) it checks them against each other and asks before proceeding on a discrepancy — instead of silently guessing. on (default) = surface every real cross-source contradiction / silent-scope-expansion as one question; auto = surface only high-confidence contradictions, state low-confidence as an assumption; off = no cross-source checking.',
@@ -450,11 +470,11 @@ export const settingsSchema = z.object({
         }),
     }),
     continuity: z.object({
-        auto_record: z.enum(['on', 'off']).default('off').describe(
-            'Deterministic continuity-record writer at session end (road-to-continuity-writer-activation Phase 1). on = the session-eol concern writes the continuity_record capsule variant on Stop for a substantive session that has claimed a roadmap; every field is computed from on-disk state, with no model spend and no subprocess. off (default) = no automatic record — while session:recycle is still the normal path, a second producer on it before the parity evidence is in would be unverified.',
+        auto_record: z.enum(['on', 'off']).default('on').describe(
+            'Deterministic continuity-record writer at session end (road-to-continuity-writer-activation Phase 1). on (default since 2026-09-10) = the session-eol concern writes the continuity_record capsule variant on Stop for a substantive session that has claimed a roadmap; every field is computed from on-disk state, with no model spend and no subprocess. off = no automatic record, and only the explicit agent-config session:recycle writes one. The default flipped once the parity evidence landed, so the normal path carries an automatic writer rather than a remembered command; session:recycle is retained because the automatic writer skips a session that claimed no roadmap and omits the git-status anchors.',
         ),
         run_checkpoints: z.enum(['on', 'off']).default('on').describe(
-            'Deterministic run-checkpoint production at session end (road-to-continuity-writer-activation Phase 1.4). on (default) = a session above the recycle threshold and inside a running roadmap contract leaves agents/runtime/state/checkpoints/<run>.json, so a killed run resumes from a derived checkpoint rather than from bookkeeping. off = no checkpoint; continuity writing, the recycle advisory and the context-fill surface are unaffected. Default ON because it is the behaviour the tree already had — the switch exists to make the three session-end handlers independently disableable, not to change what ships.',
+            'Deterministic run-checkpoint production at session end (road-to-continuity-writer-activation Phase 1.4). on (default) = a session above the recycle threshold and inside a running roadmap contract leaves agents/runtime/state/checkpoints/<run>.json, so a killed run resumes from a derived checkpoint rather than from bookkeeping. off = no checkpoint; continuity writing, the recycle advisory and the context-fill surface are unaffected. Default ON because it is the behavior the tree already had — the switch exists to make the three session-end handlers independently disableable, not to change what ships.',
         ),
     }),
     memory: z.object({

package/src/shared/settingsSurface.ts

@@ -23,7 +23,13 @@ export type JsonLike =
     | { [key: string]: JsonLike };
 
 export interface SurfaceEntry {
-    type: string;
+    /**
+     * JSON-schema type. A STRING for an ordinary key, and an ARRAY for a
+     * nullable one (`["number", "null"]`) — which is what the generator has
+     * always produced for a `z.number().nullable()`, though this field was
+     * declared `string` until the first such key shipped.
+     */
+    type: string | string[];
     default?: JsonLike;
     enum?: Array<string | number>;
     description?: string;
@@ -129,7 +135,12 @@ export function computeSurfaceDelta(oldS: SettingsSurface, newS: SettingsSurface
             continue;
         }
         const o = oldS.entries[key] as SurfaceEntry;
-        if (o.type !== n.type) {
+        // `sameJson`, not `!==`: `type` is an array for a nullable key, and two
+        // structurally equal arrays are never `===`. Left as a strict compare
+        // it reported `type_changed` on EVERY version bump for every nullable
+        // key, forever — caught by the identical-surface test the moment the
+        // first one shipped (`design.approximation.tolerance.*`).
+        if (!sameJson(o.type, n.type)) {
             changes.push({ key, kind: 'type_changed', old: o, new: n });
         }
         if (!sameJson(o.default, n.default)) {

package/src/templates/compact-instructions.md

@@ -1,9 +1,14 @@
 # Compact-instructions template — lose less when you compact anyway
 
 Fallback lane of `road-to-token-economy-recycling` Phase 3.3. The recycle
-envelope (`agent-config session:recycle` + `/clear`) is the primary path —
-validated state, no summarizer. This template is for the user who compacts
-instead: Claude Code honours a `# Compact instructions` section in the
+envelope is the primary path — validated state, no summarizer — and since
+2026-09-10 it is written for you: the `session-eol` concern publishes the
+continuity record at session end by default (`continuity.auto_record`), so
+`/clear` resumes from it with no command to remember.
+`agent-config session:recycle` still exists as an explicit affordance for the
+cases the automatic writer does not cover (a session that claimed no roadmap, or
+a record that should carry the `git status` anchors). This template is for the
+user who compacts instead: Claude Code honours a `# Compact instructions` section in the
 project's `CLAUDE.md` when it summarizes (see the "Manage context
 proactively" section of the host's cost docs), and `/compact <instructions>`
 accepts the same guidance ad hoc.

package/dist/agent-src/commands/chat-history/import.md

@@ -1,170 +0,0 @@
----
-model_tier: medium
-name: chat-history-import
-pack: memory
-visibility: internal
-cluster: chat-history
-sub: import
-description: Surface prior chat-history sessions as a numbered table, let the user pick one, read it silently, and emit a short summary plus a resume offer — selective, user-driven cross-session import
-suggestion:
-  eligible: false
-  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
-workspaces:
-  - agent-config-maintainer
-packs:
-  - memory
----
-<!-- cloud_safe: noop -->
-
-# /chat-history import
-
-Read-only, **user-driven** cross-session import. Surfaces prior
-sessions logged in `agents/runtime/.agent-chat-history` as a numbered table,
-the user picks **one**, the agent reads that session **silently**
-and emits a 2–5 sentence summary, then offers to resume the last
-task from that session. The agent does **not** render entries
-verbatim, auto-import, or rewrite the user's context without an
-explicit instruction.
-
-This is the opt-in counterpart to the read-path filter (Phase 3 of
-`road-to-chat-history-session-isolation`): default reads stay
-session-scoped; `import` is the explicit surface for crossing the
-session boundary. For project-improving learnings derived from a
-prior session, see [`/memory mine-session --mode=proposals`](../memory/mine-session/command.md).
-
-## When NOT to use
-
-- Inspect the current session — use the host's native transcript /
-  session view, or `./scripts-run scripts/chat_history read`.
-- Generate a learning proposal from a prior session — use
-  [`/memory mine-session --mode=proposals`](../memory/mine-session/command.md),
-  which frames the session's signals and runs `learning-to-rule-or-skill`.
-- Bulk-import all sessions — out of scope for v1. One session per
-  invocation; multi-pick is v2.
-- Search prior sessions by content — out of scope for v1; no fuzzy
-  search, no full-text grep. The user picks by `last_ts` and
-  `summary` from the listing.
-
-## Steps
-
-### 1. Check if enabled
-
-Read `chat_history.enabled` from `.agent-settings.yml`. If `false`
-or the section is missing, say so and stop:
-
-```
-> 📒 chat-history is disabled (chat_history.enabled = false).
-> Set it to true in .agent-settings.yml to start logging.
-```
-
-### 2. List sessions
-
-Run `./scripts-run scripts/chat_history sessions --json --limit 20 --summary`.
-The helper returns an array of
-`{id, count, first_ts, last_ts, preview, summary}` sorted by
-`last_ts` desc. The `summary` field is built **inside the helper**
-from at most 10 sampled entries per session (5 oldest + 5 newest) —
-token-cheap, no need to ever read the full body for the picker.
-Default excludes empty buckets — only sessions with at least one
-body entry are surfaced.
-
-If the array is empty, stop:
-
-```
-> 📒 No prior sessions found in agents/runtime/.agent-chat-history.
-```
-
-### 3. Surface as a numbered table
-
-Render the sessions as a markdown table — the row number is the
-option (per `user-interaction` Iron Law: numbered options for any
-picker). The session `id` is noise to humans; keep it **internal**
-for step 5's `read --session <id>` call and never render it.
-Format:
-
-```
-Pick a session to import:
-
-| #  | Date             | Entries | Summary |
-|----|------------------|---------|---------|
-| 1  | YYYY-MM-DD HH:MM | N       | {summary} |
-| 2  | YYYY-MM-DD HH:MM | N       | {summary} |
-| …  |                  |         |           |
-| N  | —                | —       | abort — do not read any session |
-```
-
-Format the timestamp as `YYYY-MM-DD HH:MM` (drop seconds and
-timezone — the listing is for orientation, not forensics). Lead the
-`Summary` cell with the helper's `summary` field — that is the
-rough arc the user picks by (`<first user msg> → <last user msg>`
-for normal sessions, or `(N entries — no user prompts; t-mix: …)`
-for tool-only sessions). Do **not** truncate or rewrite `summary` —
-markdown table wrap handles long values. Always include an explicit
-`abort` row as the last numbered option. Track option-number → `id`
-internally so step 5 can call `./scripts-run scripts/chat_history read
---session <id>` with the right id.
-
-### 4. Wait for the pick
-
-**One question per turn** (per `ask-when-uncertain`). Do not chain
-the listing with anything else; do not auto-pick; do not surface a
-default. Wait for the user's response.
-
-If the user picks the abort option, stop without reading.
-
-### 5. Read the picked session silently
-
-Run `./scripts-run scripts/chat_history read --session <id> --last <count>`,
-where `<count>` is the picked row's `count` from step 2. The
-`--last` flag is **required** — the helper defaults to 5 entries,
-which would silently truncate any longer session. The helper returns
-the entries as JSON.
-
-**Do not render the entries.** The verbose dump was reversed by the
-user — token cost and scroll fatigue outweighed the verbatim
-contract. Read the JSON in-context, then proceed to step 6.
-
-### 6. Summarise and offer to resume
-
-Emit a **2–5 sentence** summary of the picked session: the topic,
-what was decided or built, and where it left off (the last task in
-progress, if any). Plain prose — no bullets, no headings, no
-verbatim quotes.
-
-Then offer the resume choice as numbered options
-(per `user-interaction`), one question per turn:
-
-```
-1. resume — pick up the last task from that session
-2. stop — keep the summary in context, do nothing else
-```
-
-Wait for the pick. Do **not** auto-resume. If the user picks
-`resume`, hand off to the relevant skill or command for that work;
-do not silently start editing files. The agent does not write to
-the current session's log on the user's behalf without an explicit
-instruction.
-
-## Gotchas
-
-- **Summary, not verbatim.** Earlier Council R2-2 favoured verbatim
-  rendering; reversed in practice — too slow, too token-expensive.
-  The agent reads the picked session in-context and emits a 2–5
-  sentence summary. Verbatim rendering is no longer part of the
-  contract.
-- **One pick per invocation.** Multi-pick is v2. If the user wants
-  a second session, run `/chat-history import` again.
-- **Read-only.** This command never writes to `agents/runtime/.agent-chat-history`
-  and never rotates.
-- **`<legacy>` and `<unknown>` buckets** show up like any other
-  session id when they have body entries — the user can pick them
-  too. The helper aggregates body entries with no `s` field into
-  `<legacy>` and entries with `s == "<unknown>"` into `<unknown>`.
-
-## See also
-
-- [`/memory mine-session --mode=proposals`](../memory/mine-session/command.md) — pick a prior session and turn it into a project-improving proposal via `learning-to-rule-or-skill` (the former `/chat-history learn`)
-- [`chat-history-platform-hooks`](../../../agents/settings/contexts/chat-history-platform-hooks.md) — read contract, isolation default, opt-in cross-session path
-- [`scripts/chat_history.ts`](../../../scripts/chat_history.ts) — `sessions` and `read --session` CLI surface
-- [`user-interaction`](../../rules/user-interaction.md) — numbered-options Iron Law
-- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — one-question-per-turn Iron Law

package/dist/agent-src/commands/chat-history.md

@@ -1,63 +0,0 @@
----
-model_tier: medium
-name: chat-history
-disable-model-invocation: true
-argument-hint: "[import]"
-pack: memory
-visibility: internal
-description: Chat-history orchestrator — routes to import (selective cross-session resume). Mining moved to /memory mine-session; raw-log inspection uses the host's native transcript view.
-cluster: chat-history
-routes_to: [chat-history-import]
-type: orchestrator
-suggestion:
-  eligible: true
-  trigger_description: "import a prior session into the current chat, resume a previous session, pull a prior session in verbatim"
-  trigger_context: "user wants to pull a prior session from the agents/runtime/.agent-chat-history log into the current chat verbatim and optionally resume it"
-workspaces:
-  - agent-config-maintainer
-packs:
-  - memory
----
-
-<!-- cloud_safe: noop -->
-
-# /chat-history
-
-Top-level orchestrator for the `/chat-history` family. Writes and overflow
-handling are driven entirely by platform hooks + `scripts/chat_history.ts`
-internals (`road-to-chat-history-hook-only`); the surfaced sub-command is
-read-only on the cross-host log (`agents/runtime/.agent-chat-history`).
-Sessions coexist in one log file — each entry self-tags via the `s` field —
-so there is no ownership layer to recover from.
-
-## Sub-commands
-
-| Sub-command | Routes to | Purpose |
-|---|---|---|
-| `/chat-history import` | `commands/chat-history/import.md` | List prior sessions, pick one, render its entries verbatim — selective cross-session import + resume |
-
-**Consolidated elsewhere** (see `road-to-memory-pipeline-consolidation.md`):
-
-- **Mining a session for learnings** — use
-  [`/memory mine-session --mode=proposals`](../memory/mine-session/command.md)
-  (the former `/chat-history learn`; now the single mining command, reading the
-  same cross-host log).
-- **Inspecting the raw log** (size, entries, header) — use the host's native
-  transcript / session view; the bespoke `/chat-history show` was dropped as
-  redundant.
-
-## Dispatch
-
-1. Parse the user's argument: `/chat-history <sub-command> [args]`.
-2. The only sub-command is `import`. Bare `/chat-history` (or an unknown
-   sub-command) → route to `import`.
-3. Load `commands/chat-history/import.md` and follow its `## Steps` verbatim
-   with the remaining args.
-
-## Rules
-
-- **Do NOT commit, push, or open a PR** — `import` is read-only (it renders a
-  prior session into the current chat; it writes nothing).
-- **Do NOT chain sub-commands.** One `/chat-history import` per turn.
-- **`import` crosses the session boundary** — only run it when the user
-  explicitly asked for cross-session reading.