teamshare-bridge 0.1.0 → 0.2.0

package/dist/cli/index.js

@@ -27,45 +27,128 @@ const chat_reply_1 = require("../lib/chat-reply");
 const doc_reply_1 = require("../lib/doc-reply");
 const config_1 = require("../lib/config");
 const lock_1 = require("../lib/lock");
+const usage_1 = require("../lib/usage");
 const session_stream_1 = require("../lib/session-stream");
 const models_1 = require("../lib/models");
+const harness_1 = require("../lib/harness");
+const skills_1 = require("../lib/skills");
 const VERSION = '0.1.0';
 const WS_DEFAULT = 'ws://localhost:4000';
-/** Phase D settings resolution: CLI flag > agent settings (passed as flags) > env > default. */
-function modelOf(flags) {
-    return flags.get('model') ?? process.env.LLM_MODEL ?? llm_1.DEFAULT_LLM_MODEL;
+/** Build mode (IMP-700): the project chat channel for agent questions. */
+const AGENT_QUESTIONS_CHANNEL = 'agent-questions';
+/** Per-project build run state (skipped tasks awaiting answers) lives here. */
+const BUILD_STATE_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), '.teamshare', 'builds');
+/** Stop file: the daemon writes it on build.stop; the loop honors + deletes it. */
+const STOP_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), '.teamshare', 'stops');
+/** Best-effort fetch of the agent's stored settings - never fatal. */
+async function fetchAgentSettings(api, agentId, log) {
+    try {
+        const s = await api.getAgentSettings(agentId);
+        log(`[settings] agent stored: model=${s.model ?? 'none'} temperature=${s.temperature ?? 'default'} maxTokens=${s.maxTokens ?? 'default'} harness=${s.harness ?? 'default'} prompt=${s.systemPrompt ? 'set' : 'none'} providerKey=${s.providerKey ? 'set' : 'none'}`);
+        return {
+            model: s.model ?? undefined,
+            temperature: s.temperature ?? undefined,
+            maxTokens: s.maxTokens ?? undefined,
+            systemPrompt: s.systemPrompt,
+            userId: s.userId ?? undefined,
+            harness: s.harness,
+            providerKey: s.providerKey,
+        };
+    }
+    catch (err) {
+        log(`[settings] could not fetch agent settings (${(0, config_1.msg)(err)}) - using flags/env`, 'stderr');
+        return {};
+    }
+}
+/** Session driver resolution: flag > agent setting > local config > auto. */
+function harnessOf(flags, agent) {
+    return (flags.get('harness') ??
+        agent?.harness ??
+        (0, config_1.loadConfig)().harness ??
+        'auto');
+}
+/**
+ * LLM provider key for self-loop / chat / doc sessions:
+ * server BYOK (settings.providerKey) > local config chatKey >
+ * CHAT_LLM_API_KEY > LLM_API_KEY env. Never logged.
+ */
+function sessionLlmApiKey(agent) {
+    return agent?.providerKey ?? (0, config_1.chatKey)() ?? '';
+}
+/** Phase D settings resolution: CLI flag > agent settings > env > default. */
+function modelOf(flags, agent) {
+    return (flags.get('model') ??
+        agent?.model ??
+        process.env.LLM_MODEL ??
+        llm_1.DEFAULT_LLM_MODEL);
 }
 /** Model spec -> { baseUrl, model } via the catalog (env LLM_BASE_URL wins). */
