@agent-loom/loom 1.0.2 → 1.0.3

package/dist/cli.js

@@ -18,15 +18,23 @@ import { applyTemplate } from './apply.js';
 import { cloneRegistry, resolveTemplatePath } from './clone.js';
 import { resolveTemplateSource } from './resolve-template.js';
 import { createCraftFetcher } from './skill-fetcher.js';
-import { validateTemplate, validateRegistry } from './validate.js';
 import { loadWorkspaces, filterWorkspaces, recordWorkspace, removeWorkspace, addTag, setNote, saveWorkspaces, } from './workspaces.js';
+import { chat, listWorkspaceAgents, findWorkspaceRoot, suggestClosest, resolveAgentInWorkspace, resolveAgentFromRegistry, listRegistryAgentIds, listRegistryAgents, } from './chat/index.js';
+import { stageRegistryAgent } from './launch/index.js';
+import { listSessions, readSession, updateSessionMeta, } from './sessions/index.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 const program = new Command();
 program
     .name('loom')
     .description('Template engine for coding agent workspaces')
-    .version(version);
+    .version(version)
+    // Route options to the subcommand that owns them. Without this, options
+    // declared on both the verbless `loom <agent>` form and on a subcommand
+    // (e.g. `--clone-repos`, `--registry`) get consumed by the program-level
+    // verbless declaration before subcommand parsing runs, leaving the
+    // subcommand's option at its default. Bug repro and rationale: #186.
+    .enablePositionalOptions();
 // =============================================================================
 // registry
 // =============================================================================
@@ -376,7 +384,7 @@ ws
     }
     addTag(entry, tag);
     await saveWorkspaces(data);
-    console.log(chalk.green(`✓ Tag "${tag}" added.`));
+    console.log(chalk.green(`Tag "${tag}" added.`));
 });
 ws
     .command('note <path> <note>')
@@ -390,7 +398,7 @@ ws
     }
     setNote(entry, note);
     await saveWorkspaces(data);
-    console.log(chalk.green(`✓ Note updated.`));
+    console.log(chalk.green('Note updated.'));
 });
 ws
     .command('remove <path>')
@@ -398,98 +406,642 @@ ws
     .action(async (path) => {
     const removed = await removeWorkspace(path);
     if (removed) {
-        console.log(chalk.green(`✓ Workspace entry removed.`));
+        console.log(chalk.green('Workspace entry removed.'));
     }
     else {
         console.error(chalk.red(`Workspace "${path}" not found.`));
         process.exit(1);
     }
 });
