session-orchestrator 3.21.0 → 3.22.0

package/scripts/lib/io.mjs

@@ -98,6 +98,45 @@ const DENY_REASON_MAX = 16_000;
  */
 const WARN_MESSAGE_MAX = 16_000;
 
+/**
+ * Hard ceiling (in BYTES, including the trailing newline) for the whole
+ * {@link emitRewrite} envelope.
+ *
+ * Denominated in bytes, not characters, unlike {@link DENY_REASON_MAX} — the
+ * quantity that actually matters here is what the kernel pipe buffer holds, and
+ * a character count only approximates that for ASCII. `Buffer.byteLength` makes
+ * the bound exact for any input.
+ *
+ * Derivation, measured 2026-08-22 against the repo's own AUQ corpus
+ * (`node scripts/auq-audit.mjs --json`, 70 real question blocks, HEAD clean):
+ *
+ * | quantity                                                  | measured |
+ * |-----------------------------------------------------------|----------|
+ * | largest real tool-input in the corpus (plan/SKILL.md:136) | 1 369 B  |
+ * | median / mean over all 70 blocks                          | 549 / 547 B |
+ * | max question text · header · label · description · preview | 269 · 12 · 48 · 180 · 252 |
+ * | protocol-cap worst case: 4 questions × 4 options, each field at its measured max | 9 785 B |
+ *
+ * The protocol caps come from `.claude/rules/ask-via-tool.md` § AUQ-003 (1–4
+ * questions, 2–4 options); the corpus tops out at 3 questions and 4 options, so
+ * the 9 785 B row is already an over-estimate of anything observed. 32 768 sits
+ * **3.35× above that worst case** and **23.9× above the largest real payload**,
+ * while being exactly **half** the 65 536-byte kernel pipe buffer — so a
+ * cap-sized envelope fits one buffer with the whole second half to spare, and a
+ * rewrite that expands its source text several-fold is still nowhere near the
+ * ceiling.
+ *
+ * ## Why this REJECTS where {@link DENY_REASON_MAX} CLAMPS
+ *
+ * A deny reason is prose: clipping it leaves a valid deny with a shorter
+ * explanation. `updatedInput` is structure: clipping it mid-object yields
+ * unparseable JSON, which the harness reads as no-decision — the truncated
+ * envelope would silently discard the rewrite while looking like a successful
+ * emit. So an over-ceiling payload is never sliced; it is refused whole, and the
+ * tool call proceeds with its original input (see {@link emitRewrite}).
+ */
+const REWRITE_ENVELOPE_MAX_BYTES = 32_768;
+
 /**
  * Reason substituted when a caller denies without supplying one.
  *
@@ -489,6 +528,206 @@ export function emitWarn(message) {
   process.exit(0);
 }
 
+/**
+ * Rewrite the **tool input** of the current PreToolUse invocation and let the
+ * normal flow continue: emit exactly one JSON object on stdout, then exit **0**.
+ *
+ * This is the third PreToolUse verb, alongside {@link emitDeny} ("block") and
+ * {@link emitWarn} ("allow, with a notice"). It decides nothing — it hands the
+ * harness a replacement input and steps out of the way.
+ *
+ * ## Emitted payload (single stdout line, nothing else on stdout)
+ *
+ * ```json
+ * {"hookSpecificOutput":{"hookEventName":"PreToolUse","updatedInput":{…}}}
+ * ```
+ *
+ * ## THE TRAP: there is deliberately no `permissionDecision`, and no way to add one
+ *
+ * The shipped Claude Code binary (2.1.239) routes the rewrite through a branch
+ * that is guarded on the ABSENCE of a permission decision:
+ *
+ * ```js
+ * if (p.updatedInput && p.permissionBehavior === void 0)
+ *   yield { type: "hookUpdatedInput", updatedInput: p.updatedInput };
+ * ```
+ *
+ * Pair `updatedInput` with `permissionDecision: "allow"` and a different branch
+ * takes it: the input is still replaced, but the **permission stage is skipped**.
+ * For most tools that is merely a lost prompt. For `AskUserQuestion` it is fatal,
+ * because the permission stage IS the question card — `checkPermissions` returns
+ * `behavior: "ask"`, and that "ask" is what renders the options to the operator.
+ * An `allow` there does not approve the question; it routes the question PAST the
+ * human. The operator is never asked, nothing errors, and the omission is
+ * invisible from both ends.
+ *
+ * The prevention is structural, not advisory. This function takes **one**
+ * parameter — the tool input — and builds `hookSpecificOutput` here as a
+ * two-key object literal with no spread, no `opts` bag, and no caller-reachable
+ * key. There is no argument a caller can pass that lands as a sibling of
+ * `updatedInput`; a `permissionDecision` key inside the caller's own object
+ * nests one level deeper (`updatedInput.permissionDecision`), where the harness
+ * ignores it. Adding a spread or an options parameter here would re-open the
+ * trap — that is what `tests/lib/io.test.mjs` pins, since the structure cannot
+ * defend itself against a future edit.
+ *
+ * A hook that needs BOTH a permission decision and a rewrite cannot have both:
+ * choose the decision, because a rewrite that skips the operator's question is
+ * the exact failure this function is shaped to avoid.
+ *
+ * ## `updatedInput` is the COMPLETE tool input, never a patch
+ *
+ * The bundle types it as a map, not a diff (`updatedInput: oo(H(), Pn())`), and
+ * the harness substitutes it wholesale. A caller that passes only the fields it
+ * changed **deletes every field it omitted** — for `AskUserQuestion`, passing
+ * `{questions: [{question: '…'}]}` drops the options and the header along with
+ * them. Read the original input from the hook payload, modify it, and pass the
+ * whole object back.
+ *
+ * ## Fail-closed on an invalid rewrite is the HARNESS's behaviour, not ours
+ *
+ * A syntactically fine but schema-invalid `updatedInput` (5 questions where 4 is
+ * the cap, 1 option where 2 is the minimum) does not slip through as a silent
+ * pass — the bundle turns it into a deny:
+ *
+ * ```js
+ * if (!f.success && m.length > 0) { … u = { behavior: "deny", message: g, … }; continue }
+ * ```
+ *
+ * So a malformed rewrite costs the tool call, not the operator's trust. Callers
+ * are still responsible for emitting a schema-valid input; this note only
+ * records that the failure direction is safe.
+ *
+ * ## EVIDENCE STATUS — code-evidence, not runtime-evidence
+ *
+ * Everything above is read out of the shipped 2.1.239 bundle. **No hook with a
+ * matcher of `AskUserQuestion` has ever run in this repo**, so the rewrite
+ * branch has not been observed executing. The runtime proof needs a session
+ * restart and is outstanding. Treat the branch conditions as verified source and
+ * the end-to-end behaviour as expected-but-unconfirmed.
+ *
+ * ## When emitRewrite is the WRONG verb
+ *
+ *  1. **You need to block.** A rewrite carries no denial; the tool call proceeds
+ *     whatever the new input says. Use {@link emitDeny}.
+ *  2. **You need to pre-approve.** Skipping the permission prompt is
+ *     `permissionDecision: "allow"`, and combining it with a rewrite is the trap
+ *     above. Emit one or the other, never a hand-rolled envelope carrying both.
+ *  3. **The event is not PreToolUse.** `hookEventName` is hardcoded; PostToolUse
+ *     / Stop / SubagentStop have no `updatedInput` at all and signal through a
+ *     top-level `decision` (same precondition as {@link emitDeny}).
+ *  4. **You cannot reconstruct the whole input.** A partial object deletes the
+ *     rest — if the original input is not in hand, do nothing ({@link emitAllow})
+ *     rather than emit a lossy replacement.
+ *
+ * ## Delivery, and why a failed write still exits 0
+ *
+ * The envelope goes out through {@link writeStdoutLineSync}, never
+ * `console.log`: on macOS a piped stdout is asynchronous, so `console.log` +
+ * `process.exit(0)` drops everything past the 65 536-byte kernel pipe buffer and
+ * the rewrite vanishes without a trace. The payload is additionally bounded by
+ * {@link REWRITE_ENVELOPE_MAX_BYTES} — refused whole rather than clipped, since
+ * a clipped JSON object is not a smaller rewrite but an unparseable one.
+ *
+ * ── BV-004: at TODAY'S ceiling the two bounds are not equally load-bearing ────
+ * Measured 2026-08-22 (`console.log` of an N-byte line + `process.exit(0)`,
+ * piped into a reader that sleeps 300 ms before draining, so the buffer really
+ * fills): N=200 000 → 65 536 delivered, N=70 000 → 65 536, **N=32 768 → 32 768
+ * delivered intact**. Since the ceiling refuses anything larger, no payload this
+ * function can emit is big enough for `console.log` to lose — the clamp alone
+ * carries the guarantee today, and the synchronous write is the redundant half.
+ * It stays anyway, and this is the trigger to re-read before touching either:
+ * **raise {@link REWRITE_ENVELOPE_MAX_BYTES} above 65 536 and the sync write
+ * becomes the ONLY thing standing between a large rewrite and silent
+ * truncation.** Swapping in `console.log` "because the cap already protects us"
+ * is safe only for as long as nobody moves the cap — which is precisely the kind
+ * of coupling that rots unremarked. Note also that no behavioural test can
+ * currently distinguish the two writers here (see `tests/lib/io.test.mjs`).
+ *
+ * {@link emitDeny} exits **2** when stdout is unwritable, because its decision is
+ * "block" and with the structured channel gone the exit code is the only
+ * blocking signal left. **This function must not copy that.** `emitRewrite`
+ * holds no decision to preserve: its degraded state is "the tool call runs with
+ * its original input", which is exactly what happens when no envelope is
+ * emitted. Exit 2 would convert that harmless loss into a block —
+ * `scripts/lib/pi-hook-bridge.mjs:389` treats the status unconditionally
+ * (`const blocked = result.status === 2 || …`, evaluated before stdout is
+ * consulted), and the documented contract says exit 2 discards stdout and feeds
+ * stderr back to Claude as an error. On the `AskUserQuestion` path that means
+ * the operator's question is destroyed to protect a wording improvement. Every
+ * failure here therefore degrades to "no stdout, exit 0, loud stderr" — the same
+ * asymmetry {@link emitWarn} documents, for the same reason.
+ *
+ * Never throws, for the reason {@link emitDeny} spells out: a throw unwinds into
+ * the `main().catch(() => emitAllow())` that four hooks install. Here that
+ * catch would be harmless by luck rather than by design, and a hook whose catch
+ * routes to `emitDeny` instead would turn a failed rewrite into a block.
+ *
+ * @param {object} updatedInput  The COMPLETE replacement tool input. A non-object,
+ *        `null`, an array, or a value `JSON.stringify` rejects degrades to a
+ *        no-op plus a stderr diagnostic — never a throw, never a partial emit.
+ * @returns {never}
+ */
+export function emitRewrite(updatedInput) {
+  /**
+   * Abandon the rewrite: say why on stderr, emit nothing, exit 0. The tool call
+   * then runs with its original input — the intended degraded state, not a
+   * fail-open, because this helper never held a decision to lose.
+   *
+   * @param {string} diagnostic
+   * @returns {never}
+   */
+  const bail = (diagnostic) => {
+    try {
+      process.stderr.write(
+        `⚠ io.mjs: emitRewrite ${diagnostic} — leaving the tool input unchanged\n`,
+      );
+    } catch { /* stderr may be closed; the silent no-op below is what matters */ }
+    process.exit(0);
+  };
+
+  if (updatedInput === null || typeof updatedInput !== 'object' || Array.isArray(updatedInput)) {
+    // `updatedInput` is a MAP in the bundle schema, so an array is as wrong as a
+    // string — and an array would serialize into a shape the harness cannot use.
+    bail(
+      `was called with ${Array.isArray(updatedInput) ? 'an array' : String(updatedInput === null ? 'null' : typeof updatedInput)}, not a tool-input object`,
+    );
+  }
+
+  let line;
+  try {
+    // The whole trap-closure: a two-key object literal, built here. No spread,
+    // no caller-supplied opts — nothing a caller passes can become a sibling of
+    // `updatedInput`, and `permissionDecision` therefore cannot appear.
+    line = JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        updatedInput,
+      },
+    });
+  } catch (err) {
+    // A cycle or a BigInt in the caller's object. JSON.stringify can also return
+    // undefined (a toJSON that yields undefined) — caught by the same guard.
+    bail(`could not serialize the tool input (${err?.message ?? String(err)})`);
+  }
+
+  if (typeof line !== 'string') {
+    bail('serialized the tool input to undefined (a toJSON returning undefined?)');
+  }
+
+  const bytes = Buffer.byteLength(`${line}\n`, 'utf8');
+  if (bytes > REWRITE_ENVELOPE_MAX_BYTES) {
+    // Refused whole, never sliced — see REWRITE_ENVELOPE_MAX_BYTES for why a
+    // clipped structure is worse than no structure.
+    bail(`envelope is ${bytes} bytes, over the ${REWRITE_ENVELOPE_MAX_BYTES}-byte ceiling`);
+  }
+
+  // Return value deliberately ignored: a rewrite that cannot be delivered costs
+  // the improvement, never the tool call. See the asymmetry note above.
+  writeStdoutLineSync(line);
+  process.exit(0);
+}
+
 /**
  * Inject a system message into the hook response without exiting.
  * @param {string} msg  Message text wrapped in a systemMessage JSON envelope on stdout.

package/scripts/lib/issue-budget.mjs

@@ -37,6 +37,36 @@ import { _parseIssueBudget } from './config/issue-budget.mjs';
 /** Runtime counter file, relative to the repo root. */
 export const BUDGET_STATE_REL = '.orchestrator/runtime/issue-budget.json';
 
