report_dir cannot be set by ac setup, but the plot_ir note tells the operator to use it

[mkovero]

problem

ac plot ir prints, when no report directory is configured:

  note: report_dir not configured — result not persisted (see `ac setup`)

ac setup has no token for it. Its parser accepts output, input, reference, device, dburef/dbu, reference-output/refout/ref-out, gpio, range, server-timeout/server-idle-timeout, and temp/temperature (ac-cli/src/parse/setup.rs). Nothing sets report_dir, and ac setup's own read-out does not show it either.

The only way to configure it is to edit ~/.config/ac/config.json by hand, which is what I had to do on pupu to capture the #460 AC2 rig record.

why it matters

The message names a command that cannot do the thing. An operator who follows it finds no such option and, on a rig session, silently gets no persisted reports — the archival half of the measurement is lost with a note that reads as though it told them how to fix it.

This is the silent-config shape in reverse: not a value that quietly does nothing, but a remedy that quietly does not exist.

acceptance criteria

• ac setup can set report_dir (and clear it), or the note names whatever the real mechanism is.
• ac setup's read-out shows the configured report directory, so an operator can see whether captures will persist before running one.
• Test: a parse test for the token, and a check that the plot_ir note and the setup surface agree — the note must not be able to name a command that cannot do it.

evidence

Found while configuring pupu for #460 AC2 (2026-09-15). ac-cli/src/commands/plot.rs:530 emits the note; ac-cli/src/parse/setup.rs has no matching token.

[mkovero]

Scope label set: scope-none. This is config plumbing and note text; no standard governs it.

[mkovero]

spec

type: bug

problem statement
When no report directory is configured, ac plot ir prints a note telling the operator to use ac setup. ac setup has no way to set report_dir, and its read-out does not show it. The only fix is to edit ~/.config/ac/config.json by hand. So the note points to a fix that does not exist. On a rig session, an operator who follows the note gets no saved reports, and nothing tells them that before the capture runs. The archive copy of the measurement is lost quietly. The reporter hit this on pupu while capturing the #460 AC2 record.

Choice between the two fixes the reporter offered: add report_dir to ac setup. Rewording the note alone would leave hand-editing the JSON as the only way to set it, and the operator still could not check the setting before a capture.

acceptance criteria

• ac setup accepts a token that sets report_dir; after it runs, ac plot ir saves its result to that directory and does not print the "not configured" note.
• ac setup can clear report_dir; after clearing, ac plot ir prints the "not configured" note again and saves nothing.
• ac setup's read-out shows the report directory, and shows it as unset when it is not configured, so an operator can tell before a capture whether results will be saved.
• A value set through ac setup is still in effect after the daemon restarts (it is written to the same config that hand-editing changes today).
• An existing config.json with report_dir set by hand still works unchanged.
• If the given directory cannot be used (for example it does not exist or cannot be written), the operator is told at setup time or at capture time, never after a capture that silently saved nothing.
• The "not configured" note names the ac setup token that actually sets the directory.
• Parse test covering the new token, including its clear form.
• A test that fails if the remedy named in the plot ir note is not a token the ac setup parser accepts, so the note and the setup surface cannot drift apart again.

out of scope

• Making every other config key settable through ac setup.
• Changing where reports are written, their file format, or naming.
• Other commands' notes that mention ac setup (worth checking separately; not covered here).
• Auto-spawned daemon's stderr goes to /dev/null, so a failed plot_level step prints as an empty table #443 (auto-spawned daemon stderr), which is unrelated.

files likely affected

• ac-rs/ac-cli/src/parse/setup.rs — new token (cited in issue)
• ac-rs/ac-cli/src/commands/plot.rs — note text (cited in issue, ~line 530)
• ac-cli setup command / read-out — unknown module
• ac-core shared/ config — the report_dir field
• ac-daemon — only if ac setup sends settings to the daemon over ZMQ; unknown

