@event4u/agent-config 14.22.0 → 14.23.0

package/src/scripts/_lib/continuity_slot.ts

@@ -0,0 +1,295 @@
+/**
+ * The continuity-record slot — capacity policy and state machine.
+ *
+ * `road-to-continuity-writer-activation` step 1.1. Until this module existed
+ * the slot had a producer (`session:recycle`), a consumer
+ * (`handoff_context_hook`) and no documented conflict ownership: the write was
+ * an unguarded `atomic_write_json`, so a second publish replaced whatever sat
+ * there and nobody had decided whether that was correct. With a MANUAL producer
+ * the question was theoretical — a human ran the verb once. Automatic
+ * production makes it routine, which is why the policy is settled here BEFORE
+ * any automatic writer exists.
+ *
+ * The full contract, including why the two rejected alternatives are rejected
+ * on tree evidence rather than on preference, is
+ * `docs/contracts/continuity-record-slot.md`. This module is that document in
+ * code; neither is the source of truth for the other's reasoning, and both are
+ * checked by `tests/scripts/_lib_continuity_slot.test.ts`.
+ *
+ * The policy in one line:
+ *
+ *   SUPERSEDE OWN · REFUSE FOREIGN · QUARANTINE UNUSABLE · NEVER GO BACKWARDS.
+ *
+ * Why not create-if-absent.
+ *
+ * Create-if-absent is the policy the roadmap's own Risk 2 describes as a silent
+ * data loss: "the successor resumes from something plausible and older". It is
+ * rejected. Within one session the resident and the incoming record share a
+ * key, a workspace and a predecessor — the incoming one is the same lineage at
+ * a later moment, so keeping the older is a pure loss with no compensating
+ * safety.
+ *
+ * Why not a bounded multi-record queue.
+ *
+ * Because the reader forbids the resolution such a queue would need. Picking
+ * one of several records requires recency, and `recycle_envelope_paths.ts`
+ * carries a recorded decision against exactly that ("No `latest` index, by
+ * decision" — a pointer to the newest "would restore the shared write target
+ * one layer up"). `resolveContinuityRecord` implements it: several candidates
+ * and no session id START CLEAN rather than pick. A queue would either
+ * contradict that lock or be unreadable.
+ *
+ * Where `consuming` lives.
+ *
+ * Nowhere on disk, and that is the answer rather than a gap. Consumption is a
+ * single `fs.renameSync` from the authoritative name to the consumed name
+ * (`handoff_context_hook.ts:199`), and publication is a single `fs.renameSync`
+ * from a pid-suffixed temp name to the authoritative name
+ * (`state_io.ts:_publish_text_locked`). A rename within one directory is
+ * atomic on every filesystem this package supports, so an interruption lands
+ * strictly before or strictly after it: the authoritative name holds either the
+ * previous complete record or the new complete record, never a partial one.
+ * `consuming` is therefore a transition, not a state, and no reader has to
+ * tolerate a half-written record.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    recycle_consumed_rel,
+    recycle_envelope_rel,
+    recycle_quarantine_rel,
+    RECYCLE_ENVELOPE_MAX_BYTES,
+    RECYCLE_MAX_AGE_HOURS,
+} from './recycle_envelope_paths.js';
+import { validateRecycleEnvelope } from './subagent_capsule.js';
+import { update_json_under_lock } from '../hooks/state_io.js';
+
+/**
+ * The slot's states.
+ *
+ * Five are observable on disk. `consuming` is declared because the roadmap step
+ * names it and a reader looking for it deserves to find the reason it is not a
+ * disk state rather than to conclude it was forgotten — see the module header.
+ */
+export const SLOT_STATES = [
+    'absent',
+    'published',
+    'consuming',
+    'consumed',
+    'quarantined',
+    'conflicting',
+] as const;
+export type SlotState = (typeof SLOT_STATES)[number];
+
+/** What a publish attempt did, and why. The reason is always present. */
+export interface PublishOutcome {
+    /** `published` on a write; otherwise the state that refused it. */
+    state: SlotState;
+    /** Did the authoritative record change as a result of this call? */
+    wrote: boolean;
+    /** One line, always present — emitted by callers, never dropped. */
+    reason: string;
+    /** Absolute path of the record moved aside, when one was. */
+    quarantined?: string;
+}
+
+/** What {@link inspectSlot} found, without changing anything. */
+export interface SlotInspection {
+    state: SlotState;
+    reason: string;
+    /** The authoritative path this session's records live at. */
+    target: string;
+    /** Parsed resident record, when one is present AND parseable. */
+    resident?: Record<string, unknown>;
+}
+
+/** Hours a record stays usable — the reader's own bound, not a second one. */
+const MAX_AGE_MS = RECYCLE_MAX_AGE_HOURS * 3600 * 1000;
+
+function _parse(file: string): Record<string, unknown> | null {
+    try {
+        const decoded: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (typeof decoded === 'object' && decoded !== null && !Array.isArray(decoded)) {
+            return decoded as Record<string, unknown>;
+        }
+        return null;
+    } catch {
+        return null;
+    }
+}
+
+/** Milliseconds since a record's `written_at`, or `null` when it has none. */
+function _ageMs(record: Record<string, unknown>, now: Date): number | null {
+    const raw = record['written_at'];
+    if (typeof raw !== 'string') return null;
+    const at = Date.parse(raw);
+    if (Number.isNaN(at)) return null;
+    return now.getTime() - at;
+}
+
+/**
+ * Read the slot for `session_id` without touching it.
+ *
+ * `conflicting` here is a statement about the RESIDENT relative to the caller's
+ * identity, which is why the session id is required rather than optional: a
+ * record is foreign only with respect to somebody.
+ */
+export function inspectSlot(
+    workspace_root: string,
+    session_id: string | null | undefined,
+    now: Date = new Date(),
+): SlotInspection {
+    const target = path.join(workspace_root, recycle_envelope_rel(session_id));
+    if (!fs.existsSync(target)) {
+        const consumed = path.join(workspace_root, recycle_consumed_rel(session_id));
+        if (fs.existsSync(consumed)) {
+            return { state: 'consumed', reason: 'the record for this session was consumed', target };
+        }
+        const quarantined = path.join(workspace_root, recycle_quarantine_rel(session_id));
+        if (fs.existsSync(quarantined)) {
+            return {
+                state: 'quarantined',
+                reason: 'the slot is free; an unusable record sits in quarantine',
+                target,
+            };
+        }
+        return { state: 'absent', reason: 'no record in this slot', target };
+    }
+    const resident = _parse(target);
+    if (resident === null) {
+        return { state: 'quarantined', reason: 'the resident record does not parse as an object', target };
+    }
+    const violations = validateRecycleEnvelope(resident);
+    if (violations.length > 0) {
+        return {
+            state: 'quarantined',
+            reason: `the resident record fails validation (${violations.length} violation(s))`,
+            target,
+            resident,
+        };
+    }
+    const age = _ageMs(resident, now);
+    if (age === null || age > MAX_AGE_MS) {
+        return {
+            state: 'quarantined',
+            reason:
+                age === null
+                    ? 'the resident record carries no parseable written_at'
+                    : `the resident record is older than ${RECYCLE_MAX_AGE_HOURS} h`,
+            target,
+            resident,
+        };
+    }
+    const owner = String(resident['session_id'] ?? '').trim();
+    const mine = String(session_id ?? '').trim();
+    if (owner !== '' && mine !== '' && owner !== mine) {
+        return {
+            state: 'conflicting',
+            reason: `the slot holds an unconsumed record belonging to session ${owner}`,
+            target,
+            resident,
+        };
+    }
+    return { state: 'published', reason: 'this session has an unconsumed record', target, resident };
+}
+
+/**
+ * Publish `record` into this session's slot under the capacity policy.
+ *
+ * Never throws for a policy reason: a refusal is a return value, because this
+ * runs on the Stop path where an exception is a worse outcome than a missed
+ * record. A genuine I/O failure is reported as `wrote: false` with the reason,
+ * for the same reason.
+ *
+ * The write itself goes through {@link update_json_under_lock} rather than
+ * `atomic_write_json`, and the difference is the whole point: the locked form
+ * gives a read-modify-write, so the resident is inspected and the decision
+ * taken INSIDE the exclusion that stops a peer from publishing between the
+ * inspection and the write. `atomic_write_json` — the path
+ * `session:recycle` still uses — has no such window and cannot express a
+ * refusal.
+ */
+export function publishContinuityRecord(
+    workspace_root: string,
+    session_id: string | null | undefined,
+    record: Record<string, unknown>,
+    now: Date = new Date(),
+): PublishOutcome {
+    const violations = validateRecycleEnvelope(record);
+    if (violations.length > 0) {
+        return {
+            state: 'absent',
+            wrote: false,
+            reason: `refused — the record to publish fails validation: ${violations[0] as string}`,
+        };
+    }
+    const bytes = Buffer.byteLength(JSON.stringify(record, null, 2), 'utf-8');
+    if (bytes > RECYCLE_ENVELOPE_MAX_BYTES) {
+        return {
+            state: 'absent',
+            wrote: false,
+            reason: `refused — ${bytes} bytes exceeds the ${RECYCLE_ENVELOPE_MAX_BYTES} byte slot cap`,
+        };
+    }
+
+    const target = path.join(workspace_root, recycle_envelope_rel(session_id));
+    const before = inspectSlot(workspace_root, session_id, now);
+
+    // A foreign, still-usable record is not this session's to move or replace.
+    // Refusing costs this session's resume; superseding costs another session's,
+    // and that one has no way to find out.
+    if (before.state === 'conflicting') {
+        return { state: 'conflicting', wrote: false, reason: `refused — ${before.reason}` };
+    }
+
+    // Monotonicity. A delayed or retried publisher must not roll the slot back
+    // to an earlier moment of the same session.
+    if (before.state === 'published' && before.resident !== undefined) {
+        const residentAt = Date.parse(String(before.resident['written_at'] ?? ''));
+        const incomingAt = Date.parse(String(record['written_at'] ?? ''));
+        if (!Number.isNaN(residentAt) && !Number.isNaN(incomingAt) && incomingAt < residentAt) {
+            return {
+                state: 'published',
+                wrote: false,
+                reason: 'refused — the resident record is newer than the one offered',
+            };
+        }
+    }
+
+    let quarantined: string | undefined;
+    if (before.state === 'quarantined' && fs.existsSync(target)) {
+        // Move aside, never delete. See `recycle_quarantine_rel`.
+        const dest = path.join(workspace_root, recycle_quarantine_rel(session_id));
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.renameSync(target, dest);
+            quarantined = dest;
+        } catch (exc) {
+            return {
+                state: 'quarantined',
+                wrote: false,
+                reason: `refused — could not quarantine the unusable resident: ${String(exc)}`,
+            };
+        }
+    }
+
+    const result = update_json_under_lock<Record<string, unknown>>(target, () => record);
+    if (result !== 'written') {
+        return {
+            state: before.state,
+            wrote: false,
+            reason: `refused — the slot write did not complete (${result})`,
+            ...(quarantined !== undefined ? { quarantined } : {}),
+        };
+    }
+    return {
+        state: 'published',
+        wrote: true,
+        reason:
+            before.state === 'published'
+                ? 'superseded this session’s earlier record'
+                : `published into a ${before.state} slot`,
+        ...(quarantined !== undefined ? { quarantined } : {}),
+    };
+}

