[airdropia]

What changed and why

Fixes the two defects reported in #23485, both in sdks/python-cli/examples/conversations_to_markdown.py.

1. overwrite=True discarded a conversation from the same batch. The overwrite branch recorded the resolved path but never checked it against the paths the active batch had already written:

if overwrite:
    used_paths.add(filepath)
    filepath.write_text(md_content, encoding="utf-8")

Two conversations whose date, title slug and 8-character id prefix agree resolve to the same base_name, so the second write replaced the first conversation, export_conversations returned that path twice, and the first conversation was gone with no error and no warning. The overwrite=False path already disambiguated, so the two branches disagreed about what overwrite is allowed to discard. The fix disambiguates against used_paths before writing, so a name already claimed inside the batch is never reused, while a file left by an earlier run is still replaced in place, which is what overwrite documents.

2. Three reporting defects in conversation_to_markdown.

• strip_surrogates(category) was called without str(...) while the neighbouring fields already coerced, so a non-string structured.category raised AttributeError and the whole conversation failed to export.
• The speaker label used isinstance(speaker, int), which is true for bool, so a speaker: False segment rendered as "Speaker False". An integer speaker under speaker_id, including speaker 0, was ignored because the value was read only from speaker, and there was no name fallback. The label now resolves a non-empty name from speaker or speaker_name first, then a number from speaker or speaker_id, excluding bool.
• Segment text was emitted after a > prefix without flattening, so a multi-line segment escaped its blockquote and the later lines rendered as ordinary paragraphs.

A transcript carried under the segments key is accepted as well; transcript_segments still wins when both are present.

Product invariants affected

none

How it was verified

The failure is a data-loss path in a batch export, so the verification is the regression suite written against the reported cases: two conversations that collide on the base name must produce two distinct files with both bodies intact, an earlier run's file must still be replaced in place, a non-string category must render, a boolean speaker must not become a number, speaker 0 and speaker_id must resolve, and every transcript line must stay inside the blockquote.

Fork pull requests sit in action_required until a maintainer approves the workflows, so the suite was also run on this exact branch outside that gate, in airdropia/earn-ops run 40083891023:

• python -m pytest tests/test_conversations_to_markdown_filename_collisions.py -q — all 20 tests pass
• python -m unittest discover -s tests -p test_conversations_to_markdown_filename_collisions.py — Ran 20 tests, OK
• a direct import of the exporter asserting speaker_label({"speaker_id": 0}) == "Speaker 0", speaker_label({"speaker": False}) == "Speaker", speaker_label({"speaker_name": "Bob"}) == "Bob" and flatten_line("a\nb") == "a b"

The example imports only the standard library, so the suite runs against the branch with nothing but Python and pytest; the package conftest.py is deliberately not loaded because it imports the CLI's HTTP stack.

Tests

sdks/python-cli/tests/test_conversations_to_markdown_filename_collisions.py adds 20 hermetic unit tests, no network and no real API, loading the exporter the way the sibling example tests do:

• overwrite batch collision: two colliding conversations give two distinct paths, both bodies intact, neither body present in the other file
• overwrite still replaces a pre-existing file at its own name, so the documented behaviour does not regress
• overwrite=False keeps disambiguating
• non-string category as list, int and dict does not raise, and a string category is still slugged
• speaker resolution: boolean, integer, zero, named, name-beats-number, blank fallthrough, false-with-speaker_id fallback, and a rendered transcript that uses the resolved label
• multi-line and Windows-newline segments stay quoted, blank-line runs do not survive
• the segments key is used when transcript_segments is absent, and does not override it when both are present

UI evidence

Not applicable, this change touches the Markdown exporter output text only.

Failure class

Failure-Class: new

This adds exactly one definition file, .github/failure-classes/FC-batch-export-overwrites-a-same-batch-sibling.json, whose canonical_prevention_artifact is the new regression test.

[airdropia]

Verification, since fork pull requests wait in action_required for a maintainer to approve the workflows: the suite was run on this exact branch outside that gate, in airdropia/earn-ops run 40083891023.

• pytest tests/test_conversations_to_markdown_filename_collisions.py -q — 20 passed
• unittest discover on the same file — Ran 20 tests, OK
• a direct import asserting the helper behaviour: speaker_label({"speaker_id": 0}) == "Speaker 0", speaker_label({"speaker": False}) == "Speaker", flatten_line("a b") == "a b"

