fix(import): link Workflow-tool inner agents on CLI rescan (offline/headless runs)

[omar-merhebi]

Summary

A Claude Code Workflow-tool run (dynamic workflow / fleet of sub-agents) emits no hooks, so when it runs where hook events never reach the dashboard server — a headless claude -p run, a CI job, or an HPC/cluster compute node — its per-run journal is never ingested live. The offline CLI import path (ccam import rescan / ccam import path) never closed that gap, so a rescan imported the inner-agent transcripts but left them orphaned from their run (workflow_run_id = NULL), and the workflow kept showing 1 agent instead of the real N. This wires the existing workflow-journal ingest into the CLI import path so a rescan links them, mirroring what the server already does.

Changes

• scripts/import-history.js: after each import batch, importAllSessions (backs ccam import rescan / POST /api/import/rescan) and importFromDirectory (backs ccam import path / /api/import/scan-path + /upload) now call the existing ingestWorkflowsForSession per imported session — via a small shared ingestWorkflowsForBatch helper. It runs outside the better-sqlite3 transaction (the ingest is async) at the exact spot the durable-snapshot pass already runs.
• The ingest is reused as-is, not reimplemented (server/lib/workflow-ingest.js), and is idempotent: it converges on the same ${sessionId}-jsonl-<agentId> rows and returns early for sessions with no workflow artifacts (cheap on a rescan of an unchanged tree). Lazy-required to respect the existing import-history ⇆ workflow-ingest cycle avoidance.
• server/__tests__/import-workflow-link.test.js: new regression test — builds a fixture session tree with a subagents/workflows/<runId>/journal.jsonl + a few agent-*.jsonl, runs the CLI import path (not the server), and asserts every inner agent ends up with workflow_run_id = <runId>, that workflows.agent_count reflects the fleet, and that re-import is idempotent (no duplicate rows).
• Docs: ARCHITECTURE.md (adds the offline-CLI-import trigger to the Workflow-Tool Run Ingestion trigger list + the import-history.js module note) and server/README.md (import-history row).

Root cause: workflow_run_id is only ever set by the setAgentWorkflow statement, whose sole callers live in server/lib/workflow-ingest.js and are invoked only from the server (startup ingest, poll loop, live hooks). scripts/import-history.js had zero references to the workflow ingest, so the offline path could never link the fleet. Related to #167 (server-side journal ingest) — this extends the same fix to the offline import path it didn't cover.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• Documentation update

How to Test

Reproduced against real data. Point DASHBOARD_DB_PATH at a copy of a dashboard DB so nothing live is mutated.

1. Find a completed workflow run whose inner agents were never ingested (offline). On a real 17-inner-agent run:

   sqlite3 copy.db "SELECT count(*) FROM agents WHERE workflow_run_id='wf_99d1a80e-200';"   -- 1  (bug)
   sqlite3 copy.db "SELECT agent_count,status,source FROM workflows WHERE run_id='wf_99d1a80e-200';"  -- 1|running|live
   

2. Run the patched import over that session's tree (importAllSessions / importFromDirectory) against the copy DB.
3. Re-check:

   sqlite3 copy.db "SELECT count(*) FROM agents WHERE workflow_run_id='wf_99d1a80e-200';"   -- 17  ✅
   sqlite3 copy.db "SELECT agent_count,status,source FROM workflows WHERE run_id='wf_99d1a80e-200';"  -- 17|killed|journal
   

   A second run is a no-op (17 inner + 1 main agent, no duplicates).
4. npm run test:server — 655 pass (incl. the new regression test); npm run test:client — 261 pass.

Before → after (real run wf_99d1a80e-200): agents linked 1 → 17; workflows.agent_count 1 → 17.

Checklist

• I have read the contributing guidelines
• I have signed the CLA (the 🖋️ CLA Assistant bot will prompt me on my first PR)
• My code follows the project's coding standards
• I have added/updated tests that prove my fix or feature works
• All new and existing tests pass (npm test)
• Code is formatted (npm run format:check)
• I have updated documentation where necessary

🤖 Generated with Claude Code

[github-actions]

✅ All contributors have signed the CLA. Thank you!
_{Posted by the CLA Assistant Lite bot.}

[omar-merhebi]

I have read the CLA Document and I hereby sign the CLA

[gemini-code-assist]

Code Review

This pull request updates the offline CLI import path to link Workflow-tool inner agents to their corresponding runs. Specifically, it modifies scripts/import-history.js to call ingestWorkflowsForSession asynchronously and outside the SQLite transaction during both batch rescans (importAllSessions) and directory imports (importFromDirectory). This ensures that headless, CI, or cluster runs that do not emit live hooks are properly linked instead of being left orphaned. The PR also updates the documentation in ARCHITECTURE.md and server/README.md to document this new ingestion trigger, and introduces a comprehensive regression test suite in server/__tests__/import-workflow-link.test.js. No reviewer comments were provided, so there is no feedback to evaluate.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.