-// =============================================================================
-// validate
-// =============================================================================
-program
-    .command('validate [template-dir]')
-    .description('Validate manifest.yaml schema and references')
-    .option('-r, --registry-root <dir>', 'Registry root directory (for resolving shared/ refs)')
-    .option('--all', 'Validate all templates in registry (requires --registry-root)')
-    .action(async (templateDir, opts) => {
+async function runChatCli(agentId, passthrough, opts) {
     try {
-        if (opts.all) {
-            const registryRoot = opts.registryRoot ?? '.';
-            const results = await validateRegistry(registryRoot);
-            let hasError = false;
-            const templateResults = results.filter((r) => r.templateId !== '__registry__');
-            const registryResults = results.filter((r) => r.templateId === '__registry__');
-            // Print registry-level errors first
-            for (const r of registryResults) {
-                for (const e of r.errors) {
-                    console.log(chalk.red(`  ✗ ${e.message}`));
-                    hasError = true;
-                }
-            }
-            // Print per-template results
-            const validCount = templateResults.filter((r) => r.errors.length === 0).length;
-            console.log(chalk.blue(`\nValidating registry (${templateResults.length} templates)`));
-            for (const r of templateResults) {
-                if (r.errors.length === 0) {
-                    console.log(chalk.green(`  ✓ ${r.templateId} ......... OK`));
+        const cwd = opts.cwd ?? process.cwd();
+        const runtime = (opts.runtime ?? 'copilot');
+        // Prefer `-- <args...>` passthrough. Fall back to deprecated
+        // --runtime-args <csv> for anyone who has the old form scripted.
+        let extraArgs;
+        if (passthrough && passthrough.length > 0) {
+            extraArgs = passthrough;
+        }
+        else if (opts.runtimeArgs) {
+            extraArgs = opts.runtimeArgs.split(',');
+        }
+        // Bolt-on flags from the new verb-less form. These get appended AFTER
+        // any explicit passthrough so users can still override them with `-- ...`.
+        const boltOn = [];
+        if (opts.addDir)
+            boltOn.push('--add-dir', opts.addDir);
+        if (opts.model)
+            boltOn.push('--model', opts.model);
+        if (boltOn.length > 0) {
+            extraArgs = [...(extraArgs ?? []), ...boltOn];
+        }
+        // No agent given -> show what's available in the resolved workspace.
+        if (!agentId) {
+            printAgentList(opts.workspace ?? cwd);
+            console.error();
+            console.error(chalk.dim('Usage: loom <agent>'));
+            return;
+        }
+        if (runtime !== 'copilot' && runtime !== 'claude') {
+            console.error(chalk.red(`Unknown runtime: ${runtime}. Use copilot or claude.`));
+            process.exit(2);
+        }
+        const launchCwd = opts.workspace ?? cwd;
+        const interactive = opts.interactive !== false;
+        // Step 1: try in-workspace resolution (walk-up unless --workspace is set).
+        const local = resolveAgentInWorkspace({
+            agentId,
+            cwd: launchCwd,
+            strictCwd: Boolean(opts.workspace),
+        });
+        if (local) {
+            const result = await chat({
+                agentId,
+                cwd: launchCwd,
+                resolved: local,
+                runtime,
+                prompt: opts.prompt,
+                interactive,
+                extraArgs,
+                sessionName: opts.sessionName,
+                recordSession: opts.session !== false,
+            });
+            process.exit(result.exitCode ?? 0);
+        }
+        // Step 2: fall back to configured registries (unless --no-registry-fallback).
+        if (opts.registryFallback !== false) {
+            const hit = await resolveAgentFromRegistry({
+                agentId,
+                registryName: typeof opts.registry === 'string' ? opts.registry : undefined,
+                workspaceDir: launchCwd,
+            });
+            if (hit) {
+                console.error(chalk.blue(`  Staging ${chalk.bold(hit.agentId)} from ${hit.registryName}/${hit.templateId} ...`));
+                // Resolve --clone-repos. Commander parses `--clone-repos [mode]`
+                // as one of: undefined (flag absent), true (flag present with no
+                // value), or a string. Default is 'auto' since staged launches
+                // need repos to do real work.
+                let cloneReposMode = 'auto';
+                if (typeof opts.cloneRepos === 'string') {
+                    if (!['auto', 'all', 'none'].includes(opts.cloneRepos)) {
+                        throw new Error(`Invalid --clone-repos "${opts.cloneRepos}". Must be "auto", "all", or "none".`);
+                    }
+                    cloneReposMode = opts.cloneRepos;
                 }
-                else {
-                    hasError = true;
-                    console.log(chalk.red(`  ✗ ${r.templateId} ......... ${r.errors.length} error(s)`));
-                    for (const e of r.errors) {
-                        console.log(chalk.red(`    → ${e.message}`));
+                let cloneModeOpt;
+                if (typeof opts.cloneMode === 'string') {
+                    if (!['full', 'partial'].includes(opts.cloneMode)) {
+                        throw new Error(`Invalid --clone-mode "${opts.cloneMode}". Must be "full" or "partial".`);
                     }
+                    cloneModeOpt = opts.cloneMode;
                 }
+                // Interactive prompt for large/ADO repos (mirrors `loom apply`).
+                const stagingPromptFn = async (message, _choices) => {
+                    const rl = createInterface({ input: process.stdin, output: process.stdout });
+                    return new Promise((resolveP) => {
+                        rl.question(chalk.yellow(`  ${message}\n  [clone / skip / enter path to existing clone]: `), (answer) => {
+                            rl.close();
+                            resolveP(answer.trim() || 'skip');
+                        });
+                    });
+                };
+                const stagingLinkFn = async (target, linkPath) => {
+                    if (platform() === 'win32') {
+                        execSync(`cmd /c mklink /J "${linkPath}" "${target}"`, { stdio: 'pipe' });
+                    }
+                    else {
+                        const { symlink } = await import('node:fs/promises');
+                        await symlink(target, linkPath, 'junction');
+                    }
+                };
+                const staged = await stageRegistryAgent({
+                    hit,
+                    sessionName: opts.sessionName,
+                    runtime,
+                    onProgress: (m) => console.error(chalk.dim(`  ${m}`)),
+                    cloneRepos: cloneReposMode,
+                    cloneMode: cloneModeOpt,
+                    promptFn: cloneReposMode !== 'none' ? stagingPromptFn : undefined,
+                    linkFn: cloneReposMode !== 'none' ? stagingLinkFn : undefined,
+                });
+                console.error(chalk.green(`  Staged at ${staged.session.dir}`));
+                const result = await chat({
+                    agentId,
+                    cwd: staged.agent.workspaceDir,
+                    resolved: staged.agent,
+                    session: staged.session,
+                    runtime,
+                    prompt: opts.prompt,
+                    interactive,
+                    extraArgs,
+                });
+                process.exit(result.exitCode ?? 0);
             }
-            console.log(`\nSummary: ${validCount}/${templateResults.length} templates valid`);
-            if (hasError)
-                process.exit(1);
         }
-        else {
-            if (!templateDir) {
-                console.error(chalk.red('Please provide a template directory or use --all'));
-                process.exit(1);
+        // Step 3: neither found -- friendly error with suggestions from both layers.
+        await printNotFoundHelp(agentId, launchCwd, opts.registryFallback !== false);
+        process.exit(1);
+    }
+    catch (err) {
+        const msg = err.message ?? String(err);
+        console.error(chalk.red(msg));
+        process.exit(1);
+    }
+}
+/**
+ * Attach the chat option set to a Commander command.
+ */
+function applyChatOptions(cmd) {
+    return cmd
+        .option('-p, --prompt <text>', 'Prefilled / one-shot prompt (use --no-interactive for headless single-shot)')
+        .option('--no-interactive', 'Run non-interactively (single-shot, exits after the prompt)')
+        .option('--add-dir <path>', 'Additional directory passed to the runtime via --add-dir')
+        .option('--model <name>', 'Model override (forwarded to the runtime via --model)')
+        .option('-r, --runtime <runtime>', 'Runtime: copilot or claude', 'copilot')
+        .option('-w, --workspace <dir>', 'Override workspace (skips walk-up discovery)')
+        .option('--cwd <dir>', 'Working directory (defaults to current)')
+        .option('--runtime-args <args>', '(deprecated) comma-separated runtime args; prefer `-- <args...>`')
+        .option('--session-name <name>', 'Friendly label stored on the session record')
+        .option('--no-session', 'Do not record a session under ~/.loom/sessions/')
+        .option('--no-registry-fallback', 'Disable the registry fallback (fail fast if agent not in workspace)')
+        .option('--registry <name>', 'Only search the named registry when falling back')
+        .option('--clone-repos [mode]', 'When staging from a registry, clone manifest repos: auto (default), all, or none')
+        .option('--clone-mode <strategy>', 'Clone strategy: full (default) or partial (blobless)');
+}
+// Verb-less default: `loom <agent> [-- ...]`. When no agent is given (and
+// no subcommand matched), this falls through to the agent-list helper.
+applyChatOptions(program
+    .argument('[agent]', 'Agent name to launch interactively (verb-less form)')
+    .argument('[passthrough...]', 'Args forwarded to the runtime (after --)')
+    .description('Launch a single agent interactively (verb-less form). Falls back to configured registries if the agent is not in the current workspace.')
+    .addHelpText('after', `
+Examples:
+  $ loom triage                              Launch 'triage' interactively
+  $ loom triage -p "investigate X"           Launch with a prefilled prompt
+  $ loom triage --model opus                 Use a specific model
+  $ loom triage -- --some-runtime-flag       Pass --some-runtime-flag through
+  $ loom -w C:\\path\\to\\ws triage             Use explicit workspace (no walk-up)
+  $ loom                                     List available agents (no agent given)
+
+For headless / one-shot execution see \`loom run\` (or import from
+'@agent-loom/loom/run' as an SDK).
+`)).action(async (agentId, passthrough, opts) => {
+    await runChatCli(agentId, passthrough, opts);
+});
+// =============================================================================
+// run -- headless single-agent execution (SDK-equivalent CLI surface)
+// =============================================================================
+program
+    .command('run <template> <agent>')
+    .description('Run an agent headlessly and collect artifacts (SESSION, REPORT, PROGRESS)')
+    .requiredOption('--prompt <text>', 'Prompt text or @filepath')
+    .requiredOption('--work-dir <path>', 'Working directory for the run (required, no temp default)')
+    .option('--model <name>', 'Model override')
+    .option('--timeout-ms <n>', 'Timeout in milliseconds', (v) => parseInt(v, 10))
+    .action(async (template, agentId, opts) => {
+    const { run: runFn } = await import('./run/index.js');
+    try {
+        const result = await runFn({
+            template,
+            agent: agentId,
+            workDir: opts.workDir,
+            prompt: opts.prompt,
+            model: opts.model,
+            // Library handles the default (DEFAULT_RUN_TIMEOUT_MS); only override
+            // when the user supplied --timeout-ms explicitly.
+            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        });
+        if (result.artifactPaths.session)
+            console.log(`SESSION: ${result.artifactPaths.session}`);
+        if (result.artifactPaths.report)
+            console.log(`REPORT: ${result.artifactPaths.report}`);
+        if (result.artifactPaths.progress)
+            console.log(`PROGRESS: ${result.artifactPaths.progress}`);
+        if (result.timedOut)
+            console.error(chalk.red('Run timed out.'));
+        process.exit(result.exitCode);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+/** Helper: aggregate workspace + registry agent ids for the not-found message. */
+async function printNotFoundHelp(agentId, cwd, registryEnabled) {
+    console.error(chalk.red(`Agent "${agentId}" not found.`));
+    const workspace = findWorkspaceRoot(cwd);
+    const localIds = workspace ? listWorkspaceAgents(workspace).map((a) => a.agentId) : [];
+    const registryIds = registryEnabled
+        ? await listRegistryAgentIds({ workspaceDir: cwd }).catch(() => [])
+        : [];
+    const pool = Array.from(new Set([...localIds, ...registryIds]));
+    const suggestions = suggestClosest(agentId, pool);
+    if (suggestions.length > 0) {
+        console.error();
+        console.error(chalk.yellow(`Did you mean: ${suggestions.join(', ')}?`));
+    }
+    if (workspace && localIds.length > 0) {
+        console.error();
+        console.error(chalk.dim(`In workspace ${workspace}:`));
+        for (const a of localIds)
+            console.error(chalk.dim(`  ${a}`));
+    }
+    if (registryEnabled && registryIds.length > 0) {
+        console.error();
+        console.error(chalk.dim(`In configured registries:`));
+        for (const a of registryIds)
+            console.error(chalk.dim(`  ${a}`));
+    }
+    if (pool.length === 0) {
+        console.error();
+        console.error(chalk.dim('No agents found locally and no registries configured.'));
+        console.error(chalk.dim('Add a registry with: loom registry add <name> <url>'));
+    }
+}
+// =============================================================================
+// agents — list agents in the current workspace
+// =============================================================================
+program
+    .command('agents [scope]')
+    .description('List agents in the current workspace (use --all for every registry-installable agent). Scope drills: <registry> or <registry>/<template>')
+    .option('--cwd <dir>', 'Working directory (defaults to current)')
+    .option('--names-only', 'Output just agent ids, one per line (for scripts / tab completion)')
+    .option('--all', 'List every agent available across configured registries')
+    .action(async (scope, opts) => {
+    const cwd = opts.cwd ?? process.cwd();
+    if (opts.all) {
+        const parts = (scope ?? '').split('/').map((s) => s.trim()).filter(Boolean);
+        const registryFilter = parts[0];
+        const templateFilter = parts[1];
+        const listings = await listRegistryAgents({
+            workspaceDir: cwd,
+            registryName: registryFilter,
+        });
+        if (opts.namesOnly) {
+            const filtered = templateFilter
+                ? listings.filter((l) => l.templateId === templateFilter)
+                : listings;
+            for (const l of filtered)
+                process.stdout.write(l.agentId + '\n');
+            return;
+        }
+        if (listings.length === 0) {
+            console.error(chalk.yellow(registryFilter
+                ? `No agents found in registry "${registryFilter}".`
+                : 'No agents found in configured registries.'));
+            console.error(chalk.dim('  Add one:  loom registry add <name> <url>'));
+            return;
+        }
+        // Level 1: no scope → registry summary (skipped when only one registry)
+        const allRegistryNames = Array.from(new Set(listings.map((l) => l.registryName)));
+        if (!registryFilter && allRegistryNames.length > 1) {
+            const byReg = new Map();
+            for (const l of listings) {
+                const e = byReg.get(l.registryName) ?? { teams: new Set(), agents: 0 };
+                e.teams.add(l.templateId);
+                e.agents++;
+                byReg.set(l.registryName, e);
             }
-            const registryRoot = opts.registryRoot ?? templateDir.replace(/[/\\]templates[/\\].*$/, '');
-            const result = await validateTemplate(templateDir, registryRoot);
-            console.log(chalk.blue(`\nValidating template: ${result.templateId}`));
-            if (result.errors.length === 0) {
-                console.log(chalk.green('  ✓ manifest.yaml valid'));
-                const s = result.summary;
-                if (s.instructions > 0)
-                    console.log(chalk.green(`  ✓ ${s.instructions} instructions resolved`));
-                if (s.skills > 0)
-                    console.log(chalk.green(`  ✓ ${s.skills} skills`));
-                if (s.agents > 0)
-                    console.log(chalk.green(`  ✓ ${s.agents} agents resolved`));
-                if (s.mcp > 0)
-                    console.log(chalk.green(`  ✓ ${s.mcp} MCP servers resolved`));
-                if (s.repos > 0)
-                    console.log(chalk.green(`  ✓ ${s.repos} repos resolved`));
-                if (s.prompts > 0)
-                    console.log(chalk.green(`  ✓ ${s.prompts} prompts resolved`));
-                if (s.prerequisites > 0)
-                    console.log(chalk.green(`  ✓ ${s.prerequisites} prerequisites resolved`));
-                console.log(chalk.green('\n0 errors'));
+            const rows = Array.from(byReg.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+            const regCol = Math.max(8, ...rows.map((r) => r[0].length));
+            console.error(chalk.bold.dim(`  ${'REGISTRY'.padEnd(regCol)}  TEAMS  AGENTS`));
+            console.error(chalk.dim('  ' + '-'.repeat(regCol + 18)));
+            for (const [name, e] of rows) {
+                console.error(`  ${chalk.bold(name.padEnd(regCol))}  ` +
+                    `${String(e.teams.size).padStart(5)}  ${String(e.agents).padStart(6)}`);
             }
-            else {
-                for (const e of result.errors) {
-                    console.log(chalk.red(`  ✗ [${e.level}] ${e.field}: ${e.message}`));
-                }
-                console.log(chalk.red(`\n${result.errors.length} error(s)`));
-                process.exit(1);
+            console.error(chalk.dim(`\n  Drill down:  loom agents --all <registry>\n` +
+                `  e.g.         loom agents --all ${rows[0][0]}`));
+            return;
+        }
+        // Level 2: registry scope (or single-registry auto-collapse) → team summary
+        const effectiveRegistry = registryFilter ?? allRegistryNames[0];
+        if (!templateFilter) {
+            const byTeam = new Map();
+            for (const l of listings) {
+                if (l.registryName !== effectiveRegistry)
+                    continue;
+                const e = byTeam.get(l.templateId) ?? { agents: 0, sample: [] };
+                e.agents++;
+                if (e.sample.length < 3)
+                    e.sample.push(l.agentId);
+                byTeam.set(l.templateId, e);
+            }
+            const rows = Array.from(byTeam.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+            const teamCol = Math.max(4, ...rows.map((r) => r[0].length));
+            console.error(chalk.bold(effectiveRegistry) + chalk.dim(allRegistryNames.length > 1 ? '' : '  (only registry)'));
+            console.error();
+            console.error(chalk.bold.dim(`  ${'TEAM'.padEnd(teamCol)}  AGENTS  SAMPLE`));
+            console.error(chalk.dim('  ' + '-'.repeat(teamCol + 40)));
+            for (const [name, e] of rows) {
+                console.error(`  ${chalk.bold(name.padEnd(teamCol))}  ` +
+                    `${String(e.agents).padStart(6)}  ` +
+                    `${chalk.dim(e.sample.join(', ') + (e.agents > e.sample.length ? ', ...' : ''))}`);
             }
+            console.error(chalk.dim(`\n  Drill down:  loom agents --all ${effectiveRegistry}/<team>\n` +
+                `  e.g.         loom agents --all ${effectiveRegistry}/${rows[0][0]}`));
+            return;
+        }
+        // Level 3: registry/team scope → agent list
+        const filtered = listings.filter((l) => l.registryName === effectiveRegistry && l.templateId === templateFilter);
+        if (filtered.length === 0) {
+            console.error(chalk.yellow(`No team "${templateFilter}" in registry "${effectiveRegistry}".`));
+            console.error(chalk.dim(`  List teams:  loom agents --all ${effectiveRegistry}`));
+            return;
         }
+        const idCol = Math.max(5, ...filtered.map((l) => l.agentId.length));
+        console.error(chalk.bold(`${effectiveRegistry} / ${templateFilter}`));
+        console.error();
+        console.error(chalk.bold.dim(`  ${'AGENT'.padEnd(idCol)}  DESCRIPTION`));
+        console.error(chalk.dim('  ' + '-'.repeat(idCol + 60)));
+        for (const l of filtered) {
+            const desc = l.description ?? chalk.dim('(no description)');
+            console.error(`  ${chalk.bold(l.agentId.padEnd(idCol))}  ${chalk.dim(desc)}`);
+        }
+        console.error(chalk.dim(`\n  ${filtered.length} ${filtered.length === 1 ? 'agent' : 'agents'}. ` +
+            `Launch one with:  loom <agent>`));
+        return;
     }
-    catch (err) {
-        console.error(chalk.red(`Error: ${err.message}`));
+    if (opts.namesOnly) {
+        const workspace = findWorkspaceRoot(cwd);
+        if (!workspace)
+            return;
+        for (const a of listWorkspaceAgents(workspace)) {
+            process.stdout.write(a.agentId + '\n');
+        }
+        return;
+    }
+    printAgentList(cwd);
+});
+function printAgentList(cwd) {
+    const workspace = findWorkspaceRoot(cwd);
+    if (!workspace) {
+        console.error(chalk.yellow('No workspace found.'));
+        console.error(chalk.dim(`  Walked up from: ${cwd}\n` +
+            `  Looking for an ancestor containing .github/agents/`));
+        return;
+    }
+    const agents = listWorkspaceAgents(workspace);
+    console.error(chalk.dim(`workspace: ${workspace}`));
+    console.error();
+    if (agents.length === 0) {
+        console.error(chalk.yellow('No agents found in .github/agents/'));
+        console.error(chalk.dim('  See what you could install:  loom agents --all'));
+        return;
+    }
+    const idCol = Math.max(5, ...agents.map((a) => a.agentId.length));
+    console.error(chalk.bold.dim(`  ${'AGENT'.padEnd(idCol)}  DESCRIPTION`));
+    console.error(chalk.dim('  ' + '-'.repeat(idCol + 2 + 60)));
+    for (const a of agents) {
+        const name = a.metadata.name ?? '';
+        const desc = a.metadata.description ?? chalk.dim('(no description)');
+        const nameCell = name && name !== a.agentId ? chalk.dim(`  ${name}`) : '';
+        console.error(`  ${chalk.bold(a.agentId.padEnd(idCol))}${nameCell}`);
+        if (a.metadata.description)
+            console.error(`    ${chalk.dim(desc)}`);
+    }
+    console.error(chalk.dim(`\n  ${agents.length} ${agents.length === 1 ? 'agent' : 'agents'}. ` +
+        `Launch one with:  loom <agent>`));
+}
+// =============================================================================
+// sessions — inspect & manage session records
+// =============================================================================
+const sessions = program
+    .command('sessions')
+    .description('Inspect launch sessions (~/.loom/sessions/)');
+sessions
+    .command('list')
+    .description('List recent sessions, newest first')
+    .option('-n, --limit <n>', 'Max sessions to show', '20')
+    .option('--status <s>', 'Filter by status (running|exited|errored)')
+    .option('--agent <id>', 'Filter by agent id')
+    .option('--ids-only', 'Output just session ids, one per line (for scripts / tab completion)')
+    .action((opts) => {
+    const limit = Math.max(1, parseInt(opts.limit, 10) || 20);
+    let all = listSessions();
+    if (opts.status)
+        all = all.filter((s) => s.meta.status === opts.status);
+    if (opts.agent)
+        all = all.filter((s) => s.meta.agentId === opts.agent);
+    if (opts.idsOnly) {
+        for (const s of all.slice(0, limit))
+            process.stdout.write(s.meta.id + '\n');
+        return;
+    }
+    if (all.length === 0) {
+        console.error(chalk.dim('No sessions found.'));
+        return;
+    }
+    const shown = all.slice(0, limit);
+    // Column widths sized to content; keep status at a fixed width for color padding.
+    const idW = Math.max(2, ...shown.map((s) => s.meta.id.length));
+    const agentW = Math.max(5, ...shown.map((s) => s.meta.agentId.length));
+    const whenW = 19; // YYYY-MM-DD HH:MM:SS
+    const statusW = 7; // 'running' is longest
+    const header = `  ${'ID'.padEnd(idW)}  ${'STATUS'.padEnd(statusW)}  ${'STARTED'.padEnd(whenW)}  ${'AGENT'.padEnd(agentW)}  EXIT  NAME`;
+    console.log(chalk.bold.dim(header));
+    console.log(chalk.dim('  ' + '-'.repeat(header.length - 2)));
+    for (const s of shown) {
+        const status = s.meta.status.padEnd(statusW);
+        const colored = s.meta.status === 'running' ? chalk.cyan(status) :
+            s.meta.status === 'exited' && s.meta.exitCode === 0 ? chalk.green(status) :
+                chalk.red(status);
+        const when = s.meta.startedAt.slice(0, 19).replace('T', ' ');
+        const exit = s.meta.exitCode == null ? '  - ' : String(s.meta.exitCode).padEnd(4);
+        const name = s.meta.name ? chalk.dim(`"${s.meta.name}"`) : '';
+        console.log(`  ${s.meta.id.padEnd(idW)}  ${colored}  ${chalk.dim(when)}  ${chalk.bold(s.meta.agentId.padEnd(agentW))}  ${exit}  ${name}`);
+    }
+    const total = all.length;
+    const hidden = total - shown.length;
+    const footer = hidden > 0
+        ? chalk.dim(`\n  Showing ${shown.length} of ${total}. Use -n <N> to show more.`)
+        : chalk.dim(`\n  ${total} ${total === 1 ? 'session' : 'sessions'}.`);
+    console.error(footer);
+});
+sessions
+    .command('show <id>')
+    .description('Show full metadata for a session')
+    .action((id) => {
+    const s = readSession(id);
+    if (!s) {
+        console.error(chalk.red(`Session not found: ${id}`));
+        process.exit(1);
+    }
+    const m = s.meta;
+    const statusColored = m.status === 'running' ? chalk.cyan(m.status) :
+        m.status === 'exited' && m.exitCode === 0 ? chalk.green(m.status) :
+            chalk.red(m.status);
+    console.log(chalk.bold(m.id));
+    console.log(chalk.dim(s.dir));
+    console.log();
+    const row = (label, value) => console.log(`  ${chalk.dim(label.padEnd(10))} ${value}`);
+    if (m.name)
+        row('name', m.name);
+    row('agent', m.agentName && m.agentName !== m.agentId
+        ? `${m.agentId} ${chalk.dim(`(${m.agentName})`)}` : m.agentId);
+    row('runtime', m.runtime);
+    row('origin', m.origin);
+    row('workspace', m.workspaceDir);
+    row('status', m.exitCode != null ? `${statusColored}  ${chalk.dim(`exit=${m.exitCode}`)}` : statusColored);
+    row('started', m.startedAt);
+    if (m.endedAt)
+        row('ended', m.endedAt);
+    if (m.durationMs != null)
+        row('duration', humanizeDuration(m.durationMs));
+    if (m.tags && m.tags.length > 0)
+        row('tags', m.tags.join(', '));
+    if (m.note)
+        row('note', m.note);
+    console.log();
+    console.log(chalk.dim(`  Tag:   loom sessions tag ${m.id} <tag>`));
+    console.log(chalk.dim(`  Note:  loom sessions note ${m.id} "<text>"`));
+});
+function humanizeDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    const rs = s % 60;
+    if (m < 60)
+        return rs > 0 ? `${m}m ${rs}s` : `${m}m`;
+    const h = Math.floor(m / 60);
+    const rm = m % 60;
+    return rm > 0 ? `${h}h ${rm}m` : `${h}h`;
+}
+sessions
+    .command('tag <id> <tag>')
+    .description('Add a tag to a session')
+    .action((id, tag) => {
+    const s = readSession(id);
+    if (!s) {
+        console.error(chalk.red(`Session not found: ${id}`));
+        process.exit(1);
+    }
+    const tags = Array.from(new Set([...(s.meta.tags ?? []), tag]));
+    updateSessionMeta(id, { tags });
+    console.error(chalk.green(`Tagged ${id} with "${tag}"`));
+});
+sessions
+    .command('note <id> <note>')
+    .description('Set a note on a session')
+    .action((id, note) => {
+    const s = readSession(id);
+    if (!s) {
+        console.error(chalk.red(`Session not found: ${id}`));
         process.exit(1);
     }
+    updateSessionMeta(id, { note });
+    console.error(chalk.green(`Note set on ${id}`));
 });
 // =============================================================================
-// Run
+// completion — shell tab-completion scripts
 // =============================================================================
+const POWERSHELL_COMPLETER = [
+    '# loom PowerShell tab completion',
+    '# Install: Add to your $PROFILE, or: loom completion powershell | Out-String | Invoke-Expression',
+    'Register-ArgumentCompleter -Native -CommandName loom -ScriptBlock {',
+    '    param($wordToComplete, $commandAst, $cursorPosition)',
+    '    $tokens = $commandAst.CommandElements | ForEach-Object { $_.ToString() }',
+    '    $sub = if ($tokens.Count -ge 2) { $tokens[1] } else { \'\' }',
+    '',
+    '    $subcommands = @(',
+    '        \'run\',\'agents\',\'sessions\',\'apply\',\'search\',\'registry\',\'workspaces\',',
+    '        \'completion\',\'validate\',\'scaffold\'',
+    '    )',
+    '',
+    '    if ($tokens.Count -le 1 -or ($tokens.Count -eq 2 -and $wordToComplete)) {',
+    '        $subcommands |',
+    '            Where-Object { $_ -like "$wordToComplete*" } |',
+    '            ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, \'ParameterValue\', $_) }',
+    '        return',
+    '    }',
+    '',
+    '    switch ($sub) {',
+    '        \'run\' {',
+    '            if (-not $wordToComplete.StartsWith(\'-\')) {',
+    '                try {',
+    '                    (& loom agents --names-only 2>$null) -split [Environment]::NewLine |',
+    '                        Where-Object { $_ -and $_ -like "$wordToComplete*" } |',
+    '                        ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, \'ParameterValue\', $_) }',
+    '                } catch {}',
+    '            }',
+    '        }',
+    '        \'sessions\' {',
+    '            $sessionSub = if ($tokens.Count -ge 3) { $tokens[2] } else { \'\' }',
+    '            if (@(\'show\',\'tag\',\'note\') -contains $sessionSub -and -not $wordToComplete.StartsWith(\'-\')) {',
+    '                try {',
+    '                    (& loom sessions list --ids-only -n 50 2>$null) -split [Environment]::NewLine |',
+    '                        Where-Object { $_ -and $_ -like "$wordToComplete*" } |',
+    '                        ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, \'ParameterValue\', $_) }',
+    '                } catch {}',
+    '            } elseif ($tokens.Count -le 2 -or ($tokens.Count -eq 3 -and $wordToComplete)) {',
+    '                @(\'list\',\'show\',\'tag\',\'note\') |',
+    '                    Where-Object { $_ -like "$wordToComplete*" } |',
+    '                    ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, \'ParameterValue\', $_) }',
+    '            }',
+    '        }',
+    '    }',
+    '}',
+    '',
+].join('\n');
+const BASH_COMPLETER = [
+    '# loom bash tab completion',
+    '# Install: loom completion bash > /etc/bash_completion.d/loom  (or source in .bashrc)',
+    '_loom_completion() {',
+    '    local cur prev words cword',
+    '    COMPREPLY=()',
+    '    cur="${COMP_WORDS[COMP_CWORD]}"',
+    '    prev="${COMP_WORDS[COMP_CWORD-1]}"',
+    '    local sub="${COMP_WORDS[1]:-}"',
+    '    local subcommands="run agents sessions apply search registry workspaces completion validate scaffold"',
+    '',
+    '    if [ "$COMP_CWORD" -eq 1 ]; then',
+    '        COMPREPLY=( $(compgen -W "$subcommands" -- "$cur") )',
+    '        return 0',
+    '    fi',
+    '',
+    '    case "$sub" in',
+    '        run)',
+    '            if [[ "$cur" != -* && "$prev" != -* ]]; then',
+    '                local agents',
+    '                agents=$(loom agents --names-only 2>/dev/null)',
+    '                COMPREPLY=( $(compgen -W "$agents" -- "$cur") )',
+    '            fi',
+    '            ;;',
+    '        sessions)',
+    '            local ssub="${COMP_WORDS[2]:-}"',
+    '            if [[ "$ssub" =~ ^(show|tag|note)$ && "$cur" != -* ]]; then',
+    '                local ids',
+    '                ids=$(loom sessions list --ids-only -n 50 2>/dev/null)',
+    '                COMPREPLY=( $(compgen -W "$ids" -- "$cur") )',
+    '            elif [ "$COMP_CWORD" -eq 2 ]; then',
+    '                COMPREPLY=( $(compgen -W "list show tag note" -- "$cur") )',
+    '            fi',
+    '            ;;',
+    '    esac',
+    '}',
+    'complete -F _loom_completion loom',
+    '',
+].join('\n');
+program
+    .command('completion <shell>')
+    .description('Emit tab-completion script for powershell or bash')
+    .action((shell) => {
+    const s = shell.toLowerCase();
+    if (s === 'powershell' || s === 'pwsh') {
+        process.stdout.write(POWERSHELL_COMPLETER);
+    }
+    else if (s === 'bash') {
+        process.stdout.write(BASH_COMPLETER);
+    }
+    else {
+        console.error(chalk.red(`Unsupported shell: ${shell}`));
+        console.error(chalk.dim('Supported: powershell, bash'));
+        process.exit(1);
+    }
+});
 program.parse();
 //# sourceMappingURL=cli.js.map