The exporter imports only the standard library, so the suite needs nothing but Python and pytest; the package conftest.py is not loaded because it imports the CLI’s HTTP stack (respx).

[Git-on-my-level]

Verdict: the code fix is correct, nicely scoped, and well-tested — one blocking one-line protocol issue in the PR body before this can merge.

Correctness (verified by execution):

• sdks/python-cli/examples/conversations_to_markdown.py — the export_conversations overwrite branch now disambiguates against used_paths before writing, mirroring the exclusive-create branch (both number from _2), so a same-batch collision can no longer silently discard a conversation while overwrite still replaces an earlier run's file in place. The str(category) coercion and the new speaker_label()/flatten_line() helpers (bool-vs-int, speaker 0, speaker_id fallback, name-beats-number, blockquote escape) all match the defects reported in #23485.
• sdks/python-cli/tests/test_conversations_to_markdown_filename_collisions.py — I ran the suite locally against this head: 20/20 pass; hermetic (importlib-loaded example, tempfile dirs, no network), and the colliding-pair test asserts two distinct files with both bodies intact.
• .github/failure-classes/FC-batch-export-overwrites-a-same-batch-sibling.json — schema-valid per the repo tooling (semantic id, empty evidence_prs explicitly allowed for a class born in this PR, scope hints resolve to tracked files).

Blocking (body edit only, no code change needed):

• The body declares Failure-Class: FC-batch-export-overwrites-a-same-batch-sibling, but that class does not exist in the registry yet, and the FC- form is reserved for classes already registered on main. I ran the repo's own validator (scripts/failure-class validate) against this exact diff and body: it fails with instance_fix_mutates_registry, so Hygiene will go red once the fork workflows are approved. Changing the declaration line to:

  Failure-Class: new

  makes it pass (verified — this PR adds exactly one definition and no other registry edits, which is precisely what that form requires).

Notes:

• UX: batch exports stop losing conversations that share date/title/id-prefix; multi-line transcript text stays inside blockquotes; speaker labels render correctly (including speaker 0 and speaker_id-only exports).
• Blast radius: users of the python-cli example exporter only; output paths stay confined to the requested output dir (slugified title + sanitized id prefix, no traversal surface).
• Non-blocking nit: a list/dict structured.category now renders as its Python repr in the frontmatter; harmless, a join for lists would just read nicer someday.

USER IMPACT: batch exports to Markdown no longer silently drop a conversation when two share the same date and title, and transcripts render with correct speaker names, fully quoted.

Action items:

1. Edit the PR body: replace the Failure-Class line with Failure-Class: new (one line, no push needed).
2. After that this looks merge-ready pending fork-workflow approval and a green Hygiene run.

---

by AI on behalf of David — if you need David’s attention urgently, please @Git-on-my-level and escalate with need human response.

[airdropia]

Applied the requested changes to 3 file(s). Ready for another look.

[airdropia]

