@motionode/cli 0.1.2 → 0.2.1

package/README.md

@@ -22,3 +22,50 @@ motionode finish T11-518   # Motionode checks your pushed commits and moves the
   never arbitrary commands.
 - `motionode use <url>` points every terminal at another Motionode API until `motionode use production`; `--api URL` or `MOTIONODE_API_URL` overrides it for one run. `motionode where` shows the current one.
 - Revoke a computer in Motionode → Settings → Development workflow.
+
+## Repositories Motionode hosts
+
+A repository Motionode hosts lives privately in Motionode's GitHub, so your own
+GitHub account does not reach it. Clone it through Motionode instead (0.2.0+):
+
+```sh
+motionode connect                          # once per computer
+motionode clone acme/orders-api            # or the service's name: motionode clone "Orders API"
+```
+
+- The clone talks to Motionode's git proxy, and this CLI is that folder's git
+  credential helper (`motionode git-credential`), set in the clone's own git
+  config only. Plain git, Cursor, VS Code and Claude Code then just work there.
+- Each sign-in is short-lived and opens one repository. It needs a development
+  step on the project, and you can revoke it in Settings → Development workflow →
+  Git access, or by disconnecting the computer.
+- Pushes go only to the branch of a ticket you are working locally
+  (`motionode work <ticket>`); main, staging, tags and deletes are refused.
+
+## Coding agents (Claude Code, Cursor, any MCP client)
+
+Let your own agent work Motionode tickets as a first-class worker. It reads the
+ticket and its acceptance criteria, reports progress and asks questions. Requirement
+changes, overlaps and failed checks reach it between steps.
+
+```sh
+motionode mcp install --claude-code   # adds the Motionode MCP server (.mcp.json) and signal hooks (.claude/settings.json)
+motionode signals watch               # keep running: signals land in .motionode/inbox.json the moment they happen
+```
+
+- **MCP tools:** `my_work`, `get_ticket`, `get_signals`, `ack_signal` (with `incorporated` once your work reflects it),
+  `start_step`, `report_progress`, `ask_question`, `report_discovery`, `request_review`.
+  Every call acts as you, with the same permissions as the web app.
+- **Coordination records** (several agents, one person's token):
+  - `claim_step` / `release_step`: an exclusive, leased claim on the ticket's current step; other workers see who holds it.
+    Name each agent (`motionode mcp install --claude-code --agent opus5`, or `MOTIONODE_AGENT=opus5`) -- claiming needs it.
+  - `report_observation` (a symptom + evidence), `report_finding` (a cause; `verified`, `root_cause`),
+    `link_observation` and `relate_work` (coordinator/manager: one root cause, duplicates, what else it affects).
+  - `ask_decision` / `choose_decision` (an owner, options, a due time), `report_blocker` (Waiting, on a ticket or a decision).
+  - `submit_evidence`: `fails_without`, `suite_baseline`, `preview_check`, `tester_recheck` -- bound to a commit; the
+    answer carries the ticket's readiness (built → verified → integrated → released).
+- **Hooks** (no model, no network; they read the local inbox):
+  - After each tool call and on each prompt, pending signals are added to the agent's context.
+  - When the agent tries to finish while a signal that needs action is unacknowledged, it is asked once to handle it first.
+- `motionode signals pending` shows what is waiting.
+- Instead of a connected computer, you can set a personal access token (create one in Settings) in `MOTIONODE_TOKEN`.

package/bin/motionode.js

@@ -9,8 +9,11 @@ const { version } = require('../lib/api');
 const HELP = `motionode ${version} — work Motionode tickets with your own local tools
 
   motionode connect [--api URL] [--name NAME]   connect this computer (once) and link the current repo
-  motionode link [--service UUID]               link the current repository folder to a Motionode repository
+  motionode link [--service UUID] [--worktrees] link the current repository folder to a Motionode repository
+                                                (--worktrees: each ticket gets its own folder next to it)
   motionode unlink                              unlink the current folder
+  motionode clone <service | owner/repo> [dir]  clone a Motionode-hosted repository through Motionode (no GitHub
+                                                access needed: this computer's connection signs git in)
   motionode dev                                 keep Motionode in sync (branches, local changes, commit requests)
   motionode work <ticket>                       start a ticket locally and check out its branches (e.g. T11-518)
   motionode finish <ticket> [--force] [--note]  you're done: Motionode checks your pushed commits and moves it on
@@ -19,7 +22,27 @@ const HELP = `motionode ${version} — work Motionode tickets with your own loca
   motionode use <url|production>                switch which Motionode the CLI talks to (remembered)
   motionode logout                              disconnect this computer
 
-Git stays yours: fetch, commit and push use your own git credentials and identity.
+For coding agents (Claude Code, Cursor, any MCP client):
+  motionode mcp                                 run the Motionode MCP server (stdio) for your agent
+  motionode mcp install --claude-code           add the MCP server and signal hooks to this repo's Claude Code settings
+                        [--agent <name>]        name this agent (MOTIONODE_AGENT) so its claims say who holds a step
+  motionode signals watch                       keep one connection open; Motionode signals land in .motionode/inbox.json
+  motionode signals pending                     what is waiting for this repository
+
+Project work and notes (as you; --project <uuid or name>, or MOTIONODE_PROJECT):
+  motionode deliverables                        the project's deliverables
+  motionode work-item create --title T          file a work item (in setup, nothing starts); --description D or
+        [--deliverable R2-1 | --new-deliverable N]  --description-file F, --criteria "a | b", --confirmed-new when
+                                                open work with the same title already exists
+  motionode work-item update <code>             change its --title and/or --description (or --description-file),
+                                                as you (needs edit rights on the project)
+  motionode notes list | get <uuid> [--html]    the project notes you may read
+  motionode notes create --file F.md            a note from markdown (--deliverable R or --ticket T: a team note;
+        [--share a@x,b@y] [--category C]         else a board note shared with the people named)
+  motionode notes update <uuid> --file F.md     replace a note you wrote or that is shared with you
+
+Git stays yours: fetch, commit and push use your own git credentials and identity. A Motionode-hosted repository
+cloned with "motionode clone" signs in through this computer's Motionode connection instead (short-lived, one repo).
 Talks to production (https://api.motionode.com) unless "motionode use", MOTIONODE_API_URL or --api says otherwise;
 each Motionode keeps its own connection.`;
 
@@ -41,6 +64,13 @@ function flags(argv) {
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
 	const args = flags(rest);
+	/**
+	 * A server named for `connect` is the one this computer keeps using: the work
+	 * panel prints `motionode connect --api …` once, and every command after it
+	 * must stay on that Motionode rather than fall back to production
+	 * (QA-20261023T234000Z).
+	 */
+	if (command === 'connect' && typeof args.api === 'string') Config.useApi(args.api);
 	// --api (or MOTIONODE_API_URL) picks the Motionode — and its own saved connection.
 	const config = Config.load(typeof args.api === 'string' ? args.api : null);
 	switch (command) {
@@ -49,9 +79,14 @@ async function main() {
 		case 'login':
 			return Commands.login(config, { apiUrl: args.api || null, name: args.name || null });
 		case 'link':
-			return Commands.link(config, { serviceUuid: args.service || null });
+			return Commands.link(config, { serviceUuid: args.service || null, worktrees: !!args.worktrees });
 		case 'unlink':
 			return Commands.unlink(config);
+		case 'clone':
+			return require('../lib/git_credential').clone(config, args._[0], args._[1] || null);
+		case 'git-credential':
+			// git runs this as a clone's credential helper (see lib/git_credential).
+			return require('../lib/git_credential').helper(config, args._[0]);
 		case 'dev':
 			return Bridge.run(config);
 		case 'work':
@@ -71,6 +106,23 @@ async function main() {
 			return null;
 		case 'logout':
 			return Commands.logout(config);
+		case 'mcp':
+			if (args._[0] === 'install') return require('../lib/agent_setup').install(config, { claudeCode: !!args['claude-code'] || !args.cursor, cursor: !!args.cursor, agent: typeof args.agent === 'string' ? args.agent : null });
+			return require('../lib/mcp').serve(config);
+		case 'signals': {
+			const sub = args._[0] || 'pending';
+			if (sub === 'watch') return require('../lib/signals_watch').watch(config, { quiet: !!args.quiet });
+			if (sub === 'hook') return require('../lib/signals_hook').run(args._[1] || 'PostToolUse');
+			return require('../lib/signals_hook').printPending();
+		}
+		case 'deliverables':
+			return require('../lib/project_cmds').deliverables(config, args);
+		case 'work-item':
+			if (args._[0] === 'update') return require('../lib/project_cmds').updateWorkItem(config, args);
+			if (args._[0] !== 'create') throw new Error('Usage: motionode work-item create --project P --title T [...] | work-item update <code> --project P [--title T] [--description D | --description-file F]');
+			return require('../lib/project_cmds').createWorkItem(config, args);
+		case 'notes':
+			return require('../lib/project_cmds').notes(config, args);
 		case '--version':
 		case '-v':
 			console.log(version);

package/lib/agent_api.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * Client for Motionode's /api/v1/agent — what an external coding agent (Claude
+ * Code, Cursor) uses to read its tickets and exchange signals. Same machine token
+ * as the rest of the CLI (or MOTIONODE_TOKEN, a personal access token).
+ */
+
+const pkg = require('../package.json');
+
+class AgentApiError extends Error {
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+	}
+}
+
+/**
+ * This agent's name (MOTIONODE_AGENT, e.g. "opus5"), sent as X-Motionode-Client on every call so Motionode can tell
+ * several agents acting as the same person apart: each is its own session and holds its own claims. Claiming a step
+ * needs it. `motionode mcp install --agent <name>` writes it into .mcp.json.
+ */
+function agentName() {
+	const name = String(process.env.MOTIONODE_AGENT || '').trim().slice(0, 80);
+	return name || null;
+}
+
+function agentHeaders() {
+	const name = agentName();
+	return name ? { 'X-Motionode-Client': name } : {};
+}
+
+function agentClient(config) {
+	const base = String(config.apiUrl || '').replace(/\/+$/, '');
+	const token = process.env.MOTIONODE_TOKEN || config.token || null;
+	async function request(method, pathname, body = null, { timeoutMs = 60000 } = {}) {
+		if (!token) throw new AgentApiError('Not connected. Run "motionode connect" (or set MOTIONODE_TOKEN).', 401);
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		let resp;
+		try {
+			resp = await fetch(`${base}/api/v1/agent${pathname}`, {
+				method,
+				headers: {
+					'Content-Type': 'application/json',
+					'User-Agent': `motionode-cli/${pkg.version}`,
+					Authorization: `Bearer ${token}`,
+					...agentHeaders(),
+				},
+				body: body ? JSON.stringify(body) : undefined,
+				signal: controller.signal,
+			});
+		} catch (err) {
+			if (err.name === 'AbortError') throw new AgentApiError('Motionode did not answer in time.', 0);
+			throw new AgentApiError(`Could not reach Motionode at ${base}: ${err.message}`, 0);
+		} finally {
+			clearTimeout(timer);
+		}
+		let data = null;
+		try { data = await resp.json(); } catch (_e) { data = null; }
+		if (!resp.ok || data?.ok === false) {
+			// A real {ok:false} failure can arrive with HTTP 200 (the body carries the
+			// outcome) -- "Motionode answered 200." reads like success, not a refusal.
+			const message = data?.error
+				|| (data?.ok === false ? `Motionode refused: ${resp.status}` : `Motionode answered ${resp.status}.`);
+			throw new AgentApiError(message, resp.status);
+		}
+		return data || {};
+	}
+	return {
+		base,
+		token,
+		get: (p, opts) => request('GET', p, null, opts),
+		post: (p, body, opts) => request('POST', p, body || {}, opts),
+		patch: (p, body, opts) => request('PATCH', p, body || {}, opts),
+	};
+}
+
+module.exports = { agentClient, agentName, agentHeaders, AgentApiError };

package/lib/agent_setup.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * `motionode mcp install [--claude-code] [--cursor]`: wire this repository for a coding agent.
+ *   .mcp.json              → the Motionode MCP server (stdio: `motionode mcp`)
+ *   .claude/settings.json  → Claude Code hooks that surface Motionode signals at safe points
+ *   .cursor/mcp.json       → the Motionode MCP server for Cursor (no hooks -- Cursor has none)
+ * Merges into existing files (never removes anything): a file that doesn't exist yet is created;
+ * a file that exists but fails to parse as JSON stops the install instead of being silently
+ * overwritten with an empty object.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Inbox = require('./inbox');
+
+/** Existing, valid JSON -> parsed. Missing file -> {}. Existing but invalid JSON -> throws (never silently drops it). */
+function readJson(file) {
+	let raw;
+	try {
+		raw = fs.readFileSync(file, 'utf8');
+	} catch (err) {
+		if (err.code === 'ENOENT') return {};
+		throw err;
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (_e) {
+		throw new Error(`${file} isn't valid JSON — fix it or remove it, then run again`);
+	}
+}
+
+function writeJson(file, value) {
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function addHook(settings, event, matcher, command) {
+	settings.hooks = settings.hooks || {};
+	const list = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+	const exists = list.some((entry) => (entry.hooks || []).some((h) => h.command === command));
+	if (!exists) list.push({ matcher, hooks: [{ type: 'command', command }] });
+	settings.hooks[event] = list;
+}
+
+function install(config, { claudeCode = true, cursor = false, agent = null } = {}) {
+	// --agent <name>: this agent's name for Motionode (X-Motionode-Client), so claims say who holds a step.
+	const env = agent ? { env: { MOTIONODE_AGENT: String(agent).trim().slice(0, 80) } } : {};
+	const root = Inbox.repoRoot(process.cwd());
+	const written = [];
+
+	const mcpFile = path.join(root, '.mcp.json');
+	const mcp = readJson(mcpFile);
+	mcp.mcpServers = mcp.mcpServers || {};
+	mcp.mcpServers.motionode = { type: 'stdio', command: 'motionode', args: ['mcp'], ...env };
+	writeJson(mcpFile, mcp);
+	written.push(path.relative(process.cwd(), mcpFile) || '.mcp.json');
+
+	if (claudeCode) {
+		const settingsFile = path.join(root, '.claude', 'settings.json');
+		const settings = readJson(settingsFile);
+		addHook(settings, 'PostToolUse', '*', 'motionode signals hook PostToolUse');
+		addHook(settings, 'UserPromptSubmit', '', 'motionode signals hook UserPromptSubmit');
+		addHook(settings, 'Stop', '', 'motionode signals hook Stop');
+		writeJson(settingsFile, settings);
+		written.push(path.relative(process.cwd(), settingsFile));
+	}
+
+	if (cursor) {
+		// Cursor has no hook system -- just the MCP server, in its own config file.
+		const cursorFile = path.join(root, '.cursor', 'mcp.json');
+		const cursorConfig = readJson(cursorFile);
+		cursorConfig.mcpServers = cursorConfig.mcpServers || {};
+		cursorConfig.mcpServers.motionode = { command: 'motionode', args: ['mcp'], ...env };
+		writeJson(cursorFile, cursorConfig);
+		written.push(path.relative(process.cwd(), cursorFile));
+	}
+
+	Inbox.ensureExcluded(root);
+	for (const file of written) console.log(`✓ Wrote ${file}`);
+	if (claudeCode) console.log('✓ Claude Code hooks added to .claude/settings.json (signals reach your agent between steps)');
+	if (cursor) console.log('✓ Cursor MCP server added to .cursor/mcp.json (no hooks -- Cursor has none; signals still reach it through "motionode signals watch")');
+	console.log(`Next: keep "motionode signals watch" running in a terminal for this repository${config?.token ? '' : ', after "motionode connect"'}.`);
+}
+
+module.exports = { install, addHook, readJson, writeJson };

package/lib/bridge.js

@@ -9,6 +9,7 @@
  */
 
 const Git = require('./git');
+const { worktreePath } = require('./commands');
 const { client } = require('./api');
 const { version } = require('./api');
 
@@ -27,6 +28,7 @@ async function collect(config) {
 			out.push({
 				serviceUuid: ws.serviceUuid,
 				path: ws.path,
+				worktrees: !!ws.worktrees,
 				remoteUrl: await Git.remoteUrl(ws.path),
 				branch: st.branch,
 				headSha: st.headSha,
@@ -35,7 +37,7 @@ async function collect(config) {
 				dirtyFiles: st.dirtyFiles,
 			});
 		} catch (err) {
-			out.push({ serviceUuid: ws.serviceUuid, path: ws.path, gitError: err.message });
+			out.push({ serviceUuid: ws.serviceUuid, path: ws.path, worktrees: !!ws.worktrees, gitError: err.message });
 		}
 	}
 	return out;
@@ -50,6 +52,18 @@ async function runJob(config, job) {
 	const ws = workspaceFor(config, payload.serviceUuid);
 	if (!ws) throw new Error(`No folder on this computer is linked to ${payload.serviceName || 'that repository'}. Run \`motionode link\` in it.`);
 	if (job.kind === 'checkout') {
+		/**
+		 * In --worktrees mode `motionode work` owns the ticket's branch in its own
+		 * folder, so checking it out in the linked folder conflicts with that
+		 * worktree (QA-20261023T235400Z). Create/reuse the same folder instead.
+		 */
+		if (ws.worktrees && payload.ticketDisplayId) {
+			const dir = worktreePath(ws, payload.ticketDisplayId);
+			const wt = await Git.worktreeFor(ws.path, payload.branch, dir);
+			log(`checked out ${payload.branch} in ${wt.path}`);
+			const st = await Git.status(wt.path);
+			return { branch: st.branch, headSha: st.headSha, path: wt.path };
+		}
 		const st = await Git.checkout(ws.path, payload.branch);
 		log(`checked out ${payload.branch} in ${ws.path}`);
 		return { branch: st.branch, headSha: st.headSha };

package/lib/commands.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const os = require('os');
+const path = require('path');
 const readline = require('readline');
 const { execFile } = require('child_process');
 const Config = require('./config');
@@ -13,6 +14,8 @@ function ask(question) {
 }
 
 function openBrowser(url) {
+	// Headless/SSH sessions: the printed URL and code are enough.
+	if (process.env.MOTIONODE_NO_BROWSER) return;
 	const cmd = process.platform === 'win32' ? 'cmd' : (process.platform === 'darwin' ? 'open' : 'xdg-open');
 	const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
 	execFile(cmd, args, { windowsHide: true }, () => {});
@@ -50,7 +53,7 @@ async function login(config, { name = null } = {}) {
 }
 
 /** Link the current folder to a Motionode repository (matched by its git remote when possible). */
-async function link(config, { serviceUuid = null, dir = process.cwd() } = {}) {
+async function link(config, { serviceUuid = null, dir = process.cwd(), worktrees = false } = {}) {
 	const root = await Git.isRepo(dir);
 	if (!root) throw new Error('This folder is not a git repository. Run `motionode link` inside your clone.');
 	const api = client(config);
@@ -62,8 +65,26 @@ async function link(config, { serviceUuid = null, dir = process.cwd() } = {}) {
 	if (!services.length) throw new Error('You have no projects with AI building enabled to work on locally.');
 	let pick = serviceUuid ? services.find((s) => s.uuid === serviceUuid) : null;
 	if (!pick) {
-		const remote = Git.normalizeRepoUrl(await Git.remoteUrl(root));
-		const matches = remote ? services.filter((s) => Git.normalizeRepoUrl(s.repoUrl) === remote) : [];
+		const remoteUrl = await Git.remoteUrl(root);
+		const remote = Git.normalizeRepoUrl(remoteUrl);
+		/**
+		 * A clone made with `motionode clone` has this Motionode's git proxy as its
+		 * remote, not GitHub's URL; recognize the repository behind it instead of
+		 * asking the person to choose what they just cloned
+		 * (QA-20261023T234000Z).
+		 */
+		const { proxiedRepoOf, ownerRepoOf } = require('./git_credential');
+		const proxied = proxiedRepoOf(config, remoteUrl);
+		const sameRepo = (repoUrl) => {
+			if (!proxied || !repoUrl) return false;
+			const ref = ownerRepoOf(repoUrl);
+			return !!ref
+				&& ref.owner.toLowerCase() === proxied.owner.toLowerCase()
+				&& ref.repo.toLowerCase() === proxied.repo.toLowerCase();
+		};
+		const matches = remote
+			? services.filter((s) => Git.normalizeRepoUrl(s.repoUrl) === remote || sameRepo(s.repoUrl))
+			: [];
 		if (matches.length === 1) pick = matches[0];
 		else {
 			const list = matches.length ? matches : services;
@@ -77,6 +98,7 @@ async function link(config, { serviceUuid = null, dir = process.cwd() } = {}) {
 	config.workspaces = (config.workspaces || []).filter((w) => !Config.samePath(w.path, root) && w.serviceUuid !== pick.uuid);
 	config.workspaces.push({
 		path: root,
+		worktrees: !!worktrees,
 		serviceUuid: pick.uuid,
 		serviceName: pick.name,
 		projectUuid: pick.projectUuid,
@@ -84,11 +106,21 @@ async function link(config, { serviceUuid = null, dir = process.cwd() } = {}) {
 	});
 	Config.save(config);
 	console.log(`✓ ${root} → ${pick.projectName} / ${pick.name}`);
+	if (worktrees) console.log('  Each ticket you start gets its own folder next to this one (git worktree), so tickets never share a working tree.');
 	return pick;
 }
 
 async function connect(config, opts = {}) {
-	if (!config.token || opts.relogin) await login(config, opts);
+	let relogin = !config.token || opts.relogin;
+	if (!relogin) {
+		// A computer revoked in Motionode keeps its old token here; connecting again must replace it.
+		try { await client(config).get('/me'); } catch (err) {
+			if (err.status !== 401) throw err;
+			console.log('This computer was disconnected from Motionode — connecting it again.');
+			relogin = true;
+		}
+	}
+	if (relogin) await login(config, opts);
 	if (await Git.isRepo(process.cwd())) await link(config, { serviceUuid: opts.service || null });
 	console.log('');
 	console.log('Next: keep `motionode dev` running so Motionode sees your branches and local changes,');
@@ -127,6 +159,37 @@ async function status(config) {
 }
 
 /** Start (or resume) a ticket locally and check its branches out here. */
+/** Where a ticket's own folder goes: next to the linked folder, one per ticket. */
+function worktreePath(ws, ticketRef) {
+	return path.join(path.dirname(ws.path), `${path.basename(ws.path)}.worktrees`, String(ticketRef).replace(/[^A-Za-z0-9._-]/g, '_'));
+}
+
+/**
+ * How to get a service whose repository has no linked folder here. A Motionode-hosted
+ * repository is private to Motionode, so its GitHub URL is not a clone the person can use:
+ * clone it through Motionode, against the server this command is already talking to.
+ */
+function cloneGuidance(b) {
+	if (b?.motionodeHosted) {
+		return b.repo
+			? `no linked folder here — clone it through Motionode: \`motionode clone ${b.repo}\`, then run \`motionode link\``
+			: 'no linked folder here — clone it through Motionode with `motionode clone <owner/repo>`, then run `motionode link`';
+	}
+	if (b?.cloneUrl) return `no linked folder here — \`git clone ${b.cloneUrl}\`, then run \`motionode link\``;
+	return 'no linked folder here — clone the repository, then run `motionode link`';
+}
+
+/** What `motionode finish` tells the person was recorded (the same facts the web confirmation shows). */
+function finishLines(res) {
+	const lines = [`✓ ${res.summary || 'Build finished.'}`];
+	const rec = res.recorded;
+	if (rec) {
+		lines.push(`  Recorded: ${rec.commitCount} commit${rec.commitCount === 1 ? '' : 's'} on the ticket branch${rec.commits?.length ? ` (${rec.commits.map((c) => c.sha).join(', ')})` : ''}${rec.note ? `, note "${rec.note}"` : ''}.`);
+		if (rec.next?.stepName || rec.next?.message) lines.push(`  Next: ${rec.next.message || rec.next.stepName}${rec.next.ownerName ? ` (${rec.next.ownerName})` : ''}`);
+	}
+	return lines;
+}
+
 async function work(config, ref) {
 	if (!ref) throw new Error('Which ticket? e.g. motionode work T11-518');
 	const api = client(config);
@@ -136,12 +199,19 @@ async function work(config, ref) {
 	for (const b of lw.branches || []) {
 		const ws = (config.workspaces || []).find((w) => w.serviceUuid === b.serviceUuid);
 		if (!ws) {
-			console.log(`  ${b.serviceName}: ${b.branch}  (no linked folder here — clone ${b.cloneUrl || 'the repo'} and run \`motionode link\`)`);
+			console.log(`  ${b.serviceName}: ${b.branch}  (${cloneGuidance(b)})`);
 			continue;
 		}
 		try {
-			await Git.checkout(ws.path, b.branch);
-			console.log(`  ${b.serviceName}: checked out ${b.branch} in ${ws.path}`);
+			if (ws.worktrees) {
+				const dir = worktreePath(ws, lw.ticketDisplayId || ref);
+				const wt = await Git.worktreeFor(ws.path, b.branch, dir);
+				console.log(`  ${b.serviceName}: ${wt.created ? 'created' : 'reused'} a worktree on ${b.branch} in ${wt.path}`);
+				console.log(`    Open ${wt.path} in your tool; your linked folder ${ws.path} is untouched.`);
+			} else {
+				await Git.checkout(ws.path, b.branch);
+				console.log(`  ${b.serviceName}: checked out ${b.branch} in ${ws.path}`);
+			}
 		} catch (err) {
 			console.log(`  ${b.serviceName}: could not check out ${b.branch} — ${err.message}`);
 			if (/denied|403|401|authentication|permission/i.test(err.message)) {
@@ -156,8 +226,9 @@ async function finish(config, ref, { force = false, note = null } = {}) {
 	if (!ref) throw new Error('Which ticket? e.g. motionode finish T11-518');
 	const api = client(config);
 	try {
+		console.log(`Checking the ticket branch and telling Motionode ${ref} is built…`);
 		const res = await api.post(`/tickets/${encodeURIComponent(ref)}/finish`, { force, note });
-		console.log(`✓ ${res.summary || 'Build finished.'}`);
+		finishLines(res).forEach((l) => console.log(l));
 	} catch (err) {
 		console.log(`✗ ${err.message}`);
 		if (/not on the ticket branch|not pushed|uncommitted/i.test(err.message)) {
@@ -172,4 +243,4 @@ async function logout(config) {
 	console.log('✓ Disconnected this computer. (Remove it in Motionode Settings → Development workflow to revoke it there too.)');
 }
 
-module.exports = { login, link, connect, unlink, status, work, finish, logout };
+module.exports = { login, link, connect, unlink, status, work, finish, logout, worktreePath, finishLines, cloneGuidance };

package/lib/git.js

@@ -112,6 +112,27 @@ async function checkout(dir, branch) {
 	return status(dir);
 }
 
+/**
+ * A separate folder (git worktree) on a ticket's branch, so two tickets of one repository never share a working tree.
+ * Reuses the folder when this ticket already has one. Returns { path, created }.
+ */
+async function worktreeFor(dir, branch, path) {
+	const fs = require('fs');
+	if (fs.existsSync(path)) {
+		const r = await run(path, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFail: true });
+		if (r.ok && String(r.stdout || '').trim() === branch) {
+			await run(path, ['fetch', 'origin', branch], { allowFail: true });
+			await run(path, ['merge', '--ff-only', `origin/${branch}`], { allowFail: true });
+			return { path, created: false };
+		}
+		throw new Error(`${path} exists and is not a checkout of ${branch}`);
+	}
+	await run(dir, ['fetch', 'origin', branch]);
+	if (await hasLocalBranch(dir, branch)) await run(dir, ['worktree', 'add', path, branch]);
+	else await run(dir, ['worktree', 'add', '--track', '-b', branch, path, `origin/${branch}`]);
+	return { path, created: true };
+}
+
 /** The uncommitted diff, including new files. */
 async function diff(dir, onlyPath = null) {
 	const args = ['diff', 'HEAD'];
@@ -178,4 +199,4 @@ async function moveChanges(dir, branch) {
 	return { moved: true, branch };
 }
 
-module.exports = { run, isRepo, remoteUrl, normalizeRepoUrl, status, checkout, diff, commit, moveChanges };
+module.exports = { run, isRepo, remoteUrl, normalizeRepoUrl, status, checkout, worktreeFor, diff, commit, moveChanges };