package/src/scripts/_lib/continuity_writer.ts

@@ -0,0 +1,253 @@
+/**
+ * The deterministic continuity-record writer.
+ *
+ * `road-to-continuity-writer-activation` step 1.2. Until this module existed
+ * `agent-config session:recycle` was the ONLY writer of the continuity record
+ * in the tree, which is why `verb:session:recycle` counts on the
+ * `public_continuity_commands` axis and why an advisory has to tell a human to
+ * run it before `/clear`: continuity did not happen unless somebody
+ * remembered.
+ *
+ * Every field here is computed from on-disk state and nothing is asked of a
+ * model. That is not a cost optimisation, it is what makes the record a
+ * `continuity_record` rather than a `main_session` one: the judgement fields
+ * (`decisions`, `failed_approaches`, `successful_approaches`, …) are FORBIDDEN
+ * on the variant precisely so a deterministic writer cannot fill one with a
+ * guess and a reader cannot be left unable to tell a derived record from a
+ * judged one.
+ *
+ * Two gates, and both are needed:
+ *
+ *   1. `continuity.auto_record` must be `on`. It ships `off`, so with the
+ *      shipped default this module is never reached and the tree behaves
+ *      exactly as it does today.
+ *   2. The session must be SUBSTANTIVE by the committed floor
+ *      (`is_substantive`) and must have a resolvable task. Both come from the
+ *      concern's own counters and claim state, never from file presence.
+ *
+ * The task gate is the sharper of the two, and its bound is stated rather than
+ * hidden: a record needs at least one `acceptance_criteria` entry, and the only
+ * deterministic source of one in this tree is the roadmap a session has
+ * claimed. A session with no claim therefore leaves no record — and the
+ * alternative, writing a placeholder acceptance criterion, would assert a
+ * definition of "done" nobody set, which is the exact failure the variant's
+ * forbidden-key set exists to prevent.
+ */
+import * as fs from 'node:fs';
+
+import { load_agent_settings } from './agent_settings.js';
+import { resolvePredecessor } from './recycle_envelope_paths.js';
+import { CHECKBOX_LINE, phaseLines } from './roadmap_checkboxes.js';
+import { readHead, roadmapPath } from './run_checkpoint.js';
+import { is_substantive, type StoredEolCounters } from './session_eol.js';
+import { CAPSULE_SCHEMA_VERSION, MAX_ENTRIES, MAX_LINE_CHARS } from './subagent_capsule.js';
+
+/** Settings key that arms this writer. Ships `off`. */
+export const AUTO_RECORD_KEY = 'continuity.auto_record';
+
+/**
+ * Read `continuity.auto_record` from the merged settings cascade.
+ *
+ * The cascade merges the shipped template, so a workspace with no settings file
+ * resolves `off` through the template rather than through the trailing
+ * `return false` — which is why that line is defence against an unreadable
+ * cascade and not the path a default install takes. Both directions are pinned
+ * by fixtures, because "absent" and "off" arriving by different routes is
+ * exactly the kind of thing a reader assumes and a test has to establish.
+ */
+export function auto_record_enabled(root: string): boolean {
+    try {
+        const settings = load_agent_settings({ cwd: root });
+        const section = settings['continuity'];
+        if (section && typeof section === 'object' && !Array.isArray(section)) {
+            const v = (section as Record<string, unknown>)['auto_record'];
+            // YAML 1.1 parses a bare `on` as boolean true — accept both.
+            return v === 'on' || v === true;
+        }
+    } catch {
+        // fail-closed: unreadable settings leave the writer disarmed
+    }
+    return false;
+}
+
+/** Settings key that governs run-checkpoint production. Ships `on`. */
+export const RUN_CHECKPOINTS_KEY = 'continuity.run_checkpoints';
+
+/**
+ * Read `continuity.run_checkpoints` from the merged settings cascade.
+ *
+ * Fails OPEN, unlike its sibling above, and the asymmetry is the point: this
+ * switch governs behaviour the tree already had, so an unreadable cascade must
+ * leave it running. Its sibling arms something new, so an unreadable cascade
+ * must leave that disarmed. A single helper with one polarity would have been
+ * wrong for one of the two.
+ */
+export function run_checkpoints_enabled(root: string): boolean {
+    try {
+        const settings = load_agent_settings({ cwd: root });
+        const section = settings['continuity'];
+        if (section && typeof section === 'object' && !Array.isArray(section)) {
+            const v = (section as Record<string, unknown>)['run_checkpoints'];
+            if (v === 'off' || v === false) return false;
+        }
+    } catch {
+        // fail-open: an unreadable cascade never silently removes a recovery aid
+    }
+    return true;
+}
+
+/** Why no record was built, when none was. Always a stated reason. */
+export interface WriterDecision {
+    record: Record<string, unknown> | null;
+    reason: string;
+}
+
+/** How many `remaining` / `acceptance_criteria` lines a record carries. */
+const LIST_CAP = 12;
+
+function _clip(line: string): string {
+    const one = line.replace(/\s+/g, ' ').trim();
+    return one.length <= MAX_LINE_CHARS ? one : `${one.slice(0, MAX_LINE_CHARS - 1)}…`;
+}
+
+/**
+ * Open, closed and parked step counts plus the open step bodies.
+ *
+ * Deliberately reuses `phaseLines` + `CHECKBOX_LINE` rather than a fourth
+ * regex: a writer that disagreed with the dashboard about whether a roadmap is
+ * finished would put that disagreement into the record a successor resumes
+ * from.
+ */
+export function roadmapShape(text: string): { done: number; total: number; open: string[] } {
+    let done = 0;
+    let total = 0;
+    const open: string[] = [];
+    for (const raw of phaseLines(text)) {
+        const m = CHECKBOX_LINE.exec(raw);
+        if (m === null) continue;
+        total += 1;
+        const mark = m[1];
+        if (mark === 'x' || mark === 'X') {
+            done += 1;
+            continue;
+        }
+        if (mark === '~' || mark === '-') continue;
+        if (open.length < LIST_CAP) {
+            open.push(_clip((m[2] ?? '').replace(/\*\*/g, '')));
+        }
+    }
+    return { done, total, open };
+}
+
+/**
+ * Checkbox bodies under an `## Acceptance Criteria` heading.
+ *
+ * `phaseLines` deliberately excludes this section — an autonomous run must not
+ * mistake an acceptance criterion for its next step — so it is read separately
+ * here, which is the one place the two readings legitimately differ.
+ */
+export function acceptanceCriteria(text: string): string[] {
+    const lines = text.split('\n');
+    const out: string[] = [];
+    let inside = false;
+    for (const raw of lines) {
+        const heading = /^(#{2,3})[ \t]+(.*?)[ \t]*$/.exec(raw);
+        if (heading !== null) {
+            inside = /^Acceptance[ \t]+Criteria\b/i.test(heading[2] ?? '');
+            continue;
+        }
+        if (!inside) continue;
+        const m = CHECKBOX_LINE.exec(raw);
+        if (m === null) continue;
+        if (out.length < LIST_CAP) {
+            out.push(_clip((m[2] ?? '').replace(/\*\*/g, '')));
+        }
+    }
+    return out;
+}
+
+export interface BuildInput {
+    /** Workspace root — the record's `workspace`, and the root every read is relative to. */
+    root: string;
+    /** Raw session id, as the record paths and the claim state key on it. */
+    sessionId: string;
+    /** The roadmap slug this session claimed, or `null` when it claimed none. */
+    slug: string | null;
+    /** The concern's own counters for this session. */
+    counters: StoredEolCounters | null;
+    /** Injected for determinism in tests. */
+    now?: Date;
+}
+
+/**
+ * Build the record, or say why there is none.
+ *
+ * Never throws and never shells out: this runs on the Stop path, where a
+ * subprocess is a latency cost paid on every turn's end and an exception is
+ * worse than a missing record. `head` is read from `.git` directly (worktree
+ * aware) rather than through `git`, and the richer anchor fields
+ * `session:recycle` collects with `git status` are deliberately omitted — the
+ * trade is one drift line for a Stop path that spawns nothing, and it is stated
+ * in `docs/contracts/continuity-record-slot.md` rather than left for a reader
+ * to discover by diffing two producers.
+ */
+export function buildContinuityRecord(input: BuildInput): WriterDecision {
+    const { root, sessionId, slug, counters } = input;
+    const now = input.now ?? new Date();
+
+    if (!is_substantive(counters)) {
+        return {
+            record: null,
+            reason: 'no record — the session is not substantive by the committed floor',
+        };
+    }
+    if (slug === null || slug.trim() === '') {
+        return {
+            record: null,
+            reason: 'no record — no claimed roadmap, so no deterministic acceptance criterion exists',
+        };
+    }
+
+    let text: string;
+    try {
+        text = fs.readFileSync(roadmapPath(root, slug), 'utf-8');
+    } catch {
+        return { record: null, reason: `no record — the claimed roadmap ${slug} is not readable` };
+    }
+
+    const shape = roadmapShape(text);
+    if (shape.total === 0) {
+        return { record: null, reason: `no record — ${slug} carries no phase checkboxes to count` };
+    }
+
+    const declared = acceptanceCriteria(text);
+    const criteria =
+        declared.length > 0
+            ? declared
+            : // A roadmap with no declared criteria still has one definitional
+              // completion condition, and it is derived from the artefact class
+              // rather than judged: every step closed. Anything richer would be
+              // a definition of done nobody wrote.
+              [`every phase step in agents/roadmaps/${slug}.md is closed`];
+
+    const record: Record<string, unknown> = {
+        capsule_version: CAPSULE_SCHEMA_VERSION,
+        variant: 'continuity_record',
+        summary: _clip(`${slug}: ${shape.done} of ${shape.total} steps closed`),
+        task: _clip(slug),
+        workspace: root,
+        written_at: now.toISOString(),
+        acceptance_criteria: criteria.slice(0, MAX_ENTRIES),
+        remaining: shape.open.slice(0, MAX_ENTRIES),
+        predecessor: resolvePredecessor(root, sessionId),
+        artifact_paths: [`agents/roadmaps/${slug}.md`],
+    };
+    if (sessionId.trim() !== '') {
+        record['session_id'] = sessionId.trim();
+    }
+    const head = readHead(root);
+    if (head !== null) {
+        record['head'] = head;
+    }
+    return { record, reason: `record built for ${slug} (${shape.done}/${shape.total} closed)` };
+}

package/src/scripts/_lib/hook_settings.ts

@@ -110,3 +110,88 @@ export function leanProjectionModeRaw(root: string): string {
     }
     return '';
 }
