edsger 0.62.0 → 0.63.0

package/dist/commands/quality-benchmark/index.d.ts

@@ -26,6 +26,8 @@
 export interface QualityBenchmarkCliOptions {
     /** Optional local-checkout override; when absent the CLI clones the product's repo. */
     repo?: string;
+    /** Benchmark a specific linked repository (id) instead of the product's primary repo. */
+    repoId?: string;
     branch?: string;
     pkgManager?: string;
     install?: boolean;

package/dist/commands/quality-benchmark/index.js

@@ -30,12 +30,15 @@ import { callMcpEndpoint } from '../../api/mcp-client.js';
 import { fetchProductBasics } from '../../phases/find-shared/mcp.js';
 import { runQualityBenchmark, } from '../../phases/quality-benchmark/index.js';
 import { prepareQualityWorkspace } from '../../phases/quality-benchmark/workspace.js';
+import { getSupabase } from '../../supabase/client.js';
 import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
 export async function runQualityBenchmarkCli(productId, options) {
     const installEnabled = options.install !== false;
     logInfo(`Starting quality benchmark for product ${productId}`);
     let repoRoot;
     let resolvedBranch;
+    // Recorded on the report so it's scoped to the repo that was benchmarked.
+    let repositoryId = options.repoId ?? null;
     if (options.repo) {
         repoRoot = resolve(options.repo);
         resolvedBranch = options.branch;
@@ -48,9 +51,27 @@ export async function runQualityBenchmarkCli(productId, options) {
                 'GitHub is not configured for this product. Connect a repo in product settings.'}`);
             process.exit(1);
         }
+        // Default to the product's primary repo; if a specific repo id was passed,
+        // resolve its owner/repo so we benchmark that codebase instead.
+        let { owner } = gh;
+        let { repo } = gh;
+        if (options.repoId) {
+            const fullName = await resolveRepositoryFullName(options.repoId);
+            if (fullName) {
+                const [o, r] = fullName.split('/');
+                if (o && r) {
+                    owner = o;
+                    repo = r;
+                }
+            }
+            else {
+                logWarning(`repo-id ${options.repoId} not found; falling back to the product's primary repo.`);
+                repositoryId = null;
+            }
+        }
         const ws = prepareQualityWorkspace({
-            owner: gh.owner,
-            repo: gh.repo,
+            owner,
+            repo,
             token: gh.token,
             verbose: options.verbose,
         });
@@ -116,6 +137,7 @@ export async function runQualityBenchmarkCli(productId, options) {
         try {
             const saved = (await callMcpEndpoint('quality_reports/save', {
                 product_id: productId,
+                repository_id: repositoryId,
                 commit_sha: outcome.commitSha,
                 rubric_version: outcome.report.rubric_version,
                 branch: resolvedBranch ?? null,
@@ -152,3 +174,12 @@ export async function runQualityBenchmarkCli(productId, options) {
         logInfo(outcome.report.executive_summary);
     }
 }
+/** Resolve a repository id to its "owner/repo" full name (RLS-scoped). */
+async function resolveRepositoryFullName(repositoryId) {
+    const { data } = await getSupabase()
+        .from('repositories')
+        .select('full_name')
+        .eq('id', repositoryId)
+        .maybeSingle();
+    return (data)?.full_name ?? null;
+}

package/dist/commands/session-turn/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Marker emitted on stdout carrying the SDK session id, so the desktop can
+ * persist it on the channel and pass it back via --resume next turn. Kept on
+ * its own line and free of logger formatting so it parses cleanly.
+ */
+export declare const SESSION_ID_MARKER = "__EDSGER_SESSION_ID__=";
+export interface SessionTurnCliOptions {
+    channelId: string;
+    productId: string;
+    repositoryIds?: string[];
+    /** SDK session id from a previous turn, to resume the same conversation. */
+    resumeSessionId?: string;
+    verbose?: boolean;
+}
+export declare function runSessionTurnCommand(options: SessionTurnCliOptions): Promise<void>;

package/dist/commands/session-turn/index.js

@@ -0,0 +1,177 @@
+/**
+ * Marker emitted on stdout carrying the SDK session id, so the desktop can
+ * persist it on the channel and pass it back via --resume next turn. Kept on
+ * its own line and free of logger formatting so it parses cleanly.
+ */
+export const SESSION_ID_MARKER = '__EDSGER_SESSION_ID__=';
+/**
+ * `edsger session-turn <channelId>` — run one conversational agent turn for a
+ * chat session (an ai_assistant channel bound to a product).
+ *
+ * Spawned by the desktop app when the user sends a message in a session. It
+ * loads the channel's pending human messages, runs a single Claude Agent SDK
+ * turn with the full session toolbelt (createSessionMcpServer — query/action/
+ * engineering/cli + conversational + git/PR tools), then posts the reply back
+ * to the channel and marks the messages processed. The agent decides what to
+ * do (answer, generate stories/test cases, launch cli_* analyses, open PRs);
+ * there is no fixed pipeline.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { createSessionMcpServer } from 'edsger-tools';
+import { callMcpEndpoint } from '../../api/mcp-client.js';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { getToolDeps } from '../../tools/bootstrap.js';
+import { logError, logInfo, logSuccess } from '../../utils/logger.js';
+const MAX_TURNS = 40;
+function buildSystemPrompt(opts) {
+    const { channelId, productId, repositoryIds } = opts;
+    const repoLine = repositoryIds.length > 0
+        ? repositoryIds.join(', ')
+        : '(none provided — call list_session_repositories to discover them)';
+    return `You are an engineering agent working in a chat session with a user, like a pair-programming assistant.
+
+## This session
+- Session channel_id: ${channelId}
+- Product product_id: ${productId}
+- In-scope repository_ids: ${repoLine}
+
+## How you work
+You are an orchestrator, not a fixed pipeline. Do only what the user asked:
+- A question or status check → just answer (you can read code with Read/Grep/Glob).
+- "Write the test cases" / "add user stories" → use create_user_story / create_test_case / create_test_report. No code.
+- "Check quality" / "find bugs" → launch the matching cli_* tool (asynchronous: it returns a run handle, results appear later; report progress with get_cli_run).
+
+## Implementing code changes (you hand this off — you do NOT write code or open PRs yourself)
+When the user wants code changes:
+1. Optionally list_session_repositories to understand the codebase scope.
+2. create_issue with a clear, implementable description (the product may span multiple repos — say which).
+3. Mark it ready for AI with update_issue_status so the engineering pipeline picks it up, clones the repos, implements the change, and opens the pull request(s).
+4. Tell the user you filed the issue and that the pipeline will produce the PR(s); offer to check status later.
+Only create issues/tasks when the work warrants tracking — a pure question or quality check should not leave an issue behind.
+
+## Talking to the user
+- send_chat_message for explanations, summaries, clarifying questions (channel_id "${channelId}").
+- provide_options when there are 2-4 clear next steps.
+- Be concise; report what you did and what you need.`;
+}
+function buildUserPrompt(messages) {
+    const conversation = messages
+        .map((m) => {
+        const who = m.sender_agent_id
+            ? `[Agent: ${m.sender_name || 'Unknown'}]`
+            : `[${m.sender_name || 'User'}]`;
+        return `${who}: ${m.content}`;
+    })
+        .join('\n\n');
+    return `New message(s) in this session:\n\n${conversation}\n\nDecide what to do and act. Keep the user informed via send_chat_message.`;
+}
+export async function runSessionTurnCommand(options) {
+    const { channelId, productId, repositoryIds = [], resumeSessionId, verbose = false, } = options;
+    // Emit the SDK session id so the desktop can persist it for the next turn.
+    const emitSessionId = (id) => {
+        if (id) {
+            process.stdout.write(`\n${SESSION_ID_MARKER}${id}\n`);
+        }
+    };
+    // 1. Load the pending human messages that triggered this turn.
+    const pendingResult = (await callMcpEndpoint('chat/messages/pending', {
+        channel_id: channelId,
+    }));
+    const messages = pendingResult.messages ?? [];
+    if (messages.length === 0) {
+        logInfo('No pending messages for this session — nothing to do.');
+        return;
+    }
+    logInfo(`Processing ${messages.length} message(s) for session ${channelId}`);
+    // 2. Build the session toolbelt + prompts.
+    const deps = getToolDeps({
+        verbose,
+        context: { productId, channelId, repositoryIds },
+    });
+    const sessionServer = createSessionMcpServer(deps);
+    const systemPrompt = buildSystemPrompt({
+        channelId,
+        productId,
+        repositoryIds,
+    });
+    const userPrompt = buildUserPrompt(messages);
+    // 3. Run one SDK turn. Resume the prior SDK session when we have its id so
+    //    the conversation (and prompt cache) carries across turns.
+    let finalResponse = '';
+    let sdkSessionId = resumeSessionId ?? '';
+    try {
+        for await (const message of query({
+            prompt: userPrompt,
+            options: {
+                agent: 'session-agent',
+                agents: {
+                    'session-agent': {
+                        description: 'Conversational engineering agent for a session',
+                        prompt: systemPrompt,
+                        maxTurns: MAX_TURNS,
+                        mcpServers: ['edsger-session'],
+                        disallowedTools: ['Edit', 'Write', 'Bash', 'NotebookEdit', 'Agent'],
+                    },
+                },
+                mcpServers: { 'edsger-session': sessionServer },
+                tools: ['Read', 'Grep', 'Glob'],
+                permissionMode: 'bypassPermissions',
+                allowDangerouslySkipPermissions: true,
+                model: DEFAULT_MODEL,
+                ...(resumeSessionId ? { resume: resumeSessionId } : {}),
+            },
+        })) {
+            const msg = message;
+            // The system/init and result messages carry the (possibly new) session
+            // id — keep the latest so we persist what the next turn should resume.
+            if (msg.session_id) {
+                sdkSessionId = msg.session_id;
+            }
+            if (verbose && msg.type === 'assistant') {
+                logInfo('· agent step');
+            }
+            if (msg.type === 'result') {
+                finalResponse = msg.result || '';
+                break;
+            }
+        }
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        logError(`Session turn failed: ${reason}`);
+        await callMcpEndpoint('chat/messages/send_ai', {
+            channel_id: channelId,
+            content: `I hit an error processing that: ${reason}`,
+            message_type: 'text',
+            metadata: {},
+        }).catch(() => undefined);
+        emitSessionId(sdkSessionId);
+        await markProcessed(messages);
+        return;
+    }
+    // 4. Post the final reply (the agent may also have posted via
+    //    send_chat_message during the turn; this carries the closing summary).
+    const reply = finalResponse.trim();
+    if (reply) {
+        await callMcpEndpoint('chat/messages/send_ai', {
+            channel_id: channelId,
+            content: reply,
+            message_type: 'text',
+            metadata: {},
+        }).catch((e) => {
+            logError(`Failed to post reply: ${e instanceof Error ? e.message : String(e)}`);
+        });
+    }
+    // 5. Mark the triggering messages processed so they aren't re-run.
+    await markProcessed(messages);
+    // 6. Emit the SDK session id so the desktop persists it for the next turn.
+    emitSessionId(sdkSessionId);
+    logSuccess('Session turn complete.');
+}
+async function markProcessed(messages) {
+    for (const m of messages) {
+        await callMcpEndpoint('chat/messages/mark_processed', {
+            message_id: m.id,
+        }).catch(() => undefined);
+    }
+}

package/dist/commands/sync-org-repos/index.d.ts

@@ -2,7 +2,7 @@
  * CLI command: `edsger sync-org-repos <teamId>`
  *
  * Reads the team's configured github_org, fetches all repos from that org
- * via the local `gh` CLI, and creates a product for each repo not yet linked.
+ * via the local `gh` CLI, and upserts a repositories row for each repo.
  */
 export interface SyncOrgReposCliOptions {
     verbose?: boolean;

package/dist/commands/sync-org-repos/index.js

@@ -2,7 +2,7 @@
  * CLI command: `edsger sync-org-repos <teamId>`
  *
  * Reads the team's configured github_org, fetches all repos from that org
- * via the local `gh` CLI, and creates a product for each repo not yet linked.
+ * via the local `gh` CLI, and upserts a repositories row for each repo.
  */
 import { getSupabase, hasSupabaseSession } from '../../supabase/client.js';
 import { syncOrgRepos } from '../../phases/sync-org-repos/index.js';
@@ -50,7 +50,7 @@ export async function runSyncOrgRepos(teamId, options = {}) {
     });
     if (result.status === 'success') {
         logSuccess(result.message);
-        logInfo(`Total: ${result.total} · created: ${result.created} · skipped: ${result.skipped}`);
+        logInfo(`Total: ${result.total} · created: ${result.created} · updated: ${result.skipped}`);
     }
     else {
         logError(result.message);

package/dist/index.js

@@ -32,13 +32,14 @@ import { runRefactor } from './commands/refactor/refactor.js';
 import { runReleaseSyncCommand } from './commands/release-sync/index.js';
 import { runRunSheetCommand } from './commands/run-sheet/index.js';
 import { runScreenFlow } from './commands/screen-flow/index.js';
+import { runSessionTurnCommand } from './commands/session-turn/index.js';
 import { runSmokeTestCommand } from './commands/smoke-test/index.js';
-import { runSyncGithubIssues } from './commands/sync-github-issues/index.js';
-import { runSyncOrgRepos } from './commands/sync-org-repos/index.js';
 import { runSyncAws } from './commands/sync-aws/index.js';
 import { runSyncDatadog } from './commands/sync-datadog/index.js';
-import { runSyncTerraform } from './commands/sync-terraform/index.js';
+import { runSyncGithubIssues } from './commands/sync-github-issues/index.js';
+import { runSyncOrgRepos } from './commands/sync-org-repos/index.js';
 import { runSyncSentryIssues } from './commands/sync-sentry-issues/index.js';
+import { runSyncTerraform } from './commands/sync-terraform/index.js';
 import { runTaskWorker } from './commands/task-worker/index.js';
 import { runTechnicalDesignCommand } from './commands/technical-design/index.js';
 import { runTestCasesAnalysisCommand } from './commands/test-cases-analysis/index.js';
@@ -432,6 +433,34 @@ program
     }
 });
 // ============================================================
+// Subcommand: edsger session-turn <channelId>
+// ============================================================
+program
+    .command('session-turn <channelId>')
+    .description('Run one conversational agent turn for a chat session (ai_assistant channel)')
+    .requiredOption('--product <productId>', 'Product the session is bound to')
+    .option('--repos <ids>', 'Comma-separated repository IDs the agent may touch', '')
+    .option('--resume <sessionId>', 'SDK session id from a previous turn to resume the same conversation')
+    .option('-v, --verbose', 'Verbose output')
+    .action(async (channelId, opts) => {
+    try {
+        await runSessionTurnCommand({
+            channelId,
+            productId: opts.product,
+            repositoryIds: (opts.repos ?? '')
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean),
+            resumeSessionId: opts.resume,
+            verbose: opts.verbose,
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+// ============================================================
 // Subcommand: edsger user-stories-analysis <issueId>
 // ============================================================
 program
@@ -569,6 +598,7 @@ program
     .command('quality-benchmark <productId>')
     .description("Run an industrial-grade code quality benchmark against the product's GitHub repo")
     .option('--repo <path>', "Override the auto-clone with a local checkout (default: clone the product's repo into ~/edsger/quality-<owner>-<repo>)")
+    .option('--repo-id <id>', "Benchmark a specific linked repository (id) instead of the product's primary repo")
     .option('--branch <name>', 'Override the detected default branch on the report envelope')
     .option('--pkg-manager <name>', 'npm | pnpm | yarn (auto-detected if absent)')
     .option('--no-install', 'Refuse to install missing tools; mark them unmeasured')
@@ -608,7 +638,7 @@ program
     .command('sync-org-repos <teamId>')
     .description("Sync a GitHub org's repos as products under a team. Uses the local gh CLI.")
     .option('-v, --verbose', 'Verbose output')
-    .option('--org <name>', 'GitHub org name (defaults to the team\'s configured github_org)')
+    .option('--org <name>', "GitHub org name (defaults to the team's configured github_org)")
     .action(async (teamId, opts) => {
     try {
         await runSyncOrgRepos(teamId, opts);

package/dist/phases/data-flow/index.js

@@ -10,12 +10,12 @@
  * domain.
  */
 import { query } from '@anthropic-ai/claude-agent-sdk';
-import { getGitHubConfigByProduct } from '../../api/github.js';
 import { DEFAULT_MODEL } from '../../constants.js';
 import { getSupabase } from '../../supabase/client.js';
 import { logError, logInfo, logSuccess, logWarning } from '../../utils/logger.js';
-import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, } from '../../workspace/workspace-manager.js';
+import { cleanupIssueRepo } from '../../workspace/workspace-manager.js';
 import { fetchProductBasics } from '../find-shared/mcp.js';
+import { cloneFlowRepos, describeRepoScope } from '../flow-shared/clone-repos.js';
 import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
 import { createDataFlowCaptureState, createDataFlowMcpServer, validateConsistency, } from './mcp-server.js';
 import { createDataFlowSystemPrompt, createDataFlowUserPrompt, } from './prompts.js';
@@ -31,31 +31,30 @@ export async function runDataFlowPhase(options) {
     logInfo(`Starting data-flow generation for product ${productId}`);
     const supabase = getSupabase();
     await markFlowRunning(supabase, flowId);
-    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
-    if (!githubConfig.configured ||
-        !githubConfig.token ||
-        !githubConfig.owner ||
-        !githubConfig.repo) {
-        const msg = githubConfig.message ||
-            'GitHub repository not configured for this product. Connect a repo first.';
-        await markFlowFailed(supabase, flowId, msg);
-        return { status: 'error', message: msg };
+    const repositoryIds = await getFlowRepositoryIds(supabase, flowId);
+    const cloneResult = await cloneFlowRepos({
+        productId,
+        repositoryIds,
+        workspaceKey: WORKSPACE_KEY,
+        verbose,
+    });
+    if (!cloneResult.ok) {
+        await markFlowFailed(supabase, flowId, cloneResult.message);
+        return { status: 'error', message: cloneResult.message };
     }
-    let repoPath;
+    const { projectDir, cleanupDir, repos } = cloneResult;
     let succeeded = false;
     try {
-        const workspaceRoot = ensureWorkspaceDir();
-        const repoKey = `${WORKSPACE_KEY}-${productId}`;
-        ({ repoPath } = cloneIssueRepo(workspaceRoot, repoKey, githubConfig.owner, githubConfig.repo, githubConfig.token));
         const product = await fetchProductBasics(productId);
         const systemPrompt = await createDataFlowSystemPrompt({
-            projectDir: repoPath,
+            projectDir,
             hasCodebase: true,
         });
+        const repoScope = describeRepoScope(repos);
         const userPrompt = createDataFlowUserPrompt({
             productName: product.name,
             productDescription: product.description,
-            guidance,
+            guidance: [guidance, repoScope].filter(Boolean).join('\n\n') || undefined,
         });
         logInfo('Running Claude data-flow extraction...');
         const captureState = createDataFlowCaptureState();
@@ -77,7 +76,7 @@ export async function runDataFlowPhase(options) {
                 model: DEFAULT_MODEL,
                 maxTurns: MAX_TURNS,
                 permissionMode: 'bypassPermissions',
-                cwd: repoPath,
+                cwd: projectDir,
                 mcpServers: {
                     'data-flow': mcpServer,
                 },
@@ -115,10 +114,19 @@ export async function runDataFlowPhase(options) {
     }
     finally {
         if (succeeded) {
-            cleanupIssueRepo(repoPath);
+            cleanupIssueRepo(cleanupDir);
         }
     }
 }
+/** Read the ordered repo set a flow was scoped to (may be empty). */
+async function getFlowRepositoryIds(supabase, flowId) {
+    const { data } = await supabase
+        .from('flows')
+        .select('repository_ids')
+        .eq('id', flowId)
+        .single();
+    return (data?.repository_ids ?? []).filter(Boolean);
+}
 function processSdkMessage(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 message, assistantBuffer, captureState, verbose) {

package/dist/phases/flow-shared/clone-repos.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared multi-repo cloning for flow generation (screen-flow / data-flow).
+ *
+ * A flow can be scoped to one or several repositories (the user picks them in
+ * the desktop UI; the chosen set is stored on `flows.repository_ids`). This
+ * helper resolves that set, clones each repo into a per-flow parent workspace
+ * directory, and returns the directory the agent should run against:
+ *   - single repo  → the repo's own clone dir
+ *   - many repos   → the parent dir holding every clone as a subdirectory,
+ *                    so the agent can explore them all and produce one unified
+ *                    flow.
+ *
+ * Falls back to the product's primary repo when `repository_ids` is empty
+ * (older flows, or single-repo products).
+ */
+export interface ClonedRepo {
+    fullName: string;
+    owner: string;
+    repo: string;
+    dir: string;
+}
+export interface CloneFlowReposSuccess {
+    ok: true;
+    /** Directory to point the agent at (parent dir for multi-repo). */
+    projectDir: string;
+    /** Directory to clean up afterwards (always the per-flow parent). */
+    cleanupDir: string;
+    repos: ClonedRepo[];
+}
+export interface CloneFlowReposFailure {
+    ok: false;
+    message: string;
+}
+export declare function cloneFlowRepos(opts: {
+    productId: string;
+    repositoryIds: string[];
+    workspaceKey: string;
+    verbose?: boolean;
+}): Promise<CloneFlowReposSuccess | CloneFlowReposFailure>;
+/**
+ * Build a short note describing the repo scope, appended to the agent's user
+ * prompt so it knows whether to map one repo or unify several.
+ */
+export declare function describeRepoScope(repos: ClonedRepo[]): string;

package/dist/phases/flow-shared/clone-repos.js

@@ -0,0 +1,135 @@
+/**
+ * Shared multi-repo cloning for flow generation (screen-flow / data-flow).
+ *
+ * A flow can be scoped to one or several repositories (the user picks them in
+ * the desktop UI; the chosen set is stored on `flows.repository_ids`). This
+ * helper resolves that set, clones each repo into a per-flow parent workspace
+ * directory, and returns the directory the agent should run against:
+ *   - single repo  → the repo's own clone dir
+ *   - many repos   → the parent dir holding every clone as a subdirectory,
+ *                    so the agent can explore them all and produce one unified
+ *                    flow.
+ *
+ * Falls back to the product's primary repo when `repository_ids` is empty
+ * (older flows, or single-repo products).
+ */
+import { getGitHubConfigByProduct } from '../../api/github.js';
+import { getSupabase } from '../../supabase/client.js';
+import { logInfo, logWarning } from '../../utils/logger.js';
+import { cloneIssueRepo, ensureWorkspaceDir, getIssueRepoPath, } from '../../workspace/workspace-manager.js';
+function safeDirName(fullName) {
+    return fullName.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+/**
+ * Resolve the repositories a flow targets (by id, preserving the stored
+ * order), falling back to the product's primary repo.
+ */
+async function resolveTargetRepos(productId, repositoryIds, fallback) {
+    if (repositoryIds.length === 0) {
+        return [
+            {
+                fullName: `${fallback.owner}/${fallback.repo}`,
+                owner: fallback.owner,
+                repo: fallback.repo,
+            },
+        ];
+    }
+    const supabase = getSupabase();
+    const { data } = await supabase
+        .from('repositories')
+        .select('id, full_name')
+        .in('id', repositoryIds);
+    const byId = new Map(((data) ?? []).map((r) => [
+        r.id,
+        r.full_name,
+    ]));
+    // Preserve the caller's order (flows.repository_ids is ordered).
+    const resolved = [];
+    for (const id of repositoryIds) {
+        const fullName = byId.get(id);
+        if (!fullName) {
+            continue;
+        }
+        const [owner, repo] = fullName.split('/');
+        if (!owner || !repo) {
+            continue;
+        }
+        resolved.push({ fullName, owner, repo });
+    }
+    // If none resolved (deleted repos / RLS), fall back to the primary repo so
+    // generation still produces something useful.
+    if (resolved.length === 0) {
+        return [
+            {
+                fullName: `${fallback.owner}/${fallback.repo}`,
+                owner: fallback.owner,
+                repo: fallback.repo,
+            },
+        ];
+    }
+    return resolved;
+}
+export async function cloneFlowRepos(opts) {
+    const { productId, repositoryIds, workspaceKey, verbose } = opts;
+    const gh = await getGitHubConfigByProduct(productId, verbose);
+    if (!gh.configured || !gh.token || !gh.owner || !gh.repo) {
+        return {
+            ok: false,
+            message: gh.message ||
+                'GitHub repository not configured for this product. Connect a repo first.',
+        };
+    }
+    const targets = await resolveTargetRepos(productId, repositoryIds, {
+        owner: gh.owner,
+        repo: gh.repo,
+    });
+    const workspaceRoot = ensureWorkspaceDir();
+    const parentDir = getIssueRepoPath(workspaceRoot, `${workspaceKey}-${productId}`);
+    const repos = [];
+    for (const target of targets) {
+        try {
+            // The product-level token (installation or user PAT/OAuth) is reused for
+            // every repo; if it can't access one, that clone fails and we skip it
+            // rather than aborting the whole generation.
+            const { repoPath } = cloneIssueRepo(parentDir, safeDirName(target.fullName), target.owner, target.repo, gh.token);
+            repos.push({
+                fullName: target.fullName,
+                owner: target.owner,
+                repo: target.repo,
+                dir: repoPath,
+            });
+        }
+        catch (err) {
+            logWarning(`Skipping ${target.fullName}: clone failed (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    if (repos.length === 0) {
+        return { ok: false, message: 'Failed to clone any of the selected repositories.' };
+    }
+    if (repos.length > 1) {
+        logInfo(`Cloned ${repos.length} repos for ${workspaceKey}: ${repos.map((r) => r.fullName).join(', ')}`);
+    }
+    return {
+        ok: true,
+        // Single repo: run directly in its dir. Multi-repo: run in the parent so
+        // the agent sees every clone as a subdirectory.
+        projectDir: repos.length === 1 ? repos[0].dir : parentDir,
+        cleanupDir: parentDir,
+        repos,
+    };
+}
+/**
+ * Build a short note describing the repo scope, appended to the agent's user
+ * prompt so it knows whether to map one repo or unify several.
+ */
+export function describeRepoScope(repos) {
+    if (repos.length <= 1) {
+        return '';
+    }
+    const list = repos.map((r) => `- ${r.fullName} (subdirectory: ${safeDirName(r.fullName)})`);
+    return [
+        `This product spans ${repos.length} repositories, each cloned into its own subdirectory of the working directory:`,
+        ...list,
+        'Explore all of them and produce a single unified flow that spans the repositories.',
+    ].join('\n');
+}

package/dist/phases/output-contracts.js

@@ -900,11 +900,12 @@ You MUST end your response with a JSON object containing the code refine results
 **CRITICAL — How to return the result**:
 
 Return the extraction by calling the MCP tool
-\`mcp__screen-flow__submit_screen_flow\` **exactly once** with three arguments:
+\`mcp__screen-flow__submit_screen_flow\` **exactly once** with these arguments:
 
 - \`summary\` — 1-3 sentence narrative of what kind of app this is and its primary user flows
 - \`nodes\` — array of ScreenSchema objects (every user-facing screen, modal, drawer, tab, or named state)
 - \`edges\` — array of ScreenEdge objects (transitions between screens)
+- \`theme?\` — the product's visual design tokens \`{ primary?, neutral?, radius?, font? }\`, read from the **user-facing frontend**. When the product spans several repos, decide which one renders the UI users actually see (look for Tailwind config, global CSS variables like \`--primary\`/\`--radius\`, or a design-tokens file) and read its tokens — ignore backend/infra repos. Omit any field you can't determine, and omit \`theme\` entirely if there is no frontend.
 
 The tool validates the arguments against the schema. If it returns an error,
 fix the issue it describes and call the tool again. After a successful call,

package/dist/phases/run-sheet/index.js

@@ -243,6 +243,7 @@ export async function runRunSheet(options) {
     }
     const gh = await getGitHubConfigByProduct(release.product_id, verbose);
     const repoConfigured = gh.configured && gh.token && gh.owner && gh.repo;
+    const repoFullName = gh.owner && gh.repo ? `${gh.owner}/${gh.repo}` : null;
     let repoDir = null;
     let cloneError = null;
     let lockPath = null;
@@ -324,7 +325,7 @@ export async function runRunSheet(options) {
         const agentResult = await generateRunSheetWithAgent({
             product: {
                 name: product?.name ?? 'Unknown product',
-                github_repository_full_name: product?.github_repository_full_name ?? null,
+                github_repository_full_name: repoFullName,
             },
             release: {
                 tag: release.tag,
@@ -348,7 +349,7 @@ export async function runRunSheet(options) {
             template_snapshot: template,
             metadata: {
                 clone_error: cloneError,
-                repo: product?.github_repository_full_name ?? null,
+                repo: repoFullName,
                 tag: release.tag,
                 is_draft: isDraft,
                 draft_base_ref: draftBaseRef,

package/dist/phases/screen-flow/index.js

@@ -8,12 +8,12 @@
  * pattern, but writes to its own tables rather than filing issues.
  */
 import { query } from '@anthropic-ai/claude-agent-sdk';
-import { getGitHubConfigByProduct } from '../../api/github.js';
 import { DEFAULT_MODEL } from '../../constants.js';
 import { getSupabase } from '../../supabase/client.js';
 import { logError, logInfo, logSuccess, logWarning } from '../../utils/logger.js';
-import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, } from '../../workspace/workspace-manager.js';
+import { cleanupIssueRepo } from '../../workspace/workspace-manager.js';
 import { fetchProductBasics } from '../find-shared/mcp.js';
+import { cloneFlowRepos, describeRepoScope } from '../flow-shared/clone-repos.js';
 import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
 import { createScreenFlowCaptureState, createScreenFlowMcpServer, validateConsistency, } from './mcp-server.js';
 import { createScreenFlowSystemPrompt, createScreenFlowUserPrompt, } from './prompts.js';
@@ -30,36 +30,30 @@ export async function runScreenFlowPhase(options) {
     logInfo(`Starting screen-flow generation for product ${productId}`);
     const supabase = getSupabase();
     await markFlowRunning(supabase, flowId);
-    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
-    if (!githubConfig.configured ||
-        !githubConfig.token ||
-        !githubConfig.owner ||
-        !githubConfig.repo) {
-        const msg = githubConfig.message ||
-            'GitHub repository not configured for this product. Connect a repo first.';
-        await markFlowFailed(supabase, flowId, msg);
-        return { status: 'error', message: msg };
+    const repositoryIds = await getFlowRepositoryIds(supabase, flowId);
+    const cloneResult = await cloneFlowRepos({
+        productId,
+        repositoryIds,
+        workspaceKey: WORKSPACE_KEY,
+        verbose,
+    });
+    if (!cloneResult.ok) {
+        await markFlowFailed(supabase, flowId, cloneResult.message);
+        return { status: 'error', message: cloneResult.message };
     }
-    let repoPath;
+    const { projectDir, cleanupDir, repos } = cloneResult;
     let succeeded = false;
     try {
-        const workspaceRoot = ensureWorkspaceDir();
-        const repoKey = `${WORKSPACE_KEY}-${productId}`;
-        ({ repoPath } = cloneIssueRepo(workspaceRoot, repoKey, githubConfig.owner, githubConfig.repo, githubConfig.token));
         const product = await fetchProductBasics(productId);
-        const theme = extractTheme(repoPath);
-        if (Object.keys(theme).length > 0) {
-            logInfo(`Extracted theme: ${Object.entries(theme).map(([k, v]) => `${k}=${v}`).join(', ')}`);
-            await persistTheme(supabase, flowId, theme);
-        }
         const systemPrompt = await createScreenFlowSystemPrompt({
-            projectDir: repoPath,
+            projectDir,
             hasCodebase: true,
         });
+        const repoScope = describeRepoScope(repos);
         const userPrompt = createScreenFlowUserPrompt({
             productName: product.name,
             productDescription: product.description,
-            guidance,
+            guidance: [guidance, repoScope].filter(Boolean).join('\n\n') || undefined,
         });
         logInfo('Running Claude screen-flow extraction...');
         // The agent submits the extraction by calling submit_screen_flow on the
@@ -86,7 +80,7 @@ export async function runScreenFlowPhase(options) {
                 model: DEFAULT_MODEL,
                 maxTurns: MAX_TURNS,
                 permissionMode: 'bypassPermissions',
-                cwd: repoPath,
+                cwd: projectDir,
                 mcpServers: {
                     'screen-flow': mcpServer,
                 },
@@ -104,6 +98,11 @@ export async function runScreenFlowPhase(options) {
             return { status: 'error', message: msg };
         }
         logInfo(`Extraction produced ${extraction.nodes.length} screens / ${extraction.edges.length} transitions`);
+        const theme = resolveTheme(extraction.theme, repos);
+        if (Object.keys(theme).length > 0) {
+            logInfo(`Theme: ${Object.entries(theme).map(([k, v]) => `${k}=${v}`).join(', ')}`);
+            await persistTheme(supabase, flowId, theme);
+        }
         const { nodesCreated, edgesCreated } = await persistFlow(supabase, flowId, extraction);
         await markFlowSuccess(supabase, flowId, extraction.summary);
         succeeded = true;
@@ -124,9 +123,39 @@ export async function runScreenFlowPhase(options) {
     }
     finally {
         if (succeeded) {
-            cleanupIssueRepo(repoPath);
+            cleanupIssueRepo(cleanupDir);
+        }
+    }
+}
+/**
+ * Settle on the theme to persist. The agent decides which repo's design
+ * tokens represent the product (it can see every clone), so its answer wins.
+ * Only if it returned nothing do we fall back to deterministic static
+ * extraction, scanning each repo and taking the first non-empty result.
+ */
+function resolveTheme(agentTheme, repos) {
+    const cleaned = agentTheme
+        ? Object.fromEntries(Object.entries(agentTheme).filter(([, v]) => v !== null && v !== undefined && v !== ''))
+        : {};
+    if (Object.keys(cleaned).length > 0) {
+        return cleaned;
+    }
+    for (const repo of repos) {
+        const parsed = extractTheme(repo.dir);
+        if (Object.keys(parsed).length > 0) {
+            return parsed;
         }
     }
+    return {};
+}
+/** Read the ordered repo set a flow was scoped to (may be empty). */
+async function getFlowRepositoryIds(supabase, flowId) {
+    const { data } = await supabase
+        .from('flows')
+        .select('repository_ids')
+        .eq('id', flowId)
+        .single();
+    return (data?.repository_ids ?? []).filter(Boolean);
 }
 // Per-message handler — extracted out of the SDK loop to keep
 // runScreenFlowPhase under the eslint complexity ceiling.

package/dist/phases/screen-flow/mcp-server.d.ts

@@ -172,6 +172,12 @@ export declare function createSubmitScreenFlowTool(state: ScreenFlowCaptureState
             back: "back";
         }>;
     }, z.core.$strip>>;
+    theme: z.ZodOptional<z.ZodObject<{
+        primary: z.ZodOptional<z.ZodString>;
+        neutral: z.ZodOptional<z.ZodString>;
+        radius: z.ZodOptional<z.ZodString>;
+        font: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }>;
 /**
  * Build the `record_progress` tool. A side-channel that lets the agent

package/dist/phases/screen-flow/mcp-server.js

@@ -152,6 +152,12 @@ const screenEdgeSchema = z.object({
     triggerFile: z.string().optional(),
     kind: z.enum(['navigate', 'modal', 'redirect', 'back']),
 });
+const themeSchema = z.object({
+    primary: z.string().optional(),
+    neutral: z.string().optional(),
+    radius: z.string().optional(),
+    font: z.string().optional(),
+});
 // ---------------------------------------------------------------------------
 // Cross-field consistency (Zod can't express this)
 // ---------------------------------------------------------------------------
@@ -206,11 +212,15 @@ export function createSubmitScreenFlowTool(state) {
         edges: z
             .array(screenEdgeSchema)
             .describe('Transitions between screens. Every fromSlug / toSlug MUST reference a slug present in nodes; drop edges whose endpoints you did not emit.'),
+        theme: themeSchema
+            .optional()
+            .describe("The product's visual design tokens, read from its user-facing frontend (Tailwind config, CSS variables, or a tokens file). For a multi-repo product, pick the repo that renders the UI users see. Omit any field you cannot determine; omit the whole object if there is no frontend."),
     }, async (args) => {
         const extraction = {
             summary: args.summary,
             nodes: args.nodes,
             edges: args.edges,
+            theme: args.theme,
         };
         const { error } = validateConsistency(extraction);
         if (error) {

package/dist/phases/screen-flow/prompts.js

@@ -37,5 +37,7 @@ Start by detecting the framework (check package.json / pubspec.yaml / Package.sw
 
 Call \`mcp__screen-flow__record_progress\` at each phase boundary so the user can see your progress (otherwise the CLI looks frozen).
 
-When you are done, return the result by **calling the \`mcp__screen-flow__submit_screen_flow\` tool exactly once** with \`summary\`, \`nodes\`, and \`edges\` as arguments. Do not paste the JSON as a fenced text block — the tool call is the deliverable. If the tool returns an error, fix the issue it describes and call the tool again.`;
+Also determine the product's visual theme: find the user-facing frontend (when several repos are present, that's the one rendering the UI users see, not a backend or infra repo) and read its design tokens — primary/neutral colors, corner radius, and font — from its Tailwind config, global CSS variables, or a design-tokens file.
+
+When you are done, return the result by **calling the \`mcp__screen-flow__submit_screen_flow\` tool exactly once** with \`summary\`, \`nodes\`, \`edges\`, and (when you found a frontend) \`theme\` as arguments. Do not paste the JSON as a fenced text block — the tool call is the deliverable. If the tool returns an error, fix the issue it describes and call the tool again.`;
 }

package/dist/phases/screen-flow/types.d.ts

@@ -11,6 +11,7 @@
  * agent encounters something it can't model cleanly, it falls back to
  * `{ type: 'custom', label }` rather than guessing.
  */
+import type { ScreenFlowTheme } from './theme.js';
 export type ScreenKind = 'page' | 'modal' | 'drawer' | 'tab' | 'state';
 export type ScreenLayout = 'centered' | 'sidebar' | 'split' | 'list-detail' | 'tabs' | 'stacked';
 export interface ScreenAction {
@@ -126,5 +127,11 @@ export interface ScreenFlowExtraction {
     summary: string;
     nodes: ScreenSchema[];
     edges: ScreenEdge[];
+    /**
+     * Visual theme the agent judged best represents the product's user-facing
+     * surface. For multi-repo products the agent decides which repo's design
+     * tokens to use; omitted when it can't find any.
+     */
+    theme?: ScreenFlowTheme;
 }
 export declare function isScreenFlowExtraction(value: unknown): value is ScreenFlowExtraction;

package/dist/phases/sync-org-repos/index.d.ts

@@ -2,8 +2,9 @@
  * Phase: sync-org-repos
  *
  * Fetches all repositories from a GitHub organization using the local `gh` CLI,
- * then creates a product for each repo that isn't already linked to one
- * within the same team.
+ * then upserts a row into the team-scoped `repositories` table for each repo.
+ * Products are NOT created here — a product is a higher-level grouping that a
+ * user links one or more repositories to afterwards.
  *
  * Uses `gh api --paginate` for truly unlimited pagination (no hardcoded cap).
  * Forks and archived repos are filtered out client-side.

package/dist/phases/sync-org-repos/index.js

@@ -2,8 +2,9 @@
  * Phase: sync-org-repos
  *
  * Fetches all repositories from a GitHub organization using the local `gh` CLI,
- * then creates a product for each repo that isn't already linked to one
- * within the same team.
+ * then upserts a row into the team-scoped `repositories` table for each repo.
+ * Products are NOT created here — a product is a higher-level grouping that a
+ * user links one or more repositories to afterwards.
  *
  * Uses `gh api --paginate` for truly unlimited pagination (no hardcoded cap).
  * Forks and archived repos are filtered out client-side.
@@ -21,7 +22,7 @@ async function fetchOrgRepos(orgLogin, verbose) {
         `--paginate`,
         `/orgs/${encodeURIComponent(orgLogin)}/repos?per_page=100&type=sources&sort=updated`,
         '--jq',
-        '.[] | select(.archived == false) | {name, full_name, description, html_url}',
+        '.[] | select(.archived == false) | {id, name, full_name, description, html_url, default_branch, private, language}',
     ], { timeout: 120_000 });
     if (!stdout.trim()) {
         return [];
@@ -91,53 +92,53 @@ export async function syncOrgRepos(opts) {
     logInfo(`Found ${orgRepos.length} repos in ${orgLogin}`);
     const repoFullNames = orgRepos.map((r) => r.full_name);
     const { data: existing } = await supabase
-        .from('products')
-        .select('github_repository_full_name')
+        .from('repositories')
+        .select('full_name')
         .eq('team_id', teamId)
-        .in('github_repository_full_name', repoFullNames);
-    const linkedRepos = new Set((existing || []).map((p) => p.github_repository_full_name));
-    const toCreate = orgRepos.filter((r) => !linkedRepos.has(r.full_name));
-    if (toCreate.length === 0) {
-        const msg = `All ${linkedRepos.size} repos already linked to products`;
-        logInfo(msg);
-        return {
-            status: 'success',
-            message: msg,
-            total: orgRepos.length,
-            created: 0,
-            skipped: linkedRepos.size,
-        };
-    }
+        .in('full_name', repoFullNames);
+    const existingRepos = new Set((existing || []).map((r) => r.full_name));
+    const toCreate = orgRepos.filter((r) => !existingRepos.has(r.full_name));
+    // Refresh metadata + last_synced_at on every synced repo (new and existing)
+    // via upsert keyed on (team_id, full_name).
+    const now = new Date().toISOString();
+    const rows = orgRepos.map((repo) => ({
+        team_id: teamId,
+        created_by: userId,
+        github_repo_id: repo.id,
+        full_name: repo.full_name,
+        owner: repo.full_name.split('/')[0] ?? null,
+        name: repo.name,
+        url: repo.html_url,
+        description: repo.description,
+        default_branch: repo.default_branch,
+        private: repo.private,
+        language: repo.language,
+        last_synced_at: now,
+    }));
     if (verbose) {
         for (const r of toCreate) {
-            logDebug(`  Will create product: ${r.full_name}`);
+            logDebug(`  Will create repository: ${r.full_name}`);
         }
     }
-    const rows = toCreate.map((repo) => ({
-        name: repo.name,
-        description: repo.description,
-        team_id: teamId,
-        created_by: userId,
-        github_repository_full_name: repo.full_name,
-        github_repository_url: repo.html_url,
-    }));
-    const { error: insertError } = await supabase.from('products').insert(rows);
-    if (insertError) {
-        logError(`Failed to insert products: ${insertError.message}`);
+    const { error: upsertError } = await supabase
+        .from('repositories')
+        .upsert(rows, { onConflict: 'team_id,full_name' });
+    if (upsertError) {
+        logError(`Failed to upsert repositories: ${upsertError.message}`);
         return {
             status: 'error',
-            message: `Failed to create products: ${insertError.message}`,
+            message: `Failed to sync repositories: ${upsertError.message}`,
             total: orgRepos.length,
             created: 0,
-            skipped: linkedRepos.size,
+            skipped: existingRepos.size,
         };
     }
     return {
         status: 'success',
-        message: `Created ${toCreate.length} products, ${linkedRepos.size} already existed`,
+        message: `Synced ${orgRepos.length} repos: ${toCreate.length} new, ${existingRepos.size} updated`,
         total: orgRepos.length,
         created: toCreate.length,
-        skipped: linkedRepos.size,
+        skipped: existingRepos.size,
         repos: toCreate.map((r) => r.full_name),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edsger",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "type": "module",
   "bin": {
     "edsger": "dist/index.js"
@@ -50,8 +50,8 @@
     "commander": "^12.0.0",
     "cosmiconfig": "^9.0.0",
     "dotenv": "^16.4.5",
-    "edsger-contract": "0.5.0",
-    "edsger-tools": "0.5.0",
+    "edsger-contract": "0.6.0",
+    "edsger-tools": "0.6.0",
     "gray-matter": "^4.0.3",
     "zod": "^4.0.0"
   },