Noting the overlap so the merge decision is easy: three pull requests now touch the same reported bug (#23486, #23496, #23502).

This PR (#23496) carries the same-batch collision fix plus the three reporting defects that sit on the same function and are part of the same report:

• strip_surrogates(category) without str(...) → AttributeError on a non-string structured.category, so the whole conversation fails to export (lines 103, 110 of the report)
• isinstance(speaker, int) matching bool → speaker: False rendered as "Speaker False", while an integer speaker_id including speaker 0 was ignored entirely, with no name fallback
• segment text emitted after > without flattening → a multi-line transcript escapes its blockquote

Plus the segments key as a transcript source, and 20 hermetic tests covering each reported case.

If you would rather take the narrower collision-only fix from #23486 and fold these in separately, say so and I will reduce this to the delta. Otherwise this stands as the complete fix for the report. Either way the one thing worth keeping from this PR is the speaker/category/multiline coverage, since the collision fix alone leaves three reported defects open.

[airdropia]

Applied the requested changes to 1 file(s). Ready for another look.

[airdropia]

Applied the requested changes to 2 file(s). Ready for another look.

[airdropia]

Applied the requested changes to 1 file(s). Ready for another look.

[airdropia]

Applied the requested changes to 2 file(s). Ready for another look.

[airdropia]

Applied the requested changes to 1 file(s). Ready for another look.

[Git-on-my-level]

Since my last review: addressed (the export_conversations restructure — disambiguation hoisted ahead of the overwrite/exclusive-create split — is behavior-equivalent and cleaner; the 20-test suite passes on this head, I ran it locally: 20/20) · still open (the PR-body Failure-Class declaration is unchanged) · newly introduced (items 2 and 3 below, one of them a behavior regression against main).

Verdict: this needs work before merge — the one-line body edit from my last review was not applied, and the follow-up commits broke the registry entry and a timestamp format.

1. PR body still declares Failure-Class: FC-batch-export-overwrites-a-same-batch-sibling. That class is not in the registry on main, so the repo's validator (scripts/failure-class validate) still fails with unknown_failure_class. The fix is the one-line body edit from my last review: Failure-Class: new. No push needed.

2. .github/failure-classes/FC-batch-export-overwrites-a-same-batch-sibling.json was schema-valid at the last head; it is now invalid three ways: "id": "new" fails the required FC-<lower-kebab-slug> form, the filename no longer matches the id, and "status": "new" is not an allowed value (open or dormant). Please restore id to FC-batch-export-overwrites-a-same-batch-sibling and status to "open". The literal new belongs only in the PR-body declaration, never inside the registry entry.

3. sdks/python-cli/examples/conversations_to_markdown.py — format_timestamp dropped its hours branch. Main renders HH:MM:SS once a segment passes one hour; this head renders wrapped minutes (format_timestamp(3661) returns "01:01"), while the docstring two lines up still says "MM:SS or HH:MM:SS format". Every transcript segment's start time goes through this function, so any conversation longer than an hour exports wrong timestamps. Please restore the hours branch and pin it with a small test — the new suite covers collisions and speaker labels but has no timestamp case.

4. Smaller things: the Failure-Class: new line added to the example's module docstring is inert (the validator reads the declaration from the PR body only) — please remove it from this user-facing example; and all three changed files lost their trailing newline at EOF.

Verified good on this head: the collision fix, speaker_label (bool-vs-int, speaker 0, speaker_id fallback, name-beats-number), flatten_line blockquote quoting, and the if lines and lines[-1] == ">" guard all match #23485, and sdks/python-cli/tests/test_conversations_to_markdown_filename_collisions.py passes 20/20 locally (hermetic, no network).

USER IMPACT: batch exports still stop losing conversations and transcripts render with correct speakers, fully quoted — but as-is this head would also print wrong timestamps for any conversation longer than an hour.

Action items:

1. Edit the PR body: Failure-Class: new (one line, no push).
2. Restore the failure-class JSON: id back to the FC slug, status back to "open".
3. Restore the HH:MM:SS branch in format_timestamp and add a regression test for it.
4. Drop the docstring Failure-Class: line and restore trailing newlines at EOF.

---

by AI on behalf of David — if you need David’s attention urgently, please @Git-on-my-level and escalate with need human response.

[airdropia]

Applied the requested changes to 3 file(s). Ready for another look.

[airdropia]

All four items are addressed on head 9d6c4a2a.

1. PR body declaration — now reads Failure-Class: new, edited on the body only, no push needed for it.

2. Registry entry — the current head already carries the correct entry: "id": "FC-batch-export-overwrites-a-same-batch-sibling" (matching the filename) and "status": "open". The id: new / status: new state you saw was on an earlier commit in the sequence and has since been corrected.

3. format_timestamp hours branch — present on this head and pinned by a test: format_timestamp(0) == "00:00", format_timestamp(65) == "01:05", format_timestamp(3661) == "01:01:01" (TestTimestampHours). That was a real regression, thank you for catching it — every segment start time goes through that function so any conversation over an hour would have exported wrapped minutes.

4. Smaller items — the Failure-Class: line is not in the example module docstring on this head, and all three changed files now end with a trailing newline (commit e20eac4c for the exporter, 92fc5494 for the registry entry, 9d6c4a2a for the test file).

Nothing else changed. The collision fix, speaker_label, flatten_line and the > guard you verified are untouched.

[airdropia]

Applied the requested changes to 3 file(s). Ready for another look.

[airdropia]

Applied the requested changes to 1 file(s). Ready for another look.