+
+/**
+ * Raw `lean_projection.hosts` list out of `.agent-settings.yml`, or `[]`.
+ *
+ * Same indentation-shaped discipline as `leanProjectionModeRaw` above and for
+ * the same reason — a hook must never fail a tool call because a YAML parser
+ * could not load — extended to the three list shapes a human writes:
+ *
+ *     lean_projection:
+ *       hosts: [claude-code]          # inline
+ *     lean_projection:
+ *       hosts:                        # block, indented under the key
+ *         - claude-code
+ *     lean_projection:
+ *       hosts:                        # block, at the key's own indent
+ *       - claude-code
+ *
+ * All three are legal YAML and `js-yaml` loads them identically; the third was
+ * read as `[]` until 2026-09-08 (R2 finding 2) and is covered by three fixtures
+ * in `tests/scripts/lean_projection_hosts.test.ts`.
+ *
+ * Interpretation is NOT done here. `[]` means "nothing was written", and
+ * `_lib/lean_projection_mode.ts::resolveLeanProjectionHosts` decides that this
+ * means the default rather than "no host" — keeping that decision in one place
+ * is what stops the projector and the delivery concern from disagreeing, which
+ * is the whole reason the mode reader is split this way.
+ */
+export function leanProjectionHostsRaw(root: string): string[] {
+    const file = path.join(root, SETTINGS_FILE);
+    let text: string;
+    try {
+        if (!fs.statSync(file).isFile()) return [];
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return [];
+    }
+    const strip = (s: string): string => s.trim().replace(/^["']|["']$/g, '');
+    let inSection = false;
+    let inBlock = false;
+    let blockIndent = -1;
+    const out: string[] = [];
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.replace(/^\s+/, '').startsWith('#')) continue;
+        if (!(line.startsWith(' ') || line.startsWith('\t'))) {
+            inSection = /^lean_projection\s*:\s*$/.test(line);
+            inBlock = false;
+            continue;
+        }
+        if (!inSection) continue;
+        const indent = (/^\s*/.exec(line) as RegExpExecArray)[0].length;
+        if (inBlock) {
+            const item = /^\s*-\s*(\S.*)$/.exec(line);
+            // `>=`, not `>`: YAML lets a block sequence sit at its KEY's own
+            // indent, and `js-yaml` — the parser `condense` uses on this same
+            // file — loads that shape identically to the deeper-indented one.
+            // With `>` the same-indent form parsed as `[]`, which
+            // `resolveLeanProjectionHosts` reads as "nothing was written" and
+            // answers with the default `[claude-code]` while the projector
+            // thins whatever the file actually says. Two readers disagreeing
+            // about the delivery-host set is the one failure this split exists
+            // to prevent (R2 finding 2). A SHALLOWER item still ends the block:
+            // it belongs to a different mapping level, never to `hosts`.
+            if (item !== null && indent >= blockIndent) {
+                const v = strip(item[1] ?? '');
+                if (v !== '') out.push(v);
+                continue;
+            }
+            inBlock = false;
+        }
+        const inline = /^\s+hosts\s*:\s*\[([^\]]*)\]\s*$/.exec(line);
+        if (inline !== null) {
+            for (const part of (inline[1] ?? '').split(',')) {
+                const v = strip(part);
+                if (v !== '') out.push(v);
+            }
+            continue;
+        }
+        if (/^\s+hosts\s*:\s*$/.test(line)) {
+            inBlock = true;
+            blockIndent = indent;
+        }
+    }
+    return out;
+}