+/**
+ * Resolve the accounting key for a native session id.
+ *
+ * A semantic id is an accounting continuity bridge only after the native id
+ * proves that `current-session.json` belongs to this invocation. This neither
+ * establishes lock ownership nor bridges a host rotation that changes both ids.
+ *
+ * @param {string|null|undefined} candidateRawSessionId native hook/env session id
+ * @param {unknown} currentSession parsed `.orchestrator/current-session.json`
+ * @returns {string|null} semantic key for a verified pair, otherwise raw key
+ */
+export function resolveIssueBudgetSessionId(candidateRawSessionId, currentSession) {
+  const rawSessionId =
+    typeof candidateRawSessionId === 'string' && candidateRawSessionId.length > 0
+      ? candidateRawSessionId
+      : null;
+  if (
+    rawSessionId === null ||
+    !currentSession ||
+    typeof currentSession !== 'object' ||
+    Array.isArray(currentSession) ||
+    currentSession.session_id !== rawSessionId ||
+    typeof currentSession.semantic_session_id !== 'string' ||
+    currentSession.semantic_session_id.length === 0
+  ) {
+    return rawSessionId;
+  }
+  return currentSession.semantic_session_id;
+}
+
 /**
  * Commands whose issue creation MUST NOT be blocked, with the reason recorded
  * for the stderr trace and for the overflow bookkeeping.
@@ -109,20 +139,34 @@ export function budgetStatePath(repoRoot) {
  * a fresh zeroed state for `sessionId` — the counter is per session by
  * construction, so a new session never inherits the previous session's spend.
  *
+ * An identity-less invocation always gets a fresh state and never reads a
+ * persisted budget. It therefore cannot provide durable per-session continuity,
+ * but avoiding cross-session budget and overflow attribution wins over a
+ * continuity guess without a verified native identity.
+ *
+ * The counter file is SHARED across invocations, so this read-side isolation is
+ * only half the contract: an identity-less charge must also never PERSIST its
+ * fresh state, or it silently zeroes a live session's count and deletes its
+ * parked overflow records. `chargeIssueBudget` enforces that write-side half.
+ *
  * @param {string} repoRoot
  * @param {string|null} sessionId
  * @returns {{ sessionId: string|null, count: number, exempt: number, overflow: object[] }}
  */
 export function readBudgetState(repoRoot, sessionId) {
-  const fresh = { sessionId: sessionId ?? null, count: 0, exempt: 0, overflow: [] };
+  const accountingSessionId =
+    typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  const fresh = { sessionId: accountingSessionId, count: 0, exempt: 0, overflow: [] };
+  if (accountingSessionId === null) return fresh;
+
   const file = budgetStatePath(repoRoot);
   if (!existsSync(file)) return fresh;
   try {
     const data = JSON.parse(readFileSync(file, 'utf8'));
     if (!data || typeof data !== 'object') return fresh;
-    if (sessionId && data.sessionId && data.sessionId !== sessionId) return fresh;
+    if (data.sessionId !== accountingSessionId) return fresh;
     return {
-      sessionId: data.sessionId ?? sessionId ?? null,
+      sessionId: accountingSessionId,
       count: Number.isInteger(data.count) && data.count >= 0 ? data.count : 0,
       exempt: Number.isInteger(data.exempt) && data.exempt >= 0 ? data.exempt : 0,
       overflow: Array.isArray(data.overflow) ? data.overflow : [],
@@ -200,13 +244,23 @@ export function chargeIssueBudget({
     return { ...base, decision: 'off', count: 0, overflowCount: 0, reason: null };
   }
 
-  const state = readBudgetState(repoRoot, sessionId);
-  state.sessionId = sessionId ?? state.sessionId;
+  const accountingSessionId =
+    typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  const state = readBudgetState(repoRoot, accountingSessionId);
+  state.sessionId = accountingSessionId;
+
+  // An identity-less charge has no key to account under, so it must not touch
+  // the SHARED counter file at all. Writing its fresh state would reset a live
+  // session's count to 0 AND drop its parked overflow[] entries — breaking the
+  // strict cap (a single identity-less call clears it) and session-end's
+  // "nothing is lost" promise. Read-side isolation alone does not cover this.
+  const persist = (next) =>
+    accountingSessionId === null ? false : writeBudgetState(repoRoot, next);
 
   const { exempt, reason } = classifyExemption(command);
   if (exempt) {
     state.exempt += 1;
-    writeBudgetState(repoRoot, state);
+    persist(state);
     return {
       ...base,
       decision: 'exempt',
@@ -218,13 +272,13 @@ export function chargeIssueBudget({
 
   if (state.count < max) {
     state.count += 1;
-    writeBudgetState(repoRoot, state);
+    persist(state);
     return { ...base, decision: 'allow', count: state.count, overflowCount: state.overflow.length, reason: null };
   }
 
   if (mode === 'warn') {
     state.count += 1;
-    writeBudgetState(repoRoot, state);
+    persist(state);
     return { ...base, decision: 'warn', count: state.count, overflowCount: state.overflow.length, reason: null };
   }
 
@@ -234,7 +288,7 @@ export function chargeIssueBudget({
     command: String(command).slice(0, 500),
     at: now,
   });
-  writeBudgetState(repoRoot, state);
+  persist(state);
   return {
     ...base,
     decision: 'block',

package/scripts/lib/owner-interview.mjs

@@ -13,10 +13,16 @@
  *     to AskUserQuestion in the coordinator. Each object has the shape:
  *       { question, header, options: [{ label, description }], multiSelect }
  *
+ *   optionValue(label)
+ *     Maps a displayed option label to the value stored in owner.yaml by
+ *     stripping the trailing `(Recommended)` marker. The label and the stored
+ *     value are deliberately NOT the same string — see the function comment.
+ *
  *   applyInterviewAnswers(answers, { path? } = {})
  *     Accepts an array of selected option labels (one per question, same order
- *     as getInterviewQuestions()), validates the result against validateOwnerConfig,
- *     and writes owner.yaml via writeOwnerConfig.
+ *     as getInterviewQuestions()), resolves each through optionValue(), validates
+ *     the result against validateOwnerConfig, and writes owner.yaml via
+ *     writeOwnerConfig.
  *     Returns { ok, path, errors }.
  *
  *   runOwnerInterview({ skipIfExists?, force?, path? } = {})
@@ -37,6 +43,40 @@ import {
   getDefaults,
 } from './owner-yaml.mjs';
 
+// ---------------------------------------------------------------------------
+// Label ←→ stored value
+// ---------------------------------------------------------------------------
+
+/**
+ * A trailing recommendation marker on an option LABEL — the display half of a
+ * label, never part of the stored value.
+ *
+ * Anchored at the end and non-greedy about whitespace so it can only ever strip
+ * a suffix; a value that merely CONTAINS the word (there is none today) survives.
+ */
+const RECOMMENDED_SUFFIX = /\s*\((?:Recommended|Empfohlen|Default)\)\s*$/u;
+
+/**
+ * Map an AUQ option label back to the value that is written to owner.yaml.
+ *
+ * The label and the stored value used to be the SAME string, which made the
+ * label unchangeable: `applyInterviewAnswers()` matches the answer against
+ * closed enums (`['direct','neutral','friendly']` and friends) and falls back to
+ * a default on any miss. Adding the `(Recommended)` marker AUQ-003 requires
+ * would therefore have turned a picked `direct` into a silently-stored
+ * `neutral` — a wrong answer written to disk with no error anywhere.
+ *
+ * Splitting the two keeps the label free for the operator and the value pinned
+ * to the enum. Everything before the marker is the value, verbatim.
+ *
+ * @param {unknown} label — the option label as selected by the operator
+ * @returns {string} the enum value to store, or '' for a non-string input
+ */
+export function optionValue(label) {
+  if (typeof label !== 'string') return '';
+  return label.replace(RECOMMENDED_SUFFIX, '').trim();
+}
+
 // ---------------------------------------------------------------------------
 // Question definitions
 // ---------------------------------------------------------------------------
@@ -50,51 +90,51 @@ import {
 export function getInterviewQuestions() {
   return [
     {
-      question: 'Which language should the assistant use for its responses?',
-      header: 'Owner Interview — Language (1/5)',
+      question: 'Which language should the assistant answer in?',
+      header: 'Language 1/5',
       options: [
-        { label: 'de', description: 'German — responses, narration, and questions in Deutsch.' },
-        { label: 'en', description: 'English — responses, narration, and questions in English.' },
-        { label: 'other', description: 'Other — write your ISO-639-1 code when prompted.' },
+        { label: 'de', description: 'German — answers, narration and questions all in Deutsch.' },
+        { label: 'en', description: 'English — answers, narration and questions all in English.' },
+        { label: 'other', description: 'Stored as English either way — only de and en are accepted. Change it later in owner.yaml (your settings file).' },
       ],
       multiSelect: false,
     },
     {
-      question: 'What communication tone style do you prefer?',
-      header: 'Owner Interview — Tone Style (2/5)',
+      question: 'How should the assistant talk to you?',
+      header: 'Tone 2/5',
       options: [
-        { label: 'direct', description: '(Recommended for pros) No filler phrases, straight to the point.' },
-        { label: 'neutral', description: 'Balanced: professional without being terse.' },
-        { label: 'friendly', description: 'Warm and conversational — good for exploratory sessions.' },
+        { label: 'direct (Recommended)', description: 'No filler, no praise, straight to the point — fastest to read once you know the project.' },
+        { label: 'neutral', description: 'Professional without being terse. Pick this if direct reads too blunt.' },
+        { label: 'friendly', description: 'Warm and conversational. Costs a few lines per answer, and suits open-ended exploration.' },
       ],
       multiSelect: false,
     },
     {
-      question: 'How much output should the assistant produce by default?',
-      header: 'Owner Interview — Output Level (3/5)',
+      question: 'How much should the assistant write by default?',
+      header: 'Output 3/5',
       options: [
-        { label: 'lite', description: 'Verbose mode — articles, explanations, and context kept. Good for learning.' },
-        { label: 'full', description: '(Default) Terse but complete. Narration trimmed, data preserved.' },
-        { label: 'ultra', description: 'Telegraphic — code and decisions only, no narration.' },
+        { label: 'full (Recommended)', description: 'Terse but complete: narration trimmed, every fact kept. Safe default — you lose words, never data.' },
+        { label: 'lite', description: 'Keeps the explanations and background too. Slower to read, better while the codebase is still new to you.' },
+        { label: 'ultra', description: 'Code and decisions only, no narration. You will have to ask why more often.' },
       ],
       multiSelect: false,
     },
     {
-      question: 'How should the assistant handle preamble before taking actions?',
-      header: 'Owner Interview — Preamble (4/5)',
+      question: 'How much should the assistant explain before it starts working?',
+      header: 'Preamble 4/5',
       options: [
-        { label: 'minimal', description: 'One-line status updates only. Jump straight to execution.' },
-        { label: 'verbose', description: 'Explain plan + rationale before each major action.' },
+        { label: 'minimal (Recommended)', description: 'One line of status, then it works. Safe default — you can still ask for the reasoning afterwards.' },
+        { label: 'verbose', description: 'Plan and reasoning before each major action. Costs a few lines every step.' },
       ],
       multiSelect: false,
     },
     {
-      question: 'Hardware-sharing consent: may the plugin share anonymized hardware patterns to improve resource defaults? (Issue #173 C4)',
-      header: 'Owner Interview — Hardware Sharing Consent (5/5)',
+      question: 'May the plugin share anonymized hardware data to improve its resource defaults?',
+      header: 'Sharing 5/5',
       options: [
-        { label: 'No', description: '(Default) No data is shared. Fully private.' },
-        { label: 'Yes', description: 'Share anonymized patterns (hashed, no PII). Helps tune wave/session defaults.' },
-        { label: 'Preview', description: 'Show exactly what would be shared before deciding.' },
+        { label: 'No (Recommended)', description: 'Nothing leaves this machine. Safe default — you can switch it on later without redoing this interview.' },
+        { label: 'Yes', description: 'Shares hashed hardware patterns — never file names, paths or content. Helps tune the wave and session defaults.' },
+        { label: 'Preview', description: 'Shows exactly what would be sent, then asks again. Costs one extra step.' },
       ],
       multiSelect: false,
     },
@@ -108,12 +148,15 @@ export function getInterviewQuestions() {
 /**
  * Map interview answer labels to an owner.yaml config object and write it.
  *
+ * Each answer is the LABEL the operator picked, which may carry a trailing
+ * `(Recommended)` marker; optionValue() strips it before the enum match below.
+ *
  * @param {string[]} answers - Array of selected option labels, one per question (5 total).
- *   answers[0] = language label ('de' | 'en' | free-text)
- *   answers[1] = tone style label
- *   answers[2] = output level label
- *   answers[3] = preamble label
- *   answers[4] = hardware-sharing label ('Yes' | 'No' | 'Preview')
+ *   answers[0] = language label ('de' | 'en' | 'other')
+ *   answers[1] = tone style label ('direct' | 'neutral' | 'friendly', ± marker)
+ *   answers[2] = output level label ('full' | 'lite' | 'ultra', ± marker)
+ *   answers[3] = preamble label ('minimal' | 'verbose', ± marker)
+ *   answers[4] = hardware-sharing label ('Yes' | 'No' | 'Preview', ± marker)
  * @param {{ path?: string }} [opts]
  * @returns {{ ok: boolean, path: string, errors: string[] }}
  */
@@ -124,7 +167,10 @@ export function applyInterviewAnswers(answers, opts = {}) {
     return { ok: false, path: filePath, errors: ['applyInterviewAnswers requires exactly 5 answers'] };
   }
 
-  const [langRaw, toneRaw, outputLevelRaw, preambleRaw, hwConsentRaw] = answers;
+  // Strip the display-only `(Recommended)` marker before matching against the
+  // enums below — see optionValue(). A non-string answer becomes '' and falls
+  // through to the same default it always did.
+  const [langRaw, toneRaw, outputLevelRaw, preambleRaw, hwConsentRaw] = answers.map(optionValue);
 
   // --- Language ---
   // Accept 'de', 'en', or treat anything else as a free-text language code.