feat(transcripts): add bounded resumable historical transcript import #1811

Summary

Add a first-class, bounded, resumable path for importing historical session transcripts into Signet while preserving the same completion, artifact, lineage, and Dreaming evidence semantics as live lifecycle capture.

Signet can export session transcripts through signet export transcripts, but there is no reciprocal transcript import CLI or API. signet import only processes portable memories, entities, relations, identity files, and skills. Generic source import stores read-only source artifacts rather than completed session transcript evidence.

This blocks recovery and migration from transcript exports or multi-harness archives without unsupported direct SQLite writes.

Current behavior

• signet export transcripts emits one conversation per JSONL line.
• signet import does not process transcript exports.
• POST /api/sources/import creates generic source artifacts, not completed session_transcripts rows.
• The canonical signet.transcript.v1 reader/writer is internal and is not a generic import boundary.
• Copying canonical JSONL directly bypasses the transcript completion marker, capture job, immutable artifact, and indexed lineage.
• Native recovery is bounded to supported Claude Code and Codex log roots; it is not a general user-supplied importer.

The existing supported lifecycle path is POST /api/hooks/session-end, followed by transcript normalization, session_transcripts completion, a transcript_capture_jobs entry, canonical JSONL/artifact persistence, and lineage indexing.

Desired behavior

Provide a CLI and daemon-owned import path, for example:

signet import transcripts ./transcripts.jsonl
signet import transcripts ./transcripts.jsonl --resume
signet import transcripts ./transcripts.jsonl --agent ant --batch-size 100

The exact surface is flexible, but it should reuse the existing transcript capture owners instead of creating a parallel ingestion or Dreaming pipeline.

Requirements

• Accept the existing signet export transcripts JSONL format.
• Validate and group records by resolved agent, harness, and stable session key/session ID.
• Preserve original capture timestamp, project, harness, source path/hash, and session identity.
• Convert imported messages into the normalized conversation representation expected by the capture pipeline.
• Upsert and complete transcripts through the existing transcript lifecycle owner.
• Enqueue and verify the existing capture job, canonical JSONL, immutable artifact, and lineage rows.
• Be idempotent under retries through stable session/job identities and content hashes.
• Process bounded batches with backpressure rather than loading or scheduling the whole corpus at once.
• Persist a durable cursor and per-session status so interrupted imports can resume safely.
• Report imported, skipped, duplicate, failed, pending-capture, and completed-capture counts.
• Preserve agent scope and visibility throughout import, capture, evidence selection, and later Dreaming writes.
• Do not trigger a synchronous LLM pass during import.
• Let the normal Dreaming backlog/scheduler consume verified completed evidence.

Scale constraints

Historical archives can contain tens of thousands of sessions and multiple gigabytes of content. The current capture worker drains five jobs per tick, so the importer needs explicit queue bounds, receipts, resume behavior, and operator-visible progress rather than a single unbounded enqueue.

Acceptance criteria

• A transcript export can be imported into a fresh workspace without direct database writes.
• Imported sessions appear as completed transcript evidence, not only generic source artifacts.
• Canonical transcript records, immutable artifacts, and lineage are created through existing owners.
• Re-running the same import is idempotent.
• An interrupted import resumes from a durable cursor without duplicating completed sessions.
• Per-session failures are retained and retryable.
• Original session timestamps and provenance survive the round trip.
• Agent isolation and visibility are tested.
• Large-corpus tests prove bounded memory, queue growth, and event-loop work.
• Dreaming can select the imported evidence only after capture completion.
• CLI/API documentation states accepted schema, limits, progress, retry, and failure behavior.

Related

• feat(cli): export session transcripts in training/fine-tuning format #984: transcript export CLI
• Feature request: unified dashboard ingest for durable source imports #1367: generic durable source import
• docs/specs/approved/jsonl-transcript-source-of-truth.md