needs architect review
yes — if ac setup applies settings through the daemon, a new key changes the ZMQ setup message, and that change reaches ac-daemon and ac-cli. The rules for the path also need a decision before build: relative paths and ~, whether a missing directory is created or refused, and whether the check happens at setup time or capture time.

ux
The change adds a new line to ac setup's read-out and changes the note's wording. ux should set the read-out line's label and how "unset" is shown, and the exact note text.

rig check
None needed. This is config plumbing and printed text; tests and a local run can settle every criterion. No requires-rig.

estimated complexity
medium: 2–8h

[mkovero]

what this output must communicate

1. Before a capture: whether ac plot results will be saved, and where. ac setup shows this.
2. After a capture: whether this result was saved, and the exact files. The report line in ac plot ir shows this.
3. When nothing was saved: the one ac setup command that fixes it, spelled so it can be typed as shown.

The path alone is not enough. An operator also needs to know whether the daemon can write there. A path the daemon cannot write to reads exactly like a working one, and that is the #472 failure again, just one step later.

what to remove

• **note: report_dir not configured — result not persisted (see \ac setup`)** has three problems. It names a remedy that does not exist. It uses the config key name (report_dir) where the operator types something else. It also goes to stderr, while the report/csvlines it stands in for go to stdout. So anyone piping or logging stdout sees a saved result as two lines and an unsaved result as *nothing*. A missing line is a weak signal. The "not saved" state goes in the samereport` slot, on stdout.

• plot ir building the report path from the CLI's own config. print_ir_report (commands/plot.rs:952) joins cfg.report_dir from ac_core::config::load in the CLI process. The daemon writes using its config (handlers/audio/plot.rs:1387). These are different processes and can hold different values:

  • With server_host set, the CLI may have no report_dir while the daemon has one. The note then says "not persisted" about a file that was written.
  • It can also go the other way: the CLI prints a path for a file that was never written.
  • A write failure (plot_ir: report write error (...)) goes only to daemon stderr, which is hidden for an auto-spawned daemon (Auto-spawned daemon's stderr goes to /dev/null, so a failed plot_level step prints as an empty table #443). The CLI still prints report <path>. That breaks the triage criterion "never after a capture that silently saved nothing" at the most trusted place on the screen.

  The report line should show what the daemon says it wrote, not what the CLI guesses. This needs a wire change; see open question 1.

proposed output

ac setup read-out: new line, placed after Room temp

It goes next to Room temp because both describe what a capture records, not how it is routed. Same label column as its neighbours (value starts at col 17).

Set, and the daemon can write there:

  -- Hardware config (server) --
  Device:         0
  Output channel: 2
  Input channel:  3
  Reference ch:   0  ->  system:capture_1
  Ref output ch:  (main output)
  dBu reference: 774.5967 mVrms  (0.77459667 V)
  DMM host:      (not configured)
  GPIO port:     (not configured)
  Range:         20 – 20000 Hz
  Emission max:  0.0 dBFS  (full scale, fixed)
  Room temp:     22.5 °C  (c = 344.4 m/s)
  Report dir:    /home/mui/ac-reports
  Server idle:   (no timeout)
  Saved.

Not set:

  Room temp:     22.5 °C  (c = 344.4 m/s)
  Report dir:    (not set — plot results are not saved)
  Server idle:   (no timeout)

Set, but the daemon's check fails. This happens when the directory was removed or unmounted after it was set. The problem goes on its own line under the value, because paths have no length limit and a trailing (...) would push past 80 columns:

  Room temp:     22.5 °C  (c = 344.4 m/s)
  Report dir:    /mnt/rigdata/ac-reports
                 cannot write: No such file or directory (os error 2)
  Server idle:   (no timeout)

The OS error is printed as-is. The daemon knows the write check failed and knows the errno. It does not know why the disk is gone, so the text claims nothing more.

ac setup report-dir <dir>: refused

A bad path is refused when typed, and the config is left unchanged. This goes through the existing check_ack error path, so the format already exists. The OS error goes on a second line, indented under the path, to keep it within 80 columns:

$ ac setup report-dir /home/mui/ac-reprots
  error: report-dir /home/mui/ac-reprots
         No such file or directory (os error 2) — setting not changed

Clearing it:

$ ac setup report-dir none
  ...
  Report dir:    (not set — plot results are not saved)
  ...
  Saved.

ac plot ir tail: three states, same slot, all stdout

Saved (the daemon confirms both files):

  gate          tukey0.25 window, 8192 samples (170.67 ms) → f_low 5.9 Hz
  report        /home/mui/ac-reports/2026-09-17T09-41-12Z-plot_ir.json
  csv           /home/mui/ac-reports/2026-09-17T09-41-12Z-plot_ir.csv

Not configured:

  gate          tukey0.25 window, 8192 samples (170.67 ms) → f_low 5.9 Hz
  report        not saved — no report directory  (ac setup report-dir <dir>)

(76 columns. <dir> is part of the command syntax, not a design placeholder. It is the one thing the operator has to supply.)

Configured, but the write failed. This is the case the CLI cannot see today:

  gate          tukey0.25 window, 8192 samples (170.67 ms) → f_low 5.9 Hz
  report        not saved — write failed in /mnt/rigdata/ac-reports
                Permission denied (os error 13)

If the JSON was written but the CSV failed, the report line prints the path as normal and the csv line takes the failure form:

  report        /mnt/rigdata/ac-reports/2026-09-17T09-41-12Z-plot_ir.json
  csv           not saved — No space left on device (os error 28)

Worst case for width: path lines go past 80 columns once a directory is longer than about 30 characters. That is accepted for path values only. A path must stay whole and copyable, so it is never truncated or elided. Every label, state word, and error line above fits in 80.

field justifications

• Report dir: label: plain words, the same form as DMM host: / GPIO port:. The operator types report-dir, and the label reads as the same thing.
• Resolved absolute path as the value: shows what the daemon will actually use, not what was typed. A ~ or a relative path means nothing to a daemon that may be on another host.
• (not set — plot results are not saved): the unset state has a consequence, so it names it, just as Room temp: names the assumed speed. (not configured) alone would read as harmless, like an absent DMM.
• cannot write: <os error> continuation line: the read-out exists so the operator can check before a capture (triage criterion 3). A path the daemon cannot use must not look like one it can.
• error: report-dir <path> + <os error> — setting not changed: says the old value still stands, so a refused typo does not leave the operator unsure which directory is active.
• report line always present in plot ir: one fixed slot for the archive state, on stdout, readable by grep (grep '^ report') in all three states.
• not saved — prefix: the state comes first so it reads at a glance, then the reason, then the fix.
• (ac setup report-dir <dir>): the remedy as a literal, typeable command. This is the string the triage drift test must check against the parser.
• OS error on its own line: a fault, so it gets its own line, per the CLI rules. It is only a line for the operator to check, never a guessed cause.
• csv line only when the JSON succeeded, or when it failed separately: avoids repeating one failure twice.

before / after

Current output is reconstructed from commands/setup.rs and commands/plot.rs at 26f59085. There is no running implementation yet.

before (ac setup, report_dir set by hand in config.json):
  Room temp:     22.5 °C  (c = 344.4 m/s)
  Server idle:   (no timeout)

after:
  Room temp:     22.5 °C  (c = 344.4 m/s)
  Report dir:    /home/mui/ac-reports
  Server idle:   (no timeout)

before (ac plot ir, no report_dir):
  gate          tukey0.25 window, 8192 samples (170.67 ms) → f_low 5.9 Hz
  note: report_dir not configured — result not persisted (see `ac setup`)     [stderr]

after:
  gate          tukey0.25 window, 8192 samples (170.67 ms) → f_low 5.9 Hz
  report        not saved — no report directory  (ac setup report-dir <dir>)

before (ac plot ir, report_dir set, daemon write failed):
  report        /mnt/rigdata/ac-reports/2026-09-17T09-41-12Z-plot_ir.json
  csv           /mnt/rigdata/ac-reports/2026-09-17T09-41-12Z-plot_ir.csv
  (the files do not exist; the error went to the daemon's stderr)

after:
  report        not saved — write failed in /mnt/rigdata/ac-reports
                Permission denied (os error 13)

• removed: the stderr note: line, with its non-existent remedy and its config-key wording. Also removed: paths the CLI built from its own config.
• added: the Report dir: read-out line, with unset and cannot-write forms. Also added: setup-time refusal text, and the not-saved and write-failed forms of the report line.
• changed: the archive state moves from stderr to the stdout report slot, so it shows in every state. Paths shown are the ones the daemon says it wrote.

setup token

• report-dir <dir> sets it. Suggested aliases, in the style of the other keys: report_dir, reports.
• report-dir none / report-dir off clears it, using the same clear words as gpio and refout. A directory that really is named none can still be given as ./none or as an absolute path.
• The value must not go through expand() or be lowercased. The parser already takes the value raw, so keep it that way. Paths are case-sensitive.
• Add report-dir to the unknown key list in parse/setup.rs.
• The parser and the plot ir note should read the token from one constant. That is how the triage drift test can fail when they disagree, rather than comparing two string literals that happen to match.

open questions (architect: needs-design is still open)

1. Wire: the daemon reports what it wrote. The after forms for plot ir need the daemon to tell the CLI the outcome: the paths written, or not configured, or the write error per file. That could go in the measurement/report frame or the done frame. Without it the CLI can only guess, and the write-failed state cannot be shown. My view: this is part of report_dir cannot be set by ac setup, but the plot_ir note tells the operator to use it #472, not a follow-up. Criterion 6 ("never after a capture that silently saved nothing") cannot be met from CLI-side config alone.
2. Path resolution. Should ~ and relative paths be expanded by the CLI (against its own cwd and $HOME) before sending, or refused when server_host points to a remote daemon? UX only requires that the read-out show the absolute path the daemon holds.
3. Missing directory: create or refuse? UX prefers refuse. mkdir -p on a typo (ac-reprots) makes a working but wrong archive location, and the operator never notices. If the architect chooses create, the read-out should say so once, on the Saved. line (Saved. Created /home/mui/ac-reports.).
4. Remote daemon paths. Paths are on the daemon's filesystem. When server_host is set, should the report line prefix the host, scp-style (192.168.9.27:/srv/ac/reports/...), so the path can be copied into scp? This is optional, and only worth doing if the CLI already knows the daemon is remote.
5. Out of scope, flagged for triage: ac plot (frequency sweep) and its bands report also write to report_dir, but print no report line in any state. The same silent-archive gap exists there.

[mkovero]

design decision

core question
Which process decides whether a report directory is usable, and whether a capture was saved? Today the CLI's config decides what plot ir prints, and the daemon's config decides what gets written. The two can disagree (server_host, a failed write that only reaches the hidden daemon stderr, #443). Also, the daemon's setup handler (ac-daemon/src/handlers/admin.rs::setup) ignores a report_dir key completely, so adding a CLI token alone would do nothing.

option A — CLI-side
ac setup report-dir writes config.json from the CLI through ac_core::config::save, and the CLI checks the directory itself. plot ir keeps building the report/csv paths from cfg.report_dir.
tradeoffs: No wire change. But it is wrong whenever the daemon is remote (server_host): the path lives on the daemon's filesystem, which the CLI cannot check. It also skips the setup request that owns config today. And it cannot see a write failure at capture time, so triage criterion 6 and UX open question 1 stay unmet.

option B — daemon-authoritative, additive wire fields

• setup gains an update.report_dir key. The daemon validates it before changing anything, stores it, and reports whether the directory can be written on every setup reply.
• plot_ir's done frame reports what was actually written (the paths) or why nothing was.
• The CLI prints only what the daemon reports.
  tradeoffs: Adds three fields to the wire (all additive) and one new refusal shape. In exchange, the read-out and the report line both come from the process that does the writing, locally or remotely.

option C — B without the done-frame field
Setup-side only. The CLI keeps guessing the paths.
tradeoffs: Smaller, but the "configured, write failed" state still prints a path to a file that does not exist. That fails criterion 6 on the line the operator trusts most.

recommendation
Option B. The daemon already owns config: setup goes through it, and it reloads config.json before every request (ZMQ.md → Config reload). It is also the only process that writes reports. So it is the only process that can say truthfully whether a directory works and whether a capture was saved.

Answers to the open questions in the ux comment:

1. Wire: yes, part of report_dir cannot be set by ac setup, but the plot_ir note tells the operator to use it #472. The outcome goes in the done frame. It does not go in measurement/report: that payload is the archived MeasurementReport, which should not describe its own file, and it is published before the write happens.
2. Path resolution: the CLI resolves the path only when the daemon is local (cfg.server_host is None, the same test commands/server.rs:85 uses). It expands a leading ~ / ~/ with the CLI's $HOME and joins a relative path onto the CLI's cwd. When server_host is set, the CLI sends the value exactly as typed. The daemon accepts absolute paths only, so a relative path, ~user, or an empty value sent to a remote daemon is refused. The daemon stores the path as given, with no canonicalize: a symlink or mount path must stay the path the operator named.
3. Missing directory: refuse, never create. This also applies at capture time (see the write_to note below).
4. scp-style host prefix: no. Paths print exactly as the daemon reports them, as ux specified. Deferred as optional.
5. ac plot / bands persistence line: out of scope. It is a follow-up for triage, listed under risks.

affected modules

• ac-cli — new setup token and the CLI's local path resolution; the Report dir: read-out; the refusal rendering; the plot ir report/csv lines driven by the done frame instead of the CLI's cfg; the drift test.
• ac-daemon — the setup handler validates, stores and reports on report_dir; setup refuses a non-empty update whose save fails; plot_ir writes without creating the directory and reports the outcome in done.
• ac-core — none. Config::report_dir already exists with #[serde(default)], so hand-edited configs keep working unchanged.
• ac-view / ac-scene — none. Neither sends setup nor reads plot_ir's done frame (checked by grep).

file manifest
ac-rs/crates/ac-cli/src/parse/mod.rs
ac-rs/crates/ac-cli/src/parse/setup.rs
ac-rs/crates/ac-cli/src/commands/mod.rs
ac-rs/crates/ac-cli/src/commands/setup.rs
ac-rs/crates/ac-cli/src/commands/plot.rs
ac-rs/crates/ac-cli/tests/it_plot_ir.rs
ac-rs/crates/ac-daemon/src/handlers/admin.rs
ac-rs/crates/ac-daemon/src/handlers/audio/plot.rs
ac-rs/crates/ac-daemon/tests/it_protocol/setup.rs
ac-rs/crates/ac-daemon/tests/it_protocol/plot_ir.rs
ac-rs/ZMQ.md
README.md

interface changes

• CLI: ac setup report-dir <dir>, with aliases report_dir and reports. ac setup report-dir none|off|disable|disabled clears it (the same words as gpio / refout, matched case-insensitively). The key is lowercased by expand() as usual. The value is passed raw: no expand(), no lowercasing. Add report-dir to the unknown key list.
• CommandKind::Setup gains report_dir: Option<Option<String>> (outer None means untouched, Some(None) means clear).
• commands::setup::run gains a cfg: &ac_core::config::Config parameter, so it can read server_host for path resolution. The call site is commands/mod.rs::dispatch.
• commands/plot.rs::print_ir_report loses its cfg parameter. Its only use of it is cfg.report_dir, at the lines this change removes.
• Cargo features: none.

ZMQ protocol impact
Yes. Every change is additive or a new refusal. No existing field changes meaning.

1. setup request: update.report_dir: "<absolute path>" | null. Validation runs before any other field in the update is applied. If it fails, nothing is changed or saved (so "setting not changed" is true for the whole command). The reply is:
   {"ok": false, "error": "report-dir <path>: <reason> — setting not changed", "refused": {"key": "report_dir", "path": "<path>", "reason": "<reason>"}}
error stays one line for generic clients. refused lets ac render the two-line ux form.
   The reason is either must be an absolute path on the daemon host or the OS error text, printed as-is (No such file or directory (os error 2), Not a directory (os error 20), Permission denied (os error 13), …).
2. setup reply: new top-level report_dir_status, placed beside config rather than inside it, on the same reasoning as max_dbfs: it is not a config value. It is present only when config.report_dir is set: {"writable": true} | {"writable": false, "error": "<os error>"}. It is computed on every setup call, including the read-only update: {} calls.
3. setup save failure: when update is non-empty and ac_core::config::save fails, reply {"ok": false, "error": "config not saved (<config path>): <err>"} instead of today's eprintln plus ok: true. Reason: config is reloaded from disk before the next request, so an unsaved value silently reverts right after the read-out has shown it (criterion 4, and the silent-config defect class). Empty-update calls (generate.rs:121, gpio.rs:385) behave as before.
4. plot_ir done frame: new report_files:
   {"dir": null} when not configured, or
   {"dir": "<path>", "json": {"path": "<file>"} | {"error": "<err>"}, "csv": {"path": "<file>"} | {"error": "<err>"}}.
   plot, plot_level and the other done frames are unchanged.

Consumers: ac-cli is updated in this issue. ac-view is unaffected. External pyzmq scripts (headless transfer runs) ignore unknown fields. A new CLI against an old daemon gets no report_files and prints the fallback line below. Old CLI against new daemon: unchanged behavior.

implementation notes for developer

• Parser (parse/setup.rs::parse_setup): add a pub(crate) const REPORT_DIR_TOKEN: &str = "report-dir"; and use it as the match pattern next to the aliases. Tests: set, each clear word, a value containing uppercase letters that must come through unchanged, and ./none staying a path. Also extend the two exhaustive-destructure tests (test_setup_temp_does_not_touch_other_fields, test_setup_server_timeout_does_not_touch_other_fields) with the new field.
• CLI resolution (commands/setup.rs::run): resolve ~ and relative paths only if cfg.server_host.is_none(). Insert "report_dir" into update the same way gpio_port is inserted, with Value::Null for clear. Before check_ack, if the reply is ok: false and has a refused object, print the ux two-line form ( error: report-dir <path> / aligned <reason> — setting not changed) and exit(1). Otherwise fall through to check_ack. Put the Report dir: line after Room temp with the three ux forms (set / not set / cannot write: continuation line), reading config.report_dir plus report_dir_status. If the path is set but report_dir_status is absent (old daemon), print the path alone.
• Daemon setup (handlers/admin.rs::setup): validate update.report_dir at the top, before the output_channel block. Steps: is_absolute(), then std::fs::metadata → is_dir(), then a write probe. The probe does OpenOptions::create_new on <dir>/.ac-write-probe-<pid>-<nanos>, then removes the file; a failed removal is ignored. Put the probe in one private fn and use it for both validation and report_dir_status. Use the std::io::Error Display as the reason, not an anyhow chain, so the text matches the ux examples. For the model, see how backend returns early with ok:false, and the snapshot_spool_dir null/str handling.
• Daemon plot_ir (handlers/audio/plot.rs, the if let Some(ref dir) = report_dir block after the measurement/report send_pub, ~l.1397–1417): stop calling MeasurementReport::write_to here. It runs create_dir_all on the parent (ac-core/src/measurement/report/mod.rs:215), so a directory removed after setup would be silently recreated, which is the typo/archive-in-the-wrong-place failure again. Use report.to_json() + std::fs::write instead, so a missing directory fails with the OS error. Build report_files from the two results, keep the existing eprintlns for the daemon log, and add the object to the done json!. Leave write_to itself unchanged; plot/plot_level still use it.
• CLI plot ir (commands/plot.rs): collect_ir currently throws away the done frame ("done" => break), so return it too. Delete the cfg.report_dir block at the end of print_ir_report (~l.1027–1039, including the stderr note:). Add a function that prints the ux report / csv states on stdout from report_files. Call it right after print_ir_report in run_ir (~l.261), so it still follows gate. When the done frame is present without report_files, print report not reported by this daemon (the Emission max: precedent in commands/setup.rs). When there is no done frame (timeout/error, already reported), print nothing more. The not-configured line is built from REPORT_DIR_TOKEN: not saved — no report directory (ac setup report-dir <dir>).
• Drift test (in commands/plot.rs tests): comparing the constant with itself would pass by construction and could never fail. Instead, render the not-configured line with the real function, pull out the text between (ac and ), replace <dir> with a path, split on whitespace, and run it through crate::parse::parse. Assert CommandKind::Setup { report_dir: Some(Some(_)), .. }. It must fail if the note ever names reports-dir, report_dir <x> <y>, or a non-setup command.
• Daemon tests (it_protocol/setup.rs, modelled on setup_updates_snapshot_ring_and_spool_dir):
  • set, then read back with report_dir_status.writable == true;
  • clear, and report_dir_status is absent;
  • refuse a missing directory, a relative path and a plain file; in each case refused.reason is present and a combined update (output_channel + bad report_dir) leaves output_channel unchanged on disk;
  • set, then remove_dir, then read back writable: false;
  • set, restart the daemon on the same HOME, and the value is still there (criterion 4).
• it_protocol/plot_ir.rs: done.report_files in three cases: configured (both paths exist on disk); {"dir": null}; configured then the directory removed, where both entries carry error and the directory still does not exist afterwards.
• ac-cli/tests/it_plot_ir.rs: the existing Rig::start_with hand-seeds report_dir, which already covers criterion 5; keep it. Add: ac setup report-dir <dir> then plot ir prints a report line with an existing file; ac setup report-dir none then plot ir prints the not saved — no report directory line on stdout and writes no new file; directory removed then plot ir prints the write failed in form.
• Docs:
  • ZMQ.md → ### setup: request key, report_dir_status, the refused shape, the save-failure refusal.
  • ZMQ.md → ### plot_ir: the paragraph at ~l.1300 about the written pair gets report_files, plus "the directory is never created".
  • README.md → the ac setup block at ~l.83: one example line.

scope
scope-none. Unchanged from triage.

risks

• The probe file lands in the operator's report directory on every setup, including the read-only calls from generate: the name is dot-prefixed and removed at once. A leftover file after a failed removal is harmless and shows up plainly.
• A mount point that was unmounted but still exists as an empty directory passes both the probe and the capture write. Reports then go to the underlying filesystem. This is not detectable without comparing device IDs, so it is not fixed here and the error points one way only: files are saved, just not where the operator expects. The read-out shows the path, which is all this issue promises.
• Save-failure refusal changes behaviour for every setup key, not just report_dir: it is limited to non-empty updates, so the read-only callers are unaffected. It is covered by the spec's persistence criterion.
• This fix will not change ac plot / ac plot level. They still write via write_to (which creates missing directories) and print no persistence line (ux question 5). Follow-up for triage.
• This fix will not change other ac setup hints in other commands' notes (out of scope per triage).
• Old daemon, new CLI: the fallback line says so explicitly instead of guessing a path.

rig check
none. This is config plumbing and printed text. Every criterion is settled by the fake-audio integration tests above. The issue does not carry requires-rig.