@event4u/agent-config 14.20.0 → 14.21.0

package/src/scripts/_lib/release_highlights.ts

@@ -25,15 +25,7 @@
  */
 import { spawnSync } from 'node:child_process';
 
-import {
-    CURATED_HEAD_INSTRUCTION,
-    MIX_RESPONSE_MARKER,
-    MIX_RESPONSE_PLACEHOLDERS,
-    PROMISE_OUTCOMES,
-    PROMISE_PHRASE,
-    PROMISE_READBACK_MARKER,
-    extract_changelog_section,
-} from './release_material.js';
+import { CURATED_HEAD_INSTRUCTION } from './release_material.js';
 
 /** The five curated labels, in the order an operator reads them. */
 export const HEAD_LABELS: readonly string[] = [
@@ -406,7 +398,6 @@ export function publication_blockers(
     sectionBody: string,
     version: string,
     where = '`main`',
-    mix: MixObligation | null = null,
 ): string[] {
     const out: string[] = [];
     if (sectionBody.includes(DERIVED_MARKER)) {
@@ -423,13 +414,15 @@ export function publication_blockers(
                 'comment line from the section and re-run.',
         );
     }
-    out.push(...mix_response_blockers(sectionBody, version, where, mix));
     return out;
 }
 
 /**
  * Everything that makes a whole SECTION unpublishable — the head-level
- * blockers above plus the two obligations that only exist for a full section.
+ * blockers above plus the tests footer, which only exists for a full section.
+ *
+ * It was "the two obligations" until 2026-09-07: the governance-versus-product
+ * written answer was the other, and ADR-261 deleted it. One remains.
  *
  * Two levels and not one, because `publication_blockers` is legitimately called
  * with a bare curated head (the prefill tests do exactly that), and a head
@@ -450,9 +443,8 @@ export function section_publication_blockers(
     sectionBody: string,
     version: string,
     where = '`main`',
-    mix: MixObligation | null = null,
 ): string[] {
-    const out = publication_blockers(sectionBody, version, where, mix);
+    const out = publication_blockers(sectionBody, version, where);
     if (!TEST_FOOTER_RE.test(sectionBody)) {
         out.push(
             `the ${version} section carries no \`Tests: N (+M since PREV)\` footer. ` +
@@ -479,208 +471,24 @@ export function section_publication_blockers(
 const TEST_FOOTER_RE = /^Tests: \d+/mu;
 
 /**
- * The measured governance-versus-product level, as the writer and the guards
- * both receive it.
- *
- * A plain record and not the measurement itself: this module is reached by the
- * push guard, the pre-commit ask and the CI gate, and only the callers have git
- * to measure with. Passing the reading in keeps the predicate pure and keeps
- * `measure_release_mix`'s git access out of a module three guards import.
+ * The measured governance-versus-product level, as the writer receives it.
+ *
+ * A plain record and not the measurement itself: only the callers have git to
+ * measure with, and keeping `measure_release_mix`'s git access out of this
+ * module keeps it importable by the guards.
+ *
+ * It carried a `triggered` boolean until ADR-261, when the obligation that
+ * boolean gated was deleted. It was removed rather than kept with a rationale:
+ * the first attempt at this docblock claimed a reader of the published line
+ * could see the verdict, and a neutral review falsified that — `triggered` was
+ * set once and read nowhere, and `render_mix_response` never received it. The
+ * two counts in `level` are what the line publishes, and the taxonomy's own
+ * verdict stays where it is computed and printed, in `measure_release_mix`.
  */
 export interface MixObligation {
-    triggered: boolean;
     level: string;
 }
 
-/** Minimum written characters after the marker — a bare marker is not an answer. */
-export const MIX_RESPONSE_MIN_CHARS = 40;
-
-/**
- * The ONE predicate for the governance-versus-product obligation.
- *
- * `check_release_highlights` refuses this from the CI side and
- * `guard_release_branch_push` from the local side, and until 2026-09-05 only
- * the first of the two knew the obligation existed. That asymmetry is what the
- * contract itself recorded — *"the earliest refusal for this one obligation is
- * the PR, not the push"* (`docs/contracts/CHANGELOG-conventions.md`) — and what
- * cost 14.17.0 a red release PR. Both sides now read this function, so a change
- * to the obligation cannot reach one guard and miss the other.
- *
- * `null` means the measurement did not run (shallow clone, missing tag). That
- * degrades to no blocker, matching the gate's documented stance: this is a
- * governance signal, not a correctness control, and an environment fact must
- * not block a release.
- */
-export function mix_response_blockers(
-    sectionBody: string,
-    version: string,
-    where = '`main`',
-    mix: MixObligation | null = null,
-): string[] {
-    if (!mix || !mix.triggered) {
-        return [];
-    }
-    const idx = sectionBody.indexOf(MIX_RESPONSE_MARKER);
-    if (idx === -1) {
-        return [
-            `the ${version} section owes a governance-versus-product response ` +
-                `(${mix.level}) and carries none. Add one \`> ${MIX_RESPONSE_MARKER}\` line ` +
-                `immediately under the curated head on ${where}, naming the next cycle's ` +
-                'consumer work or a maintainer justification.',
-        ];
-    }
-    const block = mix_response_block(sectionBody, idx);
-    const left = MIX_RESPONSE_PLACEHOLDERS.filter((t) => block.includes(t));
-    if (left.length > 0) {
-        return [
-            `the ${version} governance-versus-product response still carries the writer's ` +
-                `placeholder(s) (${left.map((t) => `\`${t}\``).join(', ')}) — the measured level ` +
-                'is the generator\'s, the answer is not, and `CHANGELOG.md` is published to npm. ' +
-                `Name the next cycle's consumer work (or the justification) on ${where} and re-run.`,
-        ];
-    }
-    if (human_answer(block, mix.level).length < MIX_RESPONSE_MIN_CHARS) {
-        return [
-            `the ${version} governance-versus-product response carries no written answer ` +
-                `beyond the measured level (${mix.level}). The level is the generator's; the ` +
-                `response has to name the next cycle's consumer work or a maintainer ` +
-                `justification. Write it on ${where}, in the \`> \` block under the marker.`,
-        ];
-    }
-    return [];
-}
-
-/**
- * The promise the PREVIOUS release head made, or null when it made none.
- *
- * Scoped to that section's governance-response block, not to its whole body: a
- * product line that happens to contain the phrase is not a promise the project
- * made about the next cycle.
- */
-export function previous_promise(changelogText: string, previousVersion: string): string | null {
-    const section = extract_changelog_section(changelogText, previousVersion);
-    if (section === null) return null;
-    const idx = section.body.indexOf(MIX_RESPONSE_MARKER);
-    if (idx === -1) return null;
-    const block = mix_response_block(section.body, idx);
-    return block.includes(PROMISE_PHRASE) ? block : null;
-}
-
-/**
- * The ONE predicate for "did this head answer the previous head's promise?".
- *
- * The defect: `_lib/release_material.ts` generates a `Next cycle ships …` line
- * and nothing has ever read the previous one back, so an unmet promise can be
- * restated indefinitely at zero cost — the debt is booked and never called. A
- * promise nobody reads is not a commitment, it is a sentence.
- *
- * Three outcomes are accepted and one of them must be chosen, which is the
- * whole mechanism: it does not require the promise to have been KEPT, and no
- * ratio, deadline or count is enforced here. Refusing an unkept promise would
- * make the honest answer the expensive one and teach an author to promise less
- * rather than to answer truthfully.
- *
- * Length floor and placeholder scan reuse the governance-response discipline
- * for the same reason it exists there: a bare marker, or the writer's own
- * scaffolding, is not an answer a human wrote.
- */
-export function promise_readback_blockers(
-    sectionBody: string,
-    version: string,
-    previousVersion: string,
-    promise: string | null,
-    where = '`main`',
-): string[] {
-    if (promise === null) return [];
-    const idx = sectionBody.indexOf(PROMISE_READBACK_MARKER);
-    if (idx === -1) {
-        return [
-            `the ${version} section does not answer the ${previousVersion} head's ` +
-                `\`${PROMISE_PHRASE}\` promise. Add one \`> ${PROMISE_READBACK_MARKER}\` line ` +
-                `immediately under the curated head on ${where}, naming the promise and whether ` +
-                `it ${PROMISE_OUTCOMES.join(', ')} (the last one with its reason).`,
-        ];
-    }
-    const block = mix_response_block(sectionBody, idx);
-    const left = MIX_RESPONSE_PLACEHOLDERS.filter((t) => block.includes(t));
-    if (left.length > 0) {
-        return [
-            `the ${version} previous-cycle answer still carries the writer's placeholder(s) ` +
-                `(${left.map((t) => `\`${t}\``).join(', ')}). \`CHANGELOG.md\` is published to npm. ` +
-                `Write the outcome on ${where} and re-run.`,
-        ];
-    }
-    const lower = block.toLowerCase();
-    const named = PROMISE_OUTCOMES.filter((o) => lower.includes(o));
-    if (named.length === 0) {
-        return [
-            `the ${version} previous-cycle answer names no outcome. It has to say which of ` +
-                `${PROMISE_OUTCOMES.join(', ')} applies to the ${previousVersion} promise — an ` +
-                'answer that restates the promise without resolving it is the failure this reads ' +
-                'back for.',
-        ];
-    }
-    if (readback_answer(block).length < MIX_RESPONSE_MIN_CHARS) {
-        return [
-            `the ${version} previous-cycle answer is shorter than a written answer ` +
-                `(${String(MIX_RESPONSE_MIN_CHARS)} characters after the marker). Name what was ` +
-                `promised and what became of it on ${where}, not the outcome word alone.`,
-        ];
-    }
-    return [];
-}
-
-/** What the author wrote under the read-back marker, marker and quoting removed. */
-export function readback_answer(block: string): string {
-    return block
-        .replace(PROMISE_READBACK_MARKER, '')
-        .replace(/^[>\s.]+|[>\s.]+$/gu, '')
-        .replace(/[>\s]+/gu, ' ')
-        .trim();
-}
-
-/**
- * The whole response block: the marker's line plus every blockquote line under it.
- *
- * Reading only the FIRST line after the marker was wrong in both directions, and
- * both were reproduced before this was written. It **accepted** a section whose
- * placeholder line had simply been deleted, because the machine-written level
- * alone is 54 characters and cleared the floor — the smuggled auto-approval the
- * placeholder exists to prevent. And it **refused** the writer's own two-line
- * template, where the level sits on line 1 and the answer on line 2.
- *
- * Scoping to the block also fixes the placeholder scan, which searched the
- * entire section body: a legitimate changelog line containing
- * `<roadmap or issue>` blocked the release.
- */
-export function mix_response_block(sectionBody: string, markerIdx: number): string {
-    const lines = sectionBody.slice(markerIdx).split('\n');
-    const out: string[] = [lines[0] ?? ''];
-    for (const line of lines.slice(1)) {
-        if (!line.trimStart().startsWith('>')) break;
-        out.push(line);
-    }
-    return out.join('\n');
-}
-
-/**
- * What is left of the response block once the generator's own contribution is
- * removed — i.e. the part a human had to write.
- *
- * The measured level is stripped because the writer emitted it; a floor that
- * counted it would be satisfied by the tool on the author's behalf, which is
- * the whole failure this obligation guards against.
- */
-export function human_answer(block: string, level: string): string {
-    return block
-        .replace(MIX_RESPONSE_MARKER, '')
-        .split(level)
-        .join('')
-        .replace(/^[>\s.]+|[>\s.]+$/gu, '')
-        .replace(/[>\s]+/gu, ' ')
-        .trim();
-}
-
 /** Labels whose curated value is still the generator's unedited draft. */
 export function stale_draft_labels(
     curated: Readonly<Record<string, string>>,

package/src/scripts/_lib/release_material.ts

@@ -300,95 +300,45 @@ function _first_diff(a: string, b: string): string {
  * a branch, a PR and a CI run — the exact cost `guard_release_branch_push` was
  * added to avoid for the sibling obligation two releases earlier.
  *
- * This module has no imports on purpose (see `CURATED_HEAD_INSTRUCTION`), which
- * is what lets the writer, the local push guard and the CI gate all reach one
- * definition instead of three copies.
+ * This module has no imports on purpose (see `CURATED_HEAD_INSTRUCTION`).
+ *
+ * **One reader left, as of ADR-261 (2026-09-07).** This paragraph used to say
+ * the definition was shared by "the writer, the local push guard and the CI
+ * gate", which was true while `mix_response_blockers` and
+ * `check_governance_mix_response` scanned a section for this marker. Both are
+ * deleted, and with them every search for it: the only consumer now is
+ * `render_mix_response` in this same file, which WRITES the line. Nothing reads
+ * a changelog looking for it, so do not assume a guard notices when it is
+ * missing — none does.
  */
 export const MIX_RESPONSE_MARKER = '**Governance mix:**';
 
 /**
- * The sentinel that marks an EMITTED-BUT-UNANSWERED response.
- *
- * A generator that emits the measured level alone would satisfy the gate's
- * length floor (`MIX_RESPONSE_MIN_CHARS`, 40) with a number the machine
- * produced, turning a written-answer obligation into a formality the tool
- * discharges for itself. That is a smuggled auto-approval, not a fix.
+ * Render the measured governance-versus-product line the writer emits.
  *
- * So the writer emits the level AND this sentinel, and every gate refuses the
- * sentinel — the same discipline `CURATED_HEAD_INSTRUCTION` and
- * `DERIVED_MARKER` already follow. The net effect is only that the obligation
- * moves from CI to the moment the section is written, where the fix is an edit
- * to a file already open in the working tree.
- */
-export const MIX_RESPONSE_PLACEHOLDER = '<the consumer work>';
-
-/**
- * Every placeholder token the writer emits, so none of them can ship.
+ * ONE line, and machine-written end to end. It reports what the span measured
+ * and asks the releaser for nothing.
  *
- * The block carries two, and refusing only the first would leave
- * `<roadmap or issue>` publishable — `CHANGELOG.md` is in `package.json`
- * `files`, so that is the same "the generator's own scaffolding reached npm"
- * failure `CURATED_HEAD_INSTRUCTION` exists for, one token to the right.
+ * The written-answer obligation is gone (ADR-261). This used to emit a second line — `Next cycle ships <the consumer work>,
+ * tracked in <roadmap or issue>.` — a placeholder no generator was allowed to
+ * fill, backed by four refusals, an interactive prompt, a staging channel under
+ * `## [Unreleased]` and a read-back obligation on the following release. The
+ * releaser had to type prose into a running pipeline to get a version out.
  *
- * A named list rather than a shape match over angle brackets, for the reason
- * that constant already states: a pattern such as `/<[a-z ]+>/` rejects
- * unrelated legitimate prose and misses a reworded placeholder. Adding a token
- * to `render_mix_response` means adding it here.
- */
-export const MIX_RESPONSE_PLACEHOLDERS: readonly string[] = [
-    MIX_RESPONSE_PLACEHOLDER,
-    '<roadmap or issue>',
-];
-
-/**
- * Render the response block the writer emits when the obligation triggers.
+ * The owner ended it: this package exists to make the maintainer's work
+ * cheaper, and a release gate that stops a green pipeline until a human writes
+ * a sentence about a FUTURE cycle is the opposite. The measurement stays
+ * because it is free and true; the homework does not.
  *
- * Two blockquote lines, immediately under the curated head and outside it, per
- * `docs/contracts/CHANGELOG-conventions.md` § Governance-versus-product
- * response — the head's ten-line cap is for product lines, and a sixth label
- * would make every historical section retroactively incomplete.
+ * The removed placeholder constants (`MIX_RESPONSE_PLACEHOLDER(S)`) and promise
+ * sentinels (`PROMISE_PHRASE`, `PROMISE_READBACK_MARKER`, `PROMISE_OUTCOMES`)
+ * are deleted rather than deprecated — a sentinel nothing writes and nothing
+ * refuses is dead weight that reads as live policy.
  */
 export function render_mix_response(level: string): string[] {
-    return [
-        `> ${MIX_RESPONSE_MARKER} ${level}.`,
-        `> ${PROMISE_PHRASE} ${MIX_RESPONSE_PLACEHOLDER}, tracked in <roadmap or issue>.`,
-    ];
+    return [`> ${MIX_RESPONSE_MARKER} ${level}.`];
 }
 
-/**
- * The words that turn a governance response into a PROMISE about a later cycle.
- *
- * Named rather than inlined because two sides now read it: the writer emits it,
- * and the next release reads the previous section for it to decide whether a
- * read-back is owed. A promise nothing reads back costs nothing to restate, so
- * it can be restated for as many cycles as there are cycles — the defect this
- * constant exists to make addressable.
- */
-export const PROMISE_PHRASE = 'Next cycle ships';
-
-/**
- * The marker under which a release head answers the PREVIOUS head's promise.
- *
- * A named sentinel, on the same discipline as `MIX_RESPONSE_MARKER` and
- * `DERIVED_MARKER`: a shape match over prose would accept a sentence that
- * happens to mention last cycle and reject a reworded answer.
- */
-export const PROMISE_READBACK_MARKER = '**Previous cycle:**';
-
-/**
- * The three outcomes a read-back may report, and the reason there are exactly
- * three.
- *
- * `shipped` and `did not ship` are the honest halves of the fact. `withdrawn`
- * exists because a promise the project decided not to keep is a legitimate
- * third state — but only WITH a reason, which is why the answer also has to
- * clear a written-length floor rather than being one of these three words on
- * its own. Without the third state the mechanism would push an author toward
- * restating a dead promise as still-outstanding, which is the failure it is
- * built to stop.
- */
-export const PROMISE_OUTCOMES: readonly string[] = ['shipped', 'did not ship', 'withdrawn'];
-
 /** Every `## X.Y.Z` release version in the file, in document order (newest first). */
 export function changelog_versions(text: string): string[] {
     const out: string[] = [];

package/src/scripts/_lib/structured_ask.ts

@@ -0,0 +1,117 @@
+/**
+ * The structured-ask surface — one shared definition of "a host's own question
+ * tool", read by every consumer that needs it.
+ *
+ * Three consumers exist and they must not each invent their own answer:
+ *
+ *   - `probe_unblocked_ask.ts` partitions hand-back ask turns into `text` and
+ *     `native`, where `native` means the turn carried a call to such a tool.
+ *   - `hooks/one_question_per_ask_hook.ts` denies a call carrying more than one
+ *     question.
+ *   - `_lib/host_capability.ts` carries the boolean `structured_ask` capability;
+ *     the per-host SHAPE lives here rather than in the manifest, because every
+ *     manifest field is a strict boolean that `asBool` coerces — a nested object
+ *     put there would normalize silently to `false`.
+ *
+ * What is observed, and what is a shape guess — the line is drawn explicitly.
+ *
+ * `STRUCTURED_ASK_SHAPES` is **empty**. No host in this repository's registry
+ * carries an observed structured-ask tool, so there is no per-host tool name to
+ * match on, and inventing one from a vendor's documentation is exactly what
+ * `host-capability-manifest.md` § Observation protocol forbids.
+ *
+ * `STRUCTURED_ASK_TOOL_NAME_RE` is therefore a **name-shape pattern, not a host
+ * fact**. It exists so that if such a tool ever appears in a transcript, the
+ * probe MEASURES it rather than missing it — and so the number it reports today
+ * (zero) is a measurement rather than an absence of instrumentation. A reader
+ * must not read a match as evidence that a named host ships that tool; the only
+ * thing that establishes that is an observation written into
+ * `STRUCTURED_ASK_SHAPES` with the protocol's four-part citation.
+ *
+ * Consequence, stated rather than discovered later: `native` is expected to be
+ * **0** on every corpus this repo can scan today. That is the honest reading of
+ * a capability nobody has observed, not a broken detector.
+ */
+
+/** The per-host shape of a structured-ask tool, once one has been OBSERVED. */
+export interface StructuredAskShape {
+    /** The tool name as it appears in a transcript's `tool_use` block. */
+    readonly tool: string;
+    /** How many questions one call may carry. `1` is the shape this repo wants. */
+    readonly max_questions: number;
+    /** How many options one question may offer. */
+    readonly max_options_per_question: number;
+    /** Whether the host's picker admits a free-text answer alongside the options. */
+    readonly free_text: boolean;
+}
+
+/**
+ * Observed per-host structured-ask shapes.
+ *
+ * EMPTY, deliberately. A row is written only from an observation in a real
+ * session under `contexts/execution/host-capability-manifest.md` § Observation
+ * protocol — host · host version · transcript reference · date. Never from a
+ * host's documentation, and never by analogy to another host.
+ */
+export const STRUCTURED_ASK_SHAPES: Readonly<Record<string, StructuredAskShape>> = {};
+
+/** The observed shape for `hostId`, or `undefined` when none has been observed. */
+export function structuredAskShape(
+    hostId: string | null | undefined,
+): StructuredAskShape | undefined {
+    if (hostId === null || hostId === undefined) {
+        return undefined;
+    }
+    return STRUCTURED_ASK_SHAPES[hostId];
+}
+
+/**
+ * Name-SHAPE pattern for a structured-ask tool. See the module header: this is
+ * a matcher, not a claim about any host.
+ */
+export const STRUCTURED_ASK_TOOL_NAME_RE = /^(ask[_-]?user[_-]?question|user[_-]?question|ask[_-]?question)s?$/i;
+
+/**
+ * Is `name` a structured-ask tool call?
+ *
+ * An observed per-host shape wins outright — that is a fact about the host. The
+ * name-shape pattern is the fallback, and it is why the probe can report a
+ * measured zero instead of nothing at all.
+ */
+export function isStructuredAskTool(name: string, hostId?: string | null): boolean {
+    const shape = structuredAskShape(hostId);
+    if (shape !== undefined) {
+        return name === shape.tool;
+    }
+    return STRUCTURED_ASK_TOOL_NAME_RE.test(name);
+}
+
+/**
+ * How many questions a structured-ask tool payload carries.
+ *
+ * Returns `-1` when the payload's shape is not recognised at all — a caller
+ * that gates on this must treat `-1` as "cannot tell", never as "one". The two
+ * recognised shapes are the only ones a picker can plausibly use: an array of
+ * question objects under a `questions`-like key, or a single question field.
+ *
+ * A `questions` array of length 0 is 0, not 1: an empty ask is malformed and a
+ * gate should be able to say so.
+ */
+export function countStructuredAskQuestions(input: unknown): number {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        return -1;
+    }
+    const src = input as Record<string, unknown>;
+    for (const key of ['questions', 'question_list', 'items', 'prompts']) {
+        const v = src[key];
+        if (Array.isArray(v)) {
+            return v.length;
+        }
+    }
+    for (const key of ['question', 'prompt', 'header']) {
+        if (typeof src[key] === 'string' && (src[key] as string).trim() !== '') {
+            return 1;
+        }
+    }
+    return -1;
+}

package/src/scripts/_lib/tty_prompt.ts

@@ -0,0 +1,76 @@
+/**
+ * Synchronous terminal prompting for the release pipeline.
+ *
+ * Its own module because `release.ts` sits 371 lines over the 1500-line source
+ * ratchet, where every added line is one unit of excess — and because a SECOND
+ * caller now needs these: `guard_release_curation` in `release_publication.ts`
+ * collects the governance answer it used to only refuse over.
+ *
+ * Extracted verbatim from `release.ts`, where the `/dev/tty` discipline below
+ * was established against a reproduced failure. Do not "simplify" it back to
+ * `readSync(0)`; the comment on `promptLine` says what that costs.
+ */
+import * as fs from 'node:fs';
+import process from 'node:process';
+
+/** Can we prompt at all — is fd 0 a TTY, or is a controlling terminal openable? */
+export function canPrompt(): boolean {
+    if (process.env.CI) return false; // CI is non-interactive by contract → require --yes
+    if (process.stdin.isTTY) return true;
+    try {
+        const fd = fs.openSync('/dev/tty', 'r');
+        fs.closeSync(fd);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Mirror of Python `input(prompt)` — write the prompt, read one line from the
+ * controlling terminal. Returns `null` when no terminal is reachable.
+ *
+ * The answer is ALWAYS read from a freshly opened, blocking `/dev/tty`
+ * (`openSync(..., 'rs')`), NEVER from fd 0. `task release` / `./scripts-run`
+ * run this under go-task's `interactive: true`, which leaves fd 0 a TTY
+ * (`process.stdin.isTTY === true`) but one Node treats as NON-blocking — so a
+ * bare `readSync(0)` throws `EAGAIN`, the catch swallows it, and the `[y/N]`
+ * prompt "auto-aborts" without ever waiting (the exact failure this fixes;
+ * reproduced with `isTTY === true`). A fresh blocking `/dev/tty` descriptor
+ * blocks for real input regardless of how the script was invoked — the proven
+ * synchronous-prompt pattern.
+ */
+export function promptLine(prompt: string): string | null {
+    process.stdout.write(prompt);
+    let fd: number;
+    try {
+        // 'rs' → O_RDONLY | O_SYNC: a fresh, blocking descriptor on the
+        // controlling terminal, unaffected by Node's non-blocking fd 0.
+        fd = fs.openSync('/dev/tty', 'rs');
+    } catch {
+        return null; // no controlling terminal (true non-interactive)
+    }
+    try {
+        const buf = Buffer.alloc(1);
+        const chars: number[] = [];
+        for (;;) {
+            let bytesRead: number;
+            try {
+                bytesRead = fs.readSync(fd, buf, 0, 1, null);
+            } catch (e) {
+                const code = (e as NodeJS.ErrnoException).code;
+                // A blocking /dev/tty should not yield these, but inherited
+                // descriptor flags can — retry rather than abort the prompt.
+                if (code === 'EAGAIN' || code === 'EINTR') continue;
+                break; // EOF / EIO → EOFError analogue; return what we have.
+            }
+            if (bytesRead === 0) break;
+            const b = buf[0] as number;
+            if (b === 0x0a) break; // newline terminates the line (stripped, like input()).
+            chars.push(b);
+        }
+        return Buffer.from(chars).toString('utf-8');
+    } finally {
+        fs.closeSync(fd);
+    }
+}