-function llmEndpoint(flags) {
-    const spec = modelOf(flags);
+function llmEndpoint(flags, agent) {
+    const spec = modelOf(flags, agent);
     const resolved = (0, models_1.resolveModel)(spec, process.env.LLM_BASE_URL);
-    if (!resolved.catalogued) {
+    if (resolved.harnessOnly) {
+        console.log(`[model] "${spec}" is a harness-native model - must use opencode/claude harness, not --self`);
+    }
+    else if (!resolved.catalogued) {
         console.log(`[model] "${spec}" is not a catalogued provider:model spec - using LLM_BASE_URL (${resolved.baseUrl})`);
     }
-    return { baseUrl: resolved.baseUrl, model: resolved.model };
+    return { baseUrl: resolved.baseUrl, model: resolved.model, harnessOnly: resolved.harnessOnly };
+}
+/**
+ * Applies the LLM provider key for harness runs: server BYOK
+ * (settings.providerKey) > per-agent key > global key (both from
+ * ~/.teamshare/config.json). Set as OPENCODE_API_KEY so the harness child
+ * inherits it - agent usage never bills the user's default opencode
+ * credentials. An env var already set always wins. The KEY VALUE IS NEVER
+ * LOGGED - only which source was used.
+ */
+function applyOpenCodeKey(agentId, log, settings) {
+    if (process.env.OPENCODE_API_KEY) {
+        log('[key] OPENCODE_API_KEY env already set - leaving it untouched');
+        return;
+    }
+    const key = settings?.providerKey ?? (0, config_1.agentOpenCodeKey)(agentId);
+    if (!key) {
+        log('[key] no LLM provider key configured - opencode falls back to auth.json');
+        return;
+    }
+    process.env.OPENCODE_API_KEY = key;
+    log(settings?.providerKey
+        ? '[key] server BYOK provider key applied (isolated from your default credentials)'
+        : '[key] local agent LLM provider key applied (isolated from your default credentials)');
 }
-function temperatureOf(flags) {
-    const raw = flags.get('temperature') ?? process.env.LLM_TEMPERATURE;
+/** Harness kill-switch: max minutes an opencode/claude child may run (env TEAMSHARE_SESSION_TIMEOUT_MIN, default 60). */
+function sessionTimeoutMin(flags) {
+    const raw = flags.get('session-timeout') ?? process.env.TEAMSHARE_SESSION_TIMEOUT_MIN;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : 60;
+}
+function temperatureOf(flags, agent) {
+    const raw = flags.get('temperature') ??
+        (agent?.temperature !== undefined ? String(agent.temperature) : undefined) ??
+        process.env.LLM_TEMPERATURE;
     if (raw === undefined)
         return undefined;
     const n = Number(raw);
     return Number.isFinite(n) ? Math.min(2, Math.max(0, n)) : undefined;
 }
-function maxTokensOf(flags) {
-    const raw = flags.get('max-tokens') ?? process.env.LLM_MAX_TOKENS;
+function maxTokensOf(flags, agent) {
+    const raw = flags.get('max-tokens') ??
+        (agent?.maxTokens !== undefined ? String(agent.maxTokens) : undefined) ??
+        process.env.LLM_MAX_TOKENS;
     if (raw === undefined)
         return undefined;
     const n = Number(raw);
     return Number.isInteger(n) && n > 0 ? n : undefined;
 }
-function systemPromptOf(flags) {
+function systemPromptOf(flags, agent) {
     const inline = flags.get('system-prompt');
     if (inline !== undefined)
         return inline;
     const file = flags.get('system-prompt-file');
     if (file && (0, node_fs_1.existsSync)(file))
         return (0, node_fs_1.readFileSync)(file, 'utf8');
-    return null;
+    return agent?.systemPrompt ?? null;
 }
 /** Console + live-stream logger for a session. */
 function makeLog(stream) {
@@ -82,6 +165,15 @@ function usage() {
         '  teamshare-agent connect --agent <agentId> --key <ts_...>',
         '      Test the connection and save the agent key in ~/.teamshare/config.json.',
         '',
+        '  teamshare-agent link --project <projectId> --path <folder> [--guard true|false]',
+        '      PROJECT GUARD: bind a TeamShare project to a local folder. The agent',
+        '      refuses to work a project until it is linked, and every session then',
+        '      runs inside that folder (read-only warning for OneDrive/network/',
+        '      outside-profile paths - those are blocked).',
+        '  teamshare-agent link --list',
+        '  teamshare-agent unlink --project <projectId>',
+        '      Remove the link - sessions for that project are blocked again.',
+        '',
         '  teamshare-agent run --task <taskId> --agent <agentId> --key <ts_...> [options]',
         '      Fetch the task brief and work it with a harness or headless LLM.',
         '      Without --task, picks up the agent\'s next assigned task from its inbox',
@@ -90,28 +182,71 @@ function usage() {
         '  teamshare-agent continue --task <taskId> --agent <agentId> --key <ts_...> [--self]',
         '      Resume the previous --self session for a task (Phase E continuation).',
         '',
-        '  teamshare-agent chat --project <projectId> --agent <agentId> --key <ts_...> [--mention <token>]',
-        '      Reply to every project-chat message that @mentions the agent (one reply',
-        '      per message). Spawned by the daemon on chat.mention wakes.',
+        '  teamshare-agent chat --project <projectId> --agent <agentId> --key <ts_...> [--mention <token>] [--target <messageId>]',
+        '      Reply to ONE project-chat message that @mentions the agent (one mention',
+        '      → one reply → sleep). --target pins the reply to that specific message;',
+        '      without it the latest mention is used. Spawned by the daemon on chat.mention wakes.',
         '',
         '  teamshare-agent doc --document <documentId> --agent <agentId> --key <ts_...> [--mention <token>]',
         '      Document assistant (Phase F): read the document (Word/PPT/Excel/PDF)',
         '      and reply to every comment that @mentions the agent in its thread.',
         '      Spawned by the daemon on document.mention wakes.',
         '',
+        '  teamshare-agent build --project <projectId> --agent <agentId> --key <ts_...> [options]',
+        '      BUILD MODE: work the project\'s ready-for-dev queue in strict order',
+        '      (sortOrder asc, createdAt asc), one task at a time, fully completing',
+        '      each. A failed task is skipped: a [question] comment + #agent-questions',
+        '      message ask the team what to do, the build continues, and the task is',
+        '      resumed automatically once a human answers. Pass --once to stop after',
+        '      the first task; --dry-run prints the queue without working anything.',
+        '  teamshare-agent build --project <id> --agent <id> --key <ts_...> --draft "<goal>" [--go]',
+        '      Draft the build queue for a goal: the agent plans 3-8 concrete tasks,',
+        '      creates them ready-for-dev in order and assigns them to itself. --go',
+        '      executes the queue immediately afterwards; without it just the plan.',
+        '',
+        '  teamshare-agent usage [--day YYYY-MM-DD] [--agent <agentId>]',
+        '      Agent spend report - read-only daily cost/token view of the local',
+        '      opencode db (~/.local/share/opencode/opencode.db). Offline; needs',
+        '      neither the backend nor the daemon. Attribution: "TeamShare "',
+        '      titles = agent sessions, providerID opencode = your own windows.',
+        '',
+        '  teamshare-agent skills install|list|uninstall',
+        '      Install the TeamShare agent skills (teamshare-cdd, teamshare-modularity,',
+        '      teamshare-auth-rbac) into the opencode skills directory (~/.agents/skills',
+        '      by default; TEAMSHARE_SKILLS_DIR overrides). Agents working TeamShare tasks',
+        '      are expected to load them and follow their rules.',
+        '',
+        '  teamshare-agent key set --key <providerApiKey> [--agent <agentId>]',
+        '  teamshare-agent key show | clear [--agent <agentId>]',
+        '      LLM provider key for agent harness runs (e.g. an opencode-go API key).',
+        '      Without --agent it is the global default for every agent; with --agent',
+        '      it overrides that agent only. Agents run with their OWN key so usage',
+        '      never bills your default opencode credentials. Keys are never printed.',
+        '',
         'OPTIONS',
         '  --harness auto|opencode|claude|none   session driver (default: config or auto)',
         '  --self                                headless LLM loop (needs LLM_API_KEY env)',
         '  --no-report                           skip the closing summary comment',
         '  --continue                           resume the previous --self session for this task (Phase E)',
         '  --session <id>                        live-console session id (default: auto)',
+        '  --cwd <folder>                       work inside this folder (else the linked',
+        '                                       project folder; hard-blocked if neither)',
         '  --model <id>                          model override (Phase D; env LLM_MODEL)',
         '  --temperature <0-2>                   sampling temperature (Phase D; env LLM_TEMPERATURE)',
         '  --max-tokens <n>                      token budget (Phase D; env LLM_MAX_TOKENS)',
         '  --system-prompt <text>                system prompt override (Phase D)',
         '  --system-prompt-file <path>           system prompt from a file (Phase D)',
         '  --ask-timeout <sec>                   ask_human wait limit (Phase B; env TEAMSHARE_ASK_TIMEOUT)',
+        '  --session-timeout <min>              harness kill-switch cap (default 60; env TEAMSHARE_SESSION_TIMEOUT_MIN)',
+        '  --once                                build: stop after the first task',
+        '  --dry-run                             build: print the queue, work nothing',
+        '  --draft <goal>                        build: plan the queue for a goal (creates tasks)',
+        '  --go                                  build: execute the queue after --draft',
+        '  --on-fail ask|stop                    build: ask a question (resume later) or stop the run on failure (default ask)',
+        '  --blocked-wait <min>                  build: how long to wait for answers before exiting (default 30)',
         '  --api-url <url>                       TeamShare API base (default: ' + api_1.DEFAULT_API_URL + ')',
+        '  --day <YYYY-MM-DD>                    usage report day (default: today)',
+        '  --agent <agentId>                     usage report filter (title contains "agent <id>")',
         '  -h, --help                            this help',
         '',
         'ENV',
@@ -166,8 +301,34 @@ function need(flags, name) {
     }
     return value;
 }
-function harnessOf(flags) {
-    return (flags.get('harness') ?? (0, config_1.loadConfig)().harness ?? 'auto');
+/**
+ * Project guard (IMP-6xx): resolve the working folder for a session. An
+ * explicit `--cwd` wins; otherwise the project's linked folder from the
+ * local config is used. Returns null (blocked) when no folder is available
+ * - the caller must refuse the session.
+ */
+function resolveWorkingDir(flags, projectId, log) {
+    const explicit = flags.get('cwd');
+    if (explicit) {
+        const abs = (0, node_path_1.resolve)(explicit);
+        if (!(0, node_fs_1.existsSync)(abs) || !(0, node_fs_1.statSync)(abs).isDirectory()) {
+            log(`[guard] --cwd is not an existing folder: ${abs}`, 'stderr');
+            return null;
+        }
+        log(`[guard] working folder: ${abs}`);
+        return abs;
+    }
+    const cwd = projectId ? (0, config_1.projectCwd)(projectId) : null;
+    if (!cwd) {
+        log(projectId
+            ? `[guard] BLOCKED - project ${projectId} has no linked folder.\n` +
+                `  Link one first:\n  ${(0, config_1.linkHint)(projectId)}`
+            : `[guard] BLOCKED - could not determine the project; no folder to work in.\n` +
+                `  Link one first:\n  teamshare-agent link --project <projectId> --path C:\\path\\to\\folder`, 'stderr');
+        return null;
+    }
+    log(`[guard] working folder: ${cwd}`);
+    return cwd;
 }
 async function cmdConnect(flags) {
     const agentId = need(flags, 'agent');
@@ -176,15 +337,112 @@ async function cmdConnect(flags) {
     await api.heartbeat(agentId, 'online');
     (0, config_1.upsertAgent)(agentId, apiKey);
     console.log(`Connected: agent ${agentId} (key saved to ~/.teamshare/config.json)`);
+    // Wire TeamShare MCP into opencode so the agent has tools in sessions.
+    const wired = (0, config_1.wireOpencodeMcp)(apiKey);
+    console.log(wired
+        ? '[mcp] wired TeamShare MCP into opencode.jsonc — agent now has 21 tools (create_task, list_tasks, search, etc.)'
+        : '[mcp] TeamShare MCP already wired in opencode.jsonc — skipping');
     console.log('Ready: teamshare-agent run --task <taskId> --agent ' + agentId + '');
 }
+/** `link` - project guard: bind a TeamShare project to a local folder. */
+async function cmdLink(flags) {
+    if (flags.get('list') === 'true') {
+        const entries = Object.entries((0, config_1.loadConfig)().projects);
+        if (entries.length === 0) {
+            console.log('No projects linked yet - run: teamshare-agent link --project <id> --path <folder>');
+            return;
+        }
+        for (const [projectId, link] of entries) {
+            console.log(`${projectId} -> ${link.path}${link.guard === false ? ' (guard off)' : ''}`);
+        }
+        return;
+    }
+    const projectId = need(flags, 'project');
+    const path = need(flags, 'path');
+    const result = (0, config_1.linkProject)(projectId, path, flags.get('guard') !== 'false');
+    if (!result.ok) {
+        console.error(`Could not link project ${projectId}:`);
+        console.error('  ' + result.reason);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Linked project ${projectId} -> ${result.canonical}`);
+    console.log('The agent now works inside this folder for that project (guard on).');
+}
+/** `unlink` - remove a project link. */
+async function cmdUnlink(flags) {
+    const projectId = need(flags, 'project');
+    const config = (0, config_1.unlinkProject)(projectId);
+    const gone = !config.projects[projectId];
+    if (gone)
+        console.log(`Unlinked project ${projectId} - its sessions are now blocked by the guard.`);
+    else {
+        console.error(`Project ${projectId} was not linked.`);
+        process.exitCode = 1;
+    }
+}
+/** `usage` - read-only daily spend report from the local opencode db. */
+async function cmdUsage(flags) {
+    try {
+        const report = (0, usage_1.runUsageReport)({
+            day: flags.get('day') ?? undefined,
+            agent: flags.get('agent') ?? undefined,
+        });
+        console.log(`Agent spend report - ${report.day} (local time)`);
+        console.log(`Source: ${report.dbPath} (read-only)`);
+        console.log(`Total: $${report.totalCost.toFixed(4)} across ${report.sessionCount} sessions`);
+        console.log(`  your own windows : $${report.userCost.toFixed(4)}`);
+        console.log(`  agent sessions   : $${report.agentCost.toFixed(4)} (of which TeamShare $${report.teamshareCost.toFixed(4)})`);
+        const t = report.tokens;
+        console.log(`Tokens: ${t.input.toLocaleString()} in / ${t.output.toLocaleString()} out / ` +
+            `${t.reasoning.toLocaleString()} reasoning / ${t.cacheRead.toLocaleString()} cache-read`);
+        if (report.sessions.length === 0) {
+            console.log('No cost-bearing sessions for this day.');
+            return;
+        }
+        console.log('');
+        console.log('time          dur     cost      src       model                          title');
+        console.log('-'.repeat(120));
+        for (const s of report.sessions) {
+            const src = s.attribution === 'user' ? 'user' : s.teamshare ? 'teamshare' : 'agent';
+            const start = new Date(s.timeCreated).toLocaleTimeString([], {
+                hour: '2-digit',
+                minute: '2-digit',
+            });
+            const end = new Date(s.timeUpdated).toLocaleTimeString([], {
+                hour: '2-digit',
+                minute: '2-digit',
+            });
+            const model = `${s.providerID}/${s.model}`.slice(0, 34);
+            console.log(`${start}-${end}  ${String(s.durationMin.toFixed(1)).padStart(5)}m  ` +
+                `${s.cost.toFixed(4).padStart(7)}  ${src.padEnd(9)}  ${model.padEnd(34)}  ${s.title.slice(0, 60)}`);
+        }
+        console.log('');
+        console.log(`Takeaway: agents cost $${report.agentCost.toFixed(4)} vs your own windows ` +
+            `$${report.userCost.toFixed(4)} on ${report.day}.`);
+    }
+    catch (err) {
+        console.error(`[usage] ${(0, config_1.msg)(err)}`);
+        process.exitCode = 1;
+    }
+}
 async function cmdRun(flags) {
     const agentId = need(flags, 'agent');
     const apiKey = need(flags, 'key');
-    const selfMode = flags.get('self') === 'true';
+    let selfMode = flags.get('self') === 'true';
     const noReport = flags.get('no-report') === 'true';
-    const harness = harnessOf(flags);
     const api = new api_1.TeamshareApi(process.env.TEAMSHARE_API_URL, apiKey);
+    // Phase D: apply the agent's stored model/harness/providerKey/etc.
+    // (flag > agent setting > env > default) for direct CLI sessions.
+    const settings = await fetchAgentSettings(api, agentId, makeLog(null));
+    const harness = harnessOf(flags, settings);
+    // If model is harness-only (opencode-go), force harness mode instead of --self
+    const modelSpec = modelOf(flags);
+    const modelResolved = (0, models_1.resolveModel)(modelSpec, process.env.LLM_BASE_URL);
+    if (modelResolved.harnessOnly && selfMode) {
+        console.log(`[model] "${modelSpec}" is harness-native - switching from --self to harness mode`);
+        selfMode = false;
+    }
     // One session per agent at a time - wait for any in-flight session to finish.
     const lock = await (0, lock_1.acquireLock)(agentId, 'task', {
         taskId: flags.get('task') ?? undefined,
@@ -197,15 +455,24 @@ async function cmdRun(flags) {
     }
     let exitCode = 0;
     let heartbeatTimer;
+    let claimedTaskId;
     const sessionId = flags.get('session') ?? (0, session_stream_1.newSessionId)();
     const stream = new session_stream_1.SessionStream({ sessionId, agentId, mode: 'run' });
-    stream.connect((process.env.TEAMSHARE_WS_URL ?? WS_DEFAULT).replace(/\/$/, '') + '/agents', apiKey);
     const log = makeLog(stream);
+    applyOpenCodeKey(agentId, log, settings);
     try {
         // Explicit --task wins; otherwise pick up the agent's next assigned task
         // from its inbox (urgent > high > medium > low, then oldest; anything
         // in_review/resolved/closed is skipped).
         let taskId = flags.get('task');
+        // Defense: a bare `--task` (no value) parses as boolean "true" via
+        // parseArgs - never treat a non-UUID as a task id. Fall back to picking
+        // the agent's next assigned task instead of failing every UUID check.
+        if (taskId &&
+            !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(taskId)) {
+            log(`[pickup] --task ignored (not a UUID: "${taskId}") - picking the next assigned task`, 'stderr');
+            taskId = undefined;
+        }
         if (!taskId) {
             const picked = await pickNextTask(api, agentId, log);
             if (!picked) {
@@ -214,9 +481,51 @@ async function cmdRun(flags) {
             }
             taskId = picked;
         }
-        const task = await api.getTask(taskId).catch(() => null);
-        stream.meta.projectId = task?.projectId ?? undefined;
-        log(`[teamshare-agent] task ${taskId} as agent ${agentId} (${selfMode ? 'headless' : harness})`);
+        // PROJECT GUARD (IMP-6xx): resolve the working folder for this task
+        // before any work - unlinked projects are hard-blocked (the agent only
+        // ever runs inside a folder you linked).
+        const task = await api.getTask(taskId).catch((err) => {
+            log(`[guard] FAILED to fetch task ${taskId}: ${err.message ?? err}`, 'stderr');
+            return null;
+        });
+        if (!task) {
+            log(`[guard] Cannot access task ${taskId} - stopping. Verify project membership.`, 'stderr');
+            exitCode = 1;
+            return;
+        }
+        stream.meta.projectId = task.projectId ?? undefined;
+        stream.meta.taskId = taskId;
+        // Connect the session stream now that the meta is known, so session:start
+        // carries taskId/projectId (earlier lines replay from the buffer). Late
+        // connect also means blocked/early-exit sessions still stream their exit.
+        stream.connect((process.env.TEAMSHARE_WS_URL ?? WS_DEFAULT).replace(/\/$/, '') + '/agents', apiKey);
+        const cwd = resolveWorkingDir(flags, task?.projectId ?? null, log);
+        if (!cwd) {
+            exitCode = 1;
+            return;
+        }
+        // Phase D settings were fetched before the lock; the run continues below.
+        // IMP-560: claim the task so no other agent works it concurrently (the
+        // server-side lease renews on every mutation and auto-releases here on
+        // session end). Hard refusals: claimed by someone else, locked to its
+        // agent assignee, or blocked by the project/task agent-work policy.
+        try {
+            const claim = await api.claimTask(taskId);
+            claimedTaskId = taskId;
+            log(`[claim] task ${taskId} claimed - lease until ${claim.claimExpiresAt}`);
+        }
+        catch (err) {
+            const e = err;
+            if (e.code === 'TASK_CLAIMED_BY' ||
+                e.code === 'AGENT_TASK_LOCKED' ||
+                e.code === 'AGENT_UNASSIGNED_BLOCKED') {
+                log(`[claim] cannot work task ${taskId}: ${e.message ?? e.code}`, 'stderr');
+                exitCode = 1;
+                return;
+            }
+            log(`[claim] warning: could not claim task ${taskId}: ${e.message ?? e.code}`, 'stderr');
+        }
+        log(`[teamshare-agent] task ${taskId} as agent ${agentId} (${selfMode ? 'headless' : harness}) in ${cwd}`);
         await (0, brief_1.reportStatus)(api, agentId, 'working', taskId, sessionId);
         // Keep lastSeenAt fresh during long sessions so the backend liveness
         // sweep never mistakes a working agent for a dead one.
@@ -233,9 +542,10 @@ async function cmdRun(flags) {
         log('[brief] --- end preview ---');
         let summary = '';
         if (selfMode) {
-            const llmApiKey = process.env.LLM_API_KEY;
+            // BYOK: server-stored provider key > local config > env.
+            const llmApiKey = sessionLlmApiKey(settings);
             if (!llmApiKey) {
-                log('--self requires LLM_API_KEY env (and optionally LLM_BASE_URL / LLM_MODEL)', 'stderr');
+                log('--self requires a provider API key (set it on the agent in TeamShare, or LLM_API_KEY env)', 'stderr');
                 exitCode = 1;
                 return;
             }
@@ -243,34 +553,44 @@ async function cmdRun(flags) {
             if (flags.get('ask-timeout')) {
                 process.env.TEAMSHARE_ASK_TIMEOUT = flags.get('ask-timeout') ?? '';
             }
-            const endpoint = llmEndpoint(flags);
+            const endpoint = llmEndpoint(flags, settings);
             log(`[model] ${endpoint.model} @ ${endpoint.baseUrl}`);
+            const task = await api.getTask(taskId).catch(() => null);
             const result = await (0, llm_1.runLlmSession)(api, taskId, brief, {
                 baseUrl: endpoint.baseUrl,
                 apiKey: llmApiKey,
                 model: endpoint.model,
                 agentName: agentId,
-                systemPrompt: systemPromptOf(flags),
-                temperature: temperatureOf(flags),
-                maxTokens: maxTokensOf(flags),
+                systemPrompt: systemPromptOf(flags, settings),
+                temperature: temperatureOf(flags, settings),
+                maxTokens: maxTokensOf(flags, settings),
                 continue: flags.get('continue') === 'true',
-            });
+                agentUserId: settings.userId ?? undefined,
+            }, task?.projectId);
             summary =
                 result.summary ||
                     `Agent run finished after ${result.iterations} iterations (${result.tokensUsed} tokens).`;
             log(`[session] done: ${result.finishedBy} | ${result.iterations} iterations | ${result.tokensUsed} tokens`);
         }
         else {
-            const systemPrompt = systemPromptOf(flags);
+            const systemPrompt = systemPromptOf(flags, settings);
             const prompt = `Work on the TeamShare task described in ${briefPath} using the teamshare MCP tools. ` +
                 `Break the task down first: create 3-8 subtasks with create_subtask, then check each off ` +
                 `(update_subtask with done: true) as you complete it. ` +
+                (settings.userId
+                    ? `Your TeamShare user id is ${settings.userId} - when a task or the brief asks you to assign a task to yourself, pass assigneeId "me" (resolves to your user id).\n`
+                    : '') +
                 (systemPrompt ? `Follow these instructions: ${systemPrompt}\n\n` : '') +
                 `Keep the human informed with progress comments on the task. When done, post a detailed ` +
                 `summary comment (mention the subtask progress) and move the task to in_review (or resolved if you are confident).`;
             exitCode = await spawnHarness(harness, prompt, log, {
-                model: flags.get('model') ?? undefined,
-                temperature: temperatureOf(flags),
+                model: modelOf(flags, settings),
+                temperature: temperatureOf(flags, settings),
+                cwd,
+                timeoutMin: sessionTimeoutMin(flags),
+                title: `TeamShare task ${taskId} (agent ${agentId})`,
+                agentKey: api.apiKey,
+                apiBaseUrl: api.baseUrl,
             });
             summary = `Harness (${harness}) finished the session - see the task comments.`;
         }
@@ -287,6 +607,10 @@ async function cmdRun(flags) {
     finally {
         if (heartbeatTimer)
             clearInterval(heartbeatTimer);
+        if (claimedTaskId) {
+            await api.releaseTask(claimedTaskId).catch(() => undefined);
+            log(`[claim] task ${claimedTaskId} released`);
+        }
         (0, lock_1.releaseLock)(agentId);
         await stream.end(exitCode);
     }
@@ -300,13 +624,21 @@ async function cmdDoc(flags) {
     const apiKey = need(flags, 'key');
     const mention = flags.get('mention') ?? '';
     const selfMode = flags.get('self') === 'true';
-    const harness = harnessOf(flags);
     let exitCode = 0;
     const sessionId = flags.get('session') ?? (0, session_stream_1.newSessionId)();
     const stream = new session_stream_1.SessionStream({ sessionId, agentId, mode: 'chat' });
     stream.connect((process.env.TEAMSHARE_WS_URL ?? WS_DEFAULT).replace(/\/$/, '') + '/agents', apiKey);
     const log = makeLog(stream);
     const api = new api_1.TeamshareApi(process.env.TEAMSHARE_API_URL, apiKey);
+    // PROJECT GUARD (IMP-6xx): hard-block document sessions for documents
+    // whose project has no linked local folder.
+    const doc = await api.getDocument(documentId).catch(() => null);
+    const cwd = resolveWorkingDir(flags, doc?.projectId ?? null, log);
+    if (!cwd)
+        return;
+    const settings = await fetchAgentSettings(api, agentId, log);
+    const harness = harnessOf(flags, settings);
+    applyOpenCodeKey(agentId, log, settings);
     const lock = await (0, lock_1.acquireLock)(agentId, 'doc', { documentId }, {
         onWaiting: (busy) => console.log(`[lock] agent ${agentId} is busy (pid ${busy.pid}, since ${busy.startedAt}, ${busy.kind}) - waiting for it to finish...`),
     });
@@ -316,7 +648,7 @@ async function cmdDoc(flags) {
     }
     try {
         await (0, brief_1.reportStatus)(api, agentId, 'working', undefined, sessionId);
-        log(`[teamshare-agent] document assistant (document ${documentId}${mention ? `, mention @${mention}` : 'all mentions'})`);
+        log(`[teamshare-agent] document assistant (document ${documentId}${mention ? `, mention @${mention}` : 'all mentions'}) in ${cwd}`);
         const heartbeatTimer = setInterval(() => {
             void (0, brief_1.reportStatus)(api, agentId, 'working', undefined, sessionId);
         }, 60_000);
@@ -325,12 +657,13 @@ async function cmdDoc(flags) {
                 harness,
                 selfMode,
                 echo: process.env.TS_CHAT_ECHO === '1',
+                api,
                 llm: {
-                    baseUrl: llmEndpoint(flags).baseUrl,
-                    apiKey: process.env.LLM_API_KEY ?? '',
-                    model: llmEndpoint(flags).model,
-                    temperature: temperatureOf(flags),
-                    maxTokens: maxTokensOf(flags),
+                    baseUrl: llmEndpoint(flags, settings).baseUrl,
+                    apiKey: sessionLlmApiKey(settings),
+                    model: llmEndpoint(flags, settings).model,
+                    temperature: temperatureOf(flags, settings),
+                    maxTokens: maxTokensOf(flags, settings),
                 },
             });
             log(`[done] replied to ${result.replied} mention${result.replied === 1 ? '' : 's'}` +
@@ -350,20 +683,28 @@ async function cmdDoc(flags) {
         await stream.end(exitCode);
     }
 }
-/** Chat reply loop: reply to every message mentioning the agent. */
+/** Chat reply loop: reply to a single mentioning message (the triggering one). */
 async function cmdChat(flags) {
     const projectId = need(flags, 'project');
     const agentId = need(flags, 'agent');
     const apiKey = need(flags, 'key');
     const mention = flags.get('mention') ?? '';
+    const targetId = flags.get('target');
     const selfMode = flags.get('self') === 'true';
-    const harness = harnessOf(flags);
     let exitCode = 0;
     const sessionId = flags.get('session') ?? (0, session_stream_1.newSessionId)();
     const stream = new session_stream_1.SessionStream({ sessionId, agentId, projectId, mode: 'chat' });
     stream.connect((process.env.TEAMSHARE_WS_URL ?? WS_DEFAULT).replace(/\/$/, '') + '/agents', apiKey);
     const log = makeLog(stream);
     const api = new api_1.TeamshareApi(process.env.TEAMSHARE_API_URL, apiKey);
+    // PROJECT GUARD (IMP-6xx): hard-block chat sessions for projects without
+    // a linked local folder.
+    const cwd = resolveWorkingDir(flags, projectId, log);
+    if (!cwd)
+        return;
+    const settings = await fetchAgentSettings(api, agentId, log);
+    const harness = harnessOf(flags, settings);
+    applyOpenCodeKey(agentId, log, settings);
     const lock = await (0, lock_1.acquireLock)(agentId, 'chat', { projectId }, {
         onWaiting: (busy) => console.log(`[lock] agent ${agentId} is busy (pid ${busy.pid}, since ${busy.startedAt}, ${busy.kind}) - waiting for it to finish...`),
     });
@@ -373,22 +714,22 @@ async function cmdChat(flags) {
     }
     try {
         await (0, brief_1.reportStatus)(api, agentId, 'working', undefined, sessionId);
-        log(`[teamshare-agent] chat reply loop (project ${projectId}${mention ? `, mention @${mention}` : 'all mentions'})`);
+        log(`[teamshare-agent] chat reply loop (project ${projectId}${mention ? `, mention @${mention}` : 'all mentions'}) in ${cwd}`);
         const heartbeatTimer = setInterval(() => {
             void (0, brief_1.reportStatus)(api, agentId, 'working', undefined, sessionId);
         }, 60_000);
         try {
-            const endpoint = llmEndpoint(flags);
             const result = await (0, chat_reply_1.runChatReply)(api, agentId, projectId, mention, {
                 harness,
                 selfMode,
+                api,
                 echo: process.env.TS_CHAT_ECHO === '1',
                 llm: {
-                    baseUrl: endpoint.baseUrl,
-                    apiKey: process.env.LLM_API_KEY ?? '',
-                    model: endpoint.model,
-                    temperature: temperatureOf(flags),
-                    maxTokens: maxTokensOf(flags),
+                    baseUrl: (llmEndpoint(flags, settings)).baseUrl,
+                    apiKey: sessionLlmApiKey(settings),
+                    model: (llmEndpoint(flags, settings)).model,
+                    temperature: temperatureOf(flags, settings),
+                    maxTokens: maxTokensOf(flags, settings),
                 },
                 // Phase C: stream generated replies into the channel as drafts.
                 stream: {
@@ -396,7 +737,7 @@ async function cmdChat(flags) {
                     apiKey,
                     projectId,
                 },
-            });
+            }, targetId);
             log(`[done] replied to ${result.replied} mention${result.replied === 1 ? '' : 's'}` +
                 (result.skipped ? ` (${result.skipped} skipped)` : ''));
         }
@@ -414,6 +755,510 @@ async function cmdChat(flags) {
         await stream.end(exitCode);
     }
 }
+function buildStatePath(agentId, projectId) {
+    return (0, node_path_1.join)(BUILD_STATE_DIR, `${agentId}.${projectId}.json`);
+}
+function loadBuildState(agentId, projectId) {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(buildStatePath(agentId, projectId), 'utf8'));
+        return {
+            projectId,
+            skipped: Array.isArray(parsed.skipped) ? parsed.skipped : [],
+            done: Number.isFinite(parsed.done) ? parsed.done : 0,
+            updatedAt: parsed.updatedAt ?? new Date().toISOString(),
+        };
+    }
+    catch {
+        return { projectId, skipped: [], done: 0, updatedAt: new Date().toISOString() };
+    }
+}
+function saveBuildState(agentId, projectId, state) {
+    try {
+        (0, node_fs_1.mkdirSync)(BUILD_STATE_DIR, { recursive: true });
+        (0, node_fs_2.writeFileSync)(buildStatePath(agentId, projectId), JSON.stringify({ ...state, updatedAt: new Date().toISOString() }, null, 2));
+    }
+    catch {
+        /* best-effort - the in-memory state still drives this process */
+    }
+}
+function clearBuildState(agentId, projectId) {
+    try {
+        (0, node_fs_1.rmSync)(buildStatePath(agentId, projectId), { force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Stop file: the daemon writes it on build.stop; the loop honors + deletes it. */
+function stopFilePath(agentId) {
+    return (0, node_path_1.join)(STOP_DIR, `${agentId}.stop`);
+}
+function writeStopFile(agentId) {
+    try {
+        (0, node_fs_1.mkdirSync)(STOP_DIR, { recursive: true });
+        (0, node_fs_2.writeFileSync)(stopFilePath(agentId), new Date().toISOString(), 'utf8');
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function hasStopFile(agentId) {
+    return (0, node_fs_1.existsSync)(stopFilePath(agentId));
+}
+function clearStopFile(agentId) {
+    try {
+        (0, node_fs_1.rmSync)(stopFilePath(agentId), { force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** The `build` command: guard + lock + run loop (or --draft / --dry-run). */
+async function cmdBuild(flags) {
+    const agentId = need(flags, 'agent');
+    const apiKey = need(flags, 'key');
+    const projectId = need(flags, 'project');
+    const api = new api_1.TeamshareApi(process.env.TEAMSHARE_API_URL, apiKey);
+    const log = makeLog(null);
+    const settings = await fetchAgentSettings(api, agentId, log);
+    const harness = harnessOf(flags, settings);
+    let selfMode = flags.get('self') === 'true';
+    const modelSpec = modelOf(flags, settings);
+    const modelResolved = (0, models_1.resolveModel)(modelSpec, process.env.LLM_BASE_URL);
+    if (modelResolved.harnessOnly && selfMode) {
+        log(`[model] "${modelSpec}" is harness-native - switching from --self to harness mode`);
+        selfMode = false;
+    }
+    // --dry-run: print the queue, work nothing (no lock, no session).
+    if (flags.get('dry-run') === 'true') {
+        await cmdBuildDryRun(api, projectId, log);
+        return;
+    }
+    // --draft "<goal>": plan the queue first (creates ready-for-dev tasks).
+    const draftGoal = flags.get('draft');
+    if (draftGoal && draftGoal !== 'true') {
+        log(`[draft] planning the build queue for: ${draftGoal}`);
+        const planned = await draftBuildPlan({ api, agentId, projectId, settings, flags, log });
+        if (!planned) {
+            console.error('[draft] planning failed - see the log above');
+            process.exitCode = 1;
+            return;
+        }
+        if (flags.get('go') !== 'true') {
+            console.log('\nPlan created - the tasks are ready-for-dev and ordered.');
+            console.log('Run again with --go (or start the build from the app) to execute the queue.');
+            return;
+        }
+    }
+    // Project guard: resolve the working folder before any work.
+    const stream = new session_stream_1.SessionStream({ sessionId: flags.get('session') ?? (0, session_stream_1.newSessionId)(), agentId, mode: 'build', projectId });
+    const cwd = resolveWorkingDir(flags, projectId, log);
+    if (!cwd) {
+        process.exitCode = 1;
+        return;
+    }
+    // One agent at a time - wait for any in-flight session to finish.
+    const lock = await (0, lock_1.acquireLock)(agentId, 'build', { projectId }, {
+        onWaiting: (busy) => log(`[lock] agent ${agentId} is busy (pid ${busy.pid}, since ${busy.startedAt}, ${busy.kind}) - waiting for it to finish...`),
+    });
+    if (!lock) {
+        console.error(`[lock] gave up waiting for agent ${agentId} - try again later`);
+        process.exitCode = 1;
+        return;
+    }
+    let exitCode = 0;
+    const sessionId = stream.sessionId;
+    stream.connect((process.env.TEAMSHARE_WS_URL ?? WS_DEFAULT).replace(/\/$/, '') + '/agents', apiKey);
+    const ctx = { api, agentId, projectId, cwd, selfMode, harness, settings, flags, stream, sessionId, log };
+    try {
+        applyOpenCodeKey(agentId, log, settings);
+        exitCode = await runBuildLoop(ctx);
+    }
+    catch (err) {
+        log(`[build] fatal: ${(0, config_1.msg)(err)}`, 'stderr');
+        exitCode = 1;
+    }
+    finally {
+        clearStopFile(agentId);
+        (0, lock_1.releaseLock)(agentId);
+        await stream.end(exitCode);
+    }
+}
+/** Prints the current build queue without working anything (--dry-run). */
+async function cmdBuildDryRun(api, projectId, log) {
+    const queue = await api.getBuildQueue(projectId);
+    console.log(`Build queue for project ${queue.project.id} (${queue.project.name})`);
+    console.log(`build agent: ${queue.buildAgent ? queue.buildAgent.name : '(none assigned)'}`);
+    console.log('');
+    if (queue.pending.length === 0) {
+        console.log('pending: none (mark tasks ready-for-dev to add them to the queue)');
+    }
+    else {
+        console.log(`pending (${queue.pending.length}):`);
+        for (const item of queue.pending) {
+            const t = item.task;
+            console.log(`  #${item.position} ${t.title} (${t.priority}, ${t.status})`);
+        }
+    }
+    if (queue.blocked.length === 0) {
+        console.log('blocked: none');
+    }
+    else {
+        console.log(`blocked (${queue.blocked.length}) - waiting for answers:`);
+        for (const item of queue.blocked) {
+            console.log(`  - ${item.task.title}: ${item.question.body}`);
+        }
+    }
+}
+/** Plans the build queue for a goal: LLM creates ready tasks in order. */
+async function draftBuildPlan(ctx) {
+    const { api, agentId, projectId, settings, flags, log } = ctx;
+    const llmApiKey = sessionLlmApiKey(settings);
+    if (!llmApiKey) {
+        log('--draft requires a provider API key (set it on the agent in TeamShare, or LLM_API_KEY env)', 'stderr');
+        return '';
+    }
+    const endpoint = llmEndpoint(flags, settings);
+    log(`[draft] model ${endpoint.model} @ ${endpoint.baseUrl}`);
+    const goal = flags.get('draft') ?? '';
+    const project = await api.getProject(projectId).catch(() => null);
+    const prompt = `Plan the work for this goal and create the build queue for it NOW:\n\n` +
+        `"${goal}"\n\n` +
+        `Break the goal into 3-8 concrete, independently completable tasks. For each task:\n` +
+        `- create_task with readyForDev: true and a clear one-line title\n` +
+        `- set increasing sortOrder (1, 2, 3, ...) so the build works them strictly in order\n` +
+        `- assign it to yourself with assigneeId "me"\n` +
+        `- order dependencies first (a task that unblocks others comes before them)\n` +
+        `After creating them, reply with the ordered task list and the total count.`;
+    const reply = await (0, llm_1.runProjectSession)(api, projectId, prompt, {
+        baseUrl: endpoint.baseUrl,
+        apiKey: llmApiKey,
+        model: endpoint.model,
+        agentName: agentId,
+        systemPrompt: `You are the build planner for project ${project ? `"${project.name}" (${projectId})` : projectId} in TeamShare build mode.\n` +
+            'You turn a goal into an ordered, executable build queue. Create each task immediately with create_task ' +
+            '(readyForDev: true, sortOrder increasing, assigneeId "me"). Do NOT ask for confirmation first - the plan IS the deliverable.',
+        temperature: 0.2,
+        agentUserId: settings.userId ?? undefined,
+    }, project?.name);
+    log(`[draft] plan reply: ${reply}`);
+    return reply;
+}
+/**
+ * The build run loop: pending -> work -> done; failure -> skip + ask +
+ * continue; answered questions -> resume; empty queue -> finish. Progress is
+ * pushed to the backend after every transition. Exits 0 on a clean finish.
+ */
+async function runBuildLoop(ctx) {
+    const { api, agentId, projectId, cwd, selfMode, harness, settings, flags, stream, sessionId, log } = ctx;
+    const once = flags.get('once') === 'true';
+    const onFail = flags.get('on-fail') ?? 'ask';
+    const blockedWaitMin = Math.max(1, Number(flags.get('blocked-wait')) || 30);
+    let state = loadBuildState(agentId, projectId);
+    const queue = await api.getBuildQueue(projectId);
+    // Crash recovery: a fresh process re-seeds skipped tasks from blocked ones.
+    if (state.skipped.length === 0 && queue.blocked.length > 0) {
+        state.skipped = queue.blocked.map((b) => ({
+            taskId: b.task.id,
+            title: b.task.title,
+            askedAt: b.question.askedAt,
+        }));
+        saveBuildState(agentId, projectId, state);
+    }
+    log(`[build] queue: ${queue.pending.length} pending, ${queue.blocked.length} blocked, ${state.done} done, ${state.skipped.length} waiting`);
+    const push = (body) => {
+        const fresh = queue.pending.length + queue.blocked.length;
+        void api
+            .pushBuildProgress(agentId, {
+            projectId,
+            status: body.status,
+            total: state.done + fresh,
+            done: state.done,
+            remaining: fresh,
+            currentTaskId: body.currentTaskId,
+            currentTitle: body.currentTitle,
+            skippedTaskId: body.skippedTaskId,
+        })
+            .catch((err) => log(`[build] progress push failed: ${(0, config_1.msg)(err)}`, 'stderr'));
+    };
+    // Live heartbeat: keeps the agent marked working during long sessions.
+    let currentTaskId;
+    const heartbeatTimer = setInterval(() => {
+        void (0, brief_1.reportStatus)(api, agentId, 'working', currentTaskId, sessionId);
+    }, 60_000);
+    await (0, brief_1.reportStatus)(api, agentId, 'working', currentTaskId, sessionId);
+    try {
+        push({ status: 'running' });
+        for (;;) {
+            if (hasStopFile(agentId)) {
+                clearStopFile(agentId);
+                log('[build] stop requested - wrapping up');
+                push({ status: 'stopped' });
+                return 0;
+            }
+            const q = await api.getBuildQueue(projectId);
+            // 1) Strict order: work the first pending ready-for-dev task.
+            const next = q.pending[0];
+            if (next) {
+                currentTaskId = next.task.id;
+                push({ status: 'running', currentTaskId: next.task.id, currentTitle: next.task.title });
+                log(`[build] task ${next.position}/${q.pending.length + q.blocked.length + state.skipped.length}: "${next.task.title}"`);
+                const outcome = await workBuildTask(ctx, next.task);
+                if (outcome === 'done') {
+                    state.done += 1;
+                    saveBuildState(agentId, projectId, state);
+                    log(`[build] task completed (${state.done} done)`);
+                    push({ status: 'running' });
+                    if (once) {
+                        log('[build] --once: stopping after the first task');
+                        push({ status: 'finished' });
+                        return 0;
+                    }
+                    continue;
+                }
+                // Failure: skip + ask (or stop the run).
+                if (onFail === 'stop') {
+                    log(`[build] task "${next.task.title}" failed and --on-fail stop is set - stopping the run`, 'stderr');
+                    push({ status: 'stopped', skippedTaskId: next.task.id });
+                    return 0;
+                }
+                if (state.skipped.some((s) => s.taskId === next.task.id)) {
+                    log(`[build] task "${next.task.title}" failed again - re-asking`);
+                }
+                else {
+                    state.skipped.push({ taskId: next.task.id, title: next.task.title, askedAt: new Date().toISOString() });
+                }
+                saveBuildState(agentId, projectId, state);
+                await askBuildQuestion(api, projectId, next.task, ctx.log);
+                push({ status: 'running', skippedTaskId: next.task.id });
+                if (once) {
+                    log('[build] --once: stopping after the first task (skipped)');
+                    push({ status: 'stopped' });
+                    return 0;
+                }
+                continue;
+            }
+            // 2) No pending work - resume the first skipped task whose question
+            //    has been answered (open question gone = human answered).
+            let resumed = null;
+            for (const s of state.skipped) {
+                const qState = await api.getTaskQuestions(s.taskId).catch(() => ({ open: null }));
+                if (!qState.open) {
+                    resumed = { taskId: s.taskId, title: s.title };
+                    break;
+                }
+            }
+            if (resumed) {
+                currentTaskId = resumed.taskId;
+                log(`[build] resuming "${resumed.title}" (question answered)`);
+                const task = await api.getTask(resumed.taskId).catch(() => null);
+                if (task) {
+                    const outcome = await workBuildTask(ctx, task);
+                    if (outcome === 'done') {
+                        state.skipped = state.skipped.filter((s) => s.taskId !== resumed.taskId);
+                        state.done += 1;
+                        saveBuildState(agentId, projectId, state);
+                        log(`[build] resumed task completed (${state.done} done)`);
+                        push({ status: 'running' });
+                    }
+                    else if (!(await api.getTaskQuestions(resumed.taskId).catch(() => ({ open: null }))).open) {
+                        log(`[build] resumed task failed again - re-asking`);
+                        await askBuildQuestion(api, projectId, task, ctx.log);
+                    }
+                }
+                if (once) {
+                    log('[build] --once: stopping after the resumed task');
+                    push({ status: 'stopped' });
+                    return 0;
+                }
+                continue;
+            }
+            // 3) Nothing pending and skipped tasks are still waiting on answers.
+            if (state.skipped.length > 0) {
+                const deadline = Date.now() + blockedWaitMin * 60_000;
+                log(`[build] ${state.skipped.length} task(s) blocked on answers - waiting up to ${blockedWaitMin} min`);
+                push({ status: 'blocked' });
+                while (Date.now() < deadline) {
+                    if (hasStopFile(agentId)) {
+                        clearStopFile(agentId);
+                        log('[build] stop requested while blocked - exiting');
+                        push({ status: 'stopped' });
+                        return 0;
+                    }
+                    const q2 = await api.getBuildQueue(projectId);
+                    if (q2.pending.length > 0)
+                        break; // new ready task - loop and work it
+                    let answered = false;
+                    for (const s of state.skipped) {
+                        const qState = await api.getTaskQuestions(s.taskId).catch(() => ({ open: null }));
+                        if (!qState.open) {
+                            answered = true;
+                            break;
+                        }
+                    }
+                    if (answered)
+                        break;
+                    await new Promise((r) => setTimeout(r, 15_000));
+                }
+                continue; // re-evaluate: pending, answered, or still blocked (loops back)
+            }
+            // 4) Queue empty and nothing waiting - the run is finished.
+            push({ status: 'finished' });
+            log(`[build] queue finished - ${state.done} task(s) completed`);
+            clearBuildState(agentId, projectId);
+            try {
+                const channels = await api.listChatChannels(projectId);
+                const ch = channels.find((c) => c.name === AGENT_QUESTIONS_CHANNEL);
+                const target = ch ?? channels[0];
+                if (target) {
+                    await api.postChatMessage(projectId, `Build run finished: ${state.done} task(s) completed from the ready-for-dev queue.`, target.id);
+                }
+            }
+            catch (err) {
+                log(`[build] summary message failed: ${(0, config_1.msg)(err)}`, 'stderr');
+            }
+            return 0;
+        }
+    }
+    finally {
+        clearInterval(heartbeatTimer);
+        await (0, brief_1.reportStatus)(api, agentId, 'online', undefined, sessionId);
+    }
+}
+/** Works ONE build task to completion; returns 'done' or 'failed'. */
+async function workBuildTask(ctx, task) {
+    const { api, agentId, cwd, selfMode, harness, settings, flags, sessionId, log } = ctx;
+    const taskId = task.id;
+    ctx.stream.meta.taskId = taskId;
+    let claimed = false;
+    try {
+        const claim = await api.claimTask(taskId);
+        claimed = true;
+        log(`[claim] task ${taskId} claimed - lease until ${claim.claimExpiresAt}`);
+    }
+    catch (err) {
+        const e = err;
+        log(`[claim] cannot work task ${taskId}: ${e.message ?? e.code}`, 'stderr');
+        return 'failed';
+    }
+    await (0, brief_1.reportStatus)(api, agentId, 'working', taskId, sessionId);
+    try {
+        const brief = await (0, brief_1.fetchTaskBrief)(api, taskId);
+        const briefPath = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `teamshare-build-${taskId}.md`);
+        (0, node_fs_2.writeFileSync)(briefPath, brief, 'utf8');
+        log(`[brief] written to ${briefPath} (${brief.length} chars)`);
+        log('[brief] --- preview ---');
+        for (const line of brief.split('\n').slice(0, 18))
+            log(line);
+        log('[brief] --- end preview ---');
+        let summary = '';
+        if (selfMode) {
+            const llmApiKey = sessionLlmApiKey(settings);
+            if (!llmApiKey) {
+                log('--self requires a provider API key (set it on the agent in TeamShare, or LLM_API_KEY env)', 'stderr');
+                return 'failed';
+            }
+            const endpoint = llmEndpoint(flags, settings);
+            log(`[model] ${endpoint.model} @ ${endpoint.baseUrl}`);
+            const result = await (0, llm_1.runLlmSession)(api, taskId, brief, {
+                baseUrl: endpoint.baseUrl,
+                apiKey: llmApiKey,
+                model: endpoint.model,
+                agentName: agentId,
+                systemPrompt: systemPromptOf(flags, settings),
+                temperature: temperatureOf(flags, settings),
+                maxTokens: maxTokensOf(flags, settings),
+                continue: flags.get('continue') === 'true',
+                agentUserId: settings.userId ?? undefined,
+            }, task.projectId);
+            summary =
+                result.summary ||
+                    `Agent run finished after ${result.iterations} iterations (${result.tokensUsed} tokens).`;
+            log(`[session] done: ${result.finishedBy} | ${result.iterations} iterations | ${result.tokensUsed} tokens`);
+        }
+        else {
+            const systemPrompt = systemPromptOf(flags, settings);
+            const prompt = `Work on the TeamShare task described in ${briefPath} using the teamshare MCP tools. ` +
+                `This task is part of a BUILD RUN - complete it fully before finishing. ` +
+                `Break the task down first: create 3-8 subtasks with create_subtask, then check each off ` +
+                `(update_subtask with done: true) as you complete it. ` +
+                (settings.userId
+                    ? `Your TeamShare user id is ${settings.userId} - when a task or the brief asks you to assign a task to yourself, pass assigneeId "me" (resolves to your user id).\n`
+                    : '') +
+                (systemPrompt ? `Follow these instructions: ${systemPrompt}\n\n` : '') +
+                `Keep the human informed with progress comments on the task. When done, post a detailed ` +
+                `summary comment (mention the subtask progress) and move the task to in_review (or resolved if you are confident).`;
+            const exitCode = await spawnHarness(harness, prompt, log, {
+                model: modelOf(flags, settings),
+                temperature: temperatureOf(flags, settings),
+                cwd,
+                timeoutMin: sessionTimeoutMin(flags),
+                title: `TeamShare build task ${taskId} (agent ${agentId})`,
+                agentKey: api.apiKey,
+                apiBaseUrl: api.baseUrl,
+            });
+            summary = exitCode === 0 ? `Harness (${harness}) finished the session - see the task comments.` : `Harness (${harness}) exited with code ${exitCode} - see the task comments.`;
+        }
+        if (flags.get('no-report') !== 'true')
+            await (0, brief_1.postClosingComment)(api, taskId, summary);
+        const final = await (0, brief_1.waitForTaskCompletion)(api, taskId, 15_000, 15 * 60_000, (s) => log(`[status] ${s}`));
+        log(`[done] task ${taskId} final status: ${final.status}`);
+        return DONE_STATUSES.has(final.status) ? 'done' : 'failed';
+    }
+    catch (err) {
+        log(`[build] task ${taskId} errored: ${(0, config_1.msg)(err)}`, 'stderr');
+        return 'failed';
+    }
+    finally {
+        if (claimed) {
+            await api.releaseTask(taskId).catch(() => undefined);
+            log(`[claim] task ${taskId} released`);
+        }
+    }
+}
+/**
+ * Asks the team about a failed build task: a [question] comment on the task
+ * plus a message in the project's #agent-questions channel (both surfaces
+ * count as answerable per the backend). Skips when a question is already open.
+ */
+async function askBuildQuestion(api, projectId, task, log) {
+    try {
+        const current = await api.getTaskQuestions(task.id);
+        if (current.open) {
+            log(`[build] question already open for "${task.title}" - not re-asking`);
+            return;
+        }
+    }
+    catch {
+        /* fall through - ask anyway */
+    }
+    const body = `[question] Build could not complete task "${task.title}". ` +
+        `The session output is in the task comments - check them and reply here (or in #agent-questions) ` +
+        `with what the agent should do next. The build resumes this task automatically once you answer.`;
+    try {
+        await api.addComment({ taskId: task.id, body });
+        log(`[build] asked about "${task.title}" (task comment)`);
+    }
+    catch (err) {
+        log(`[build] question comment failed: ${(0, config_1.msg)(err)}`, 'stderr');
+    }
+    try {
+        const channels = await api.listChatChannels(projectId);
+        let channelId = channels.find((c) => c.name === AGENT_QUESTIONS_CHANNEL)?.id;
+        if (!channelId) {
+            const created = await api
+                .createChatChannel(projectId, AGENT_QUESTIONS_CHANNEL, 'Agent build questions - answering resumes the build')
+                .catch(() => null);
+            channelId = created?.id;
+        }
+        if (channelId) {
+            await api.postChatMessage(projectId, `Agent needs input on build task "${task.title}": check the task comments and reply - the build resumes automatically.`, channelId);
+        }
+    }
+    catch (err) {
+        log(`[build] #${AGENT_QUESTIONS_CHANNEL} message failed: ${(0, config_1.msg)(err)}`, 'stderr');
+    }
+}
 /** Picks the agent's next task from the inbox; returns its id or null. */
 async function pickNextTask(api, agentId, log) {
     const inbox = await api.inbox(agentId);
@@ -454,25 +1299,66 @@ function spawnHarness(harness, prompt, log, settings = {}) {
     }
     log(`[harness] launching ${chosen}...`);
     const cmd = chosen === 'opencode' ? 'opencode' : 'claude';
-    const args = chosen === 'opencode'
-        ? [
-            'run',
-            ...(settings.model ? ['--model', settings.model] : []),
-            ...(settings.temperature !== undefined
-                ? ['--temperature', String(settings.temperature)]
-                : []),
-            prompt,
-        ]
-        : ['-p', prompt];
+    const args = [];
+    if (chosen === 'opencode') {
+        args.push('run');
+        // Non-interactive runs must not stall on permission prompts: without
+        // --auto, opencode auto-REJECTS any unapproved tool call (MCP tools
+        // like create_subtask, reads outside the working folder) and then sits
+        // idle at the prompt forever. The working folder is guard-pinned and
+        // the run is kill-switched (--session-timeout), so --auto is safe here.
+        args.push('--auto');
+        // opencode's --model expects `provider/model` ids; TeamShare catalog
+        // ids (`provider:model`) are for the --self loop - only pass ids that
+        // opencode itself understands (e.g. opencode-go/deepseek-v4-flash) and
+        // never pass flags opencode does not support (--temperature) - both
+        // made opencode print its help and exit 1 on Windows.
+        if (settings.model && settings.model.includes('/')) {
+            args.push('--model', settings.model);
+        }
+        // Spend attribution: every bridge session records a queryable title so
+        // `teamshare-agent usage` can split agent work from the user's windows.
+        if (settings.title) {
+            args.push('--title', settings.title);
+        }
+        args.push(prompt);
+    }
+    else {
+        args.push('-p', prompt);
+    }
     const env = chosen === 'claude' && settings.model
         ? { ...process.env, ANTHROPIC_MODEL: settings.model }
         : undefined;
+    // Pin the opencode teamshare MCP server to THIS agent's key: the user's
+    // global opencode config carries one shared key (BridgeAgent), so without
+    // this override every agent would act as BridgeAgent inside the harness.
+    let mcpOverride = null;
+    if (chosen === 'opencode' && settings.agentKey) {
+        mcpOverride = (0, harness_1.writeOpencodeMcpConfig)(settings.agentKey, settings.apiBaseUrl ?? process.env.TEAMSHARE_API_URL ?? 'http://localhost:4000/api');
+    }
+    // Windows: spawn a single fully-quoted command through the shell.
+    // `spawn(exe, args, { shell: true })` joins the args WITHOUT quoting, so
+    // cmd word-splits the prompt and opencode prints help + exits 1.
+    const quote = (a) => /[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a;
+    const command = [cmd, ...args.map(quote)].join(' ');
     return new Promise((resolve) => {
-        const child = (0, node_child_process_1.spawn)(cmd, args, {
-            shell: process.platform === 'win32',
+        const child = (0, node_child_process_1.spawn)(command, {
+            shell: true,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env,
+            env: mcpOverride
+                ? { ...(env ?? process.env), OPENCODE_CONFIG: mcpOverride.file }
+                : env,
+            cwd: settings.cwd,
         });
+        // Kill-switch: a runaway harness must never burn usage forever. The
+        // cap defaults to 60 minutes and is settable per run (--session-timeout)
+        // or globally (TEAMSHARE_SESSION_TIMEOUT_MIN).
+        const timeoutMs = Math.max(1, settings.timeoutMin ?? 60) * 60_000;
+        const killTimer = setTimeout(() => {
+            log(`[harness] ${cmd} killed after ${settings.timeoutMin ?? 60} min (session timeout cap)`, 'stderr');
+            child.kill();
+            resolve(124);
+        }, timeoutMs);
         const tee = (chunk, level) => {
             for (const line of chunk.toString('utf8').split(/\r?\n/)) {
                 if (line.trim())
@@ -482,10 +1368,14 @@ function spawnHarness(harness, prompt, log, settings = {}) {
         child.stdout?.on('data', (c) => tee(c, 'stdout'));
         child.stderr?.on('data', (c) => tee(c, 'stderr'));
         child.on('error', (err) => {
+            clearTimeout(killTimer);
+            mcpOverride?.cleanup();
             log(`[harness] ${cmd} failed to start: ${(0, config_1.msg)(err)}`, 'stderr');
             resolve(1);
         });
         child.on('close', (code) => {
+            clearTimeout(killTimer);
+            mcpOverride?.cleanup();
             if (code !== 0)
                 log(`[harness] ${cmd} exited with code ${code ?? 'error'}`, 'stderr');
             resolve(code ?? 1);
@@ -497,6 +1387,140 @@ function hasBin(bin) {
     const res = spawnSync(bin, ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' });
     return res.status === 0;
 }
+async function cmdSkills(action) {
+    if (action === 'list') {
+        const { available, installed, target } = (0, skills_1.listSkills)();
+        console.log(`Skills directory: ${target}`);
+        console.log(`Shipped with this bridge: ${available.join(', ') || '(none found)'}`);
+        console.log(`Installed: ${installed.join(', ') || '(none - run "teamshare-agent skills install")'}`);
+        return;
+    }
+    if (action === 'install') {
+        const { copied, target } = (0, skills_1.installSkills)();
+        console.log(`[skills] installed ${copied.join(', ') || '(nothing to copy)'} -> ${target}`);
+        return;
+    }
+    if (action === 'uninstall') {
+        const { removed, target } = (0, skills_1.uninstallSkills)();
+        console.log(`[skills] removed ${removed.join(', ') || '(nothing installed)'} from ${target}`);
+        return;
+    }
+    console.error('skills requires one of: install | list | uninstall');
+    process.exitCode = 2;
+}
+/**
+ * `key` - manage the LLM provider key agents use to run their harness.
+ * Without --agent the key is the GLOBAL default for every agent; with
+ * --agent it overrides that agent only. Keys are never printed in full.
+ */
+async function cmdMcp(flags, action) {
+    const action2 = action ?? 'status';
+    const config = (0, config_1.loadConfig)();
+    const apiKey = flags.get('key') ?? config.agents[0]?.apiKey ?? '';
+    if (action2 === 'wire') {
+        if (!apiKey) {
+            console.error('mcp wire requires --key <agentApiKey> or a configured agent');
+            process.exitCode = 2;
+            return;
+        }
+        const wired = (0, config_1.wireOpencodeMcp)(apiKey);
+        console.log(wired
+            ? '[mcp] wired TeamShare MCP into opencode.jsonc — agent now has 21 tools'
+            : '[mcp] TeamShare MCP already wired — skipping');
+        return;
+    }
+    if (action2 === 'unwire') {
+        const removed = (0, config_1.unwireOpencodeMcp)();
+        console.log(removed
+            ? '[mcp] removed TeamShare MCP from opencode.jsonc'
+            : '[mcp] TeamShare MCP not found in opencode.jsonc — nothing to remove');
+        return;
+    }
+    // status
+    const status = (0, config_1.mcpStatus)();
+    console.log('TeamShare MCP in opencode:');
+    console.log(status.configPath
+        ? `  config : ${status.configPath}`
+        : '  config : opencode.jsonc not found');
+    console.log(status.wired
+        ? `  status: WIRED — agent has 21 TeamShare tools (create_task, list_tasks, search, etc.)`
+        : '  status: NOT WIRED — agent has no TeamShare tools in opencode sessions');
+    if (status.wired) {
+        const entry = status.entry;
+        console.log(`  url   : ${entry?.url ?? 'n/a'}`);
+        const key = entry?.headers?.['X-Api-Key'] ?? '';
+        console.log(`  key   : ${key ? key.slice(0, 8) + '...' : 'n/a'}`);
+    }
+}
+async function cmdKey(flags, action) {
+    const agentId = flags.get('agent');
+    const chatFlag = flags.get('chat') === 'true';
+    const action2 = action ?? 'show';
+    if (action2 === 'set') {
+        const key = flags.get('key') ?? flags.get('set');
+        if (!key) {
+            console.error('key set requires --key <providerApiKey> [--agent <agentId>] [--chat]');
+            process.exitCode = 2;
+            return;
+        }
+        try {
+            if (chatFlag) {
+                (0, config_1.setChatKey)(key);
+                console.log(`[key] stored chat model key (${key.slice(0, 8)}...) - chat replies use deepseek:deepseek-chat at temp 0.1`);
+            }
+            else {
+                (0, config_1.setOpenCodeKey)(key, agentId ?? undefined);
+                console.log(agentId
+                    ? `[key] stored agent-specific LLM key for agent ${agentId} (${key.slice(0, 8)}...)`
+                    : `[key] stored global agent LLM key (${key.slice(0, 8)}...) - all agents use it unless overridden`);
+            }
+        }
+        catch (err) {
+            console.error(`[key] ${(0, config_1.msg)(err)}`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (action2 === 'clear') {
+        if (chatFlag) {
+            (0, config_1.setChatKey)(null);
+            console.log('[key] cleared the chat model key (chat falls back to LLM_API_KEY env)');
+        }
+        else {
+            (0, config_1.setOpenCodeKey)(null, agentId ?? undefined);
+            console.log(agentId
+                ? `[key] cleared agent-specific LLM key for ${agentId} (falls back to the global key or your default credentials)`
+                : '[key] cleared the global agent LLM key (agents fall back to your default credentials)');
+        }
+        return;
+    }
+    // show
+    const config = (0, config_1.loadConfig)();
+    const global = config.opencodeKey;
+    console.log('LLM provider keys for agent harness runs:');
+    console.log(global
+        ? `  global      : set (${global.slice(0, 8)}...) - all agents unless overridden`
+        : '  global      : not set - agents fall back to your default credentials');
+    console.log(process.env.OPENCODE_API_KEY
+        ? '  env         : OPENCODE_API_KEY set (wins over config)'
+        : '  env         : not set');
+    for (const agent of config.agents) {
+        console.log(agent.opencodeKey
+            ? `  ${agent.agentId} : agent-specific (${agent.opencodeKey.slice(0, 8)}...)`
+            : `  ${agent.agentId} : using global/default`);
+    }
+    // chat key
+    const chatKeyVal = config.chatKey;
+    console.log('\nChat model key (chat replies — deepseek:deepseek-chat at temp 0.1):');
+    console.log(chatKeyVal
+        ? `  config      : set (${chatKeyVal.slice(0, 8)}...)`
+        : '  config      : not set');
+    console.log(process.env.CHAT_LLM_API_KEY
+        ? '  env CHAT_LLM_API_KEY : set (wins over config)'
+        : process.env.LLM_API_KEY
+            ? '  env LLM_API_KEY      : set (fallback)'
+            : '  env         : not set');
+}
 async function main() {
     const { flags, positionals } = parseArgs(process.argv.slice(2));
     if (flags.has('help') || positionals.length === 0) {
@@ -507,6 +1531,10 @@ async function main() {
     try {
         if (command === 'connect')
             await cmdConnect(flags);
+        else if (command === 'link')
+            await cmdLink(flags);
+        else if (command === 'unlink')
+            await cmdUnlink(flags);
         else if (command === 'run')
             await cmdRun(flags);
         else if (command === 'continue') {
@@ -523,6 +1551,16 @@ async function main() {
             await cmdChat(flags);
         else if (command === 'doc')
             await cmdDoc(flags);
+        else if (command === 'build')
+            await cmdBuild(flags);
+        else if (command === 'usage')
+            await cmdUsage(flags);
+        else if (command === 'skills')
+            await cmdSkills(positionals[1]);
+        else if (command === 'key')
+            await cmdKey(flags, positionals[1]);
+        else if (command === 'mcp')
+            await cmdMcp(flags, positionals[1]);
         else {
             console.error(`Unknown command: ${command}`);
             console.log(usage());