agent-trellis 0.6.3 → 0.8.0

package/dist/lib/secretEnv.js

@@ -8,7 +8,8 @@
  * dotenv library's quoting/escaping/interpolation rules are more than
  * this narrow need requires (design.md D4).
  */
-import { existsSync, readFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
 const LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
 export function parseDotenv(content) {
     const result = {};
@@ -44,3 +45,32 @@ export function resolveSecretEnv(names, policy) {
     }
     return result;
 }
+/**
+ * `trellis migrate`'s static-env secret extraction
+ * (trellis-migrate-extract-static-env-secrets design.md D4) — appends
+ * one `NAME=value` line to a dotenv-format file in exactly the shape
+ * `parseDotenv` above already reads, creating the file (and its parent
+ * directory) if neither exists yet. Idempotent, the same three-way
+ * split every other Trellis writer uses: the name is absent (create),
+ * already present with the identical value (no-op — re-running migrate
+ * must not duplicate the line), or already present with a *different*
+ * value (conflict, left untouched — the file may hold a value the user
+ * already rotated by hand since the last run; silently overwriting it
+ * would be exactly the kind of value-clobbering this whole feature
+ * exists to prevent, just relocated to a new file).
+ */
+export function writeLocalSecretValue(path, name, value, backup) {
+    const existingContent = existsSync(path) ? readFileSync(path, "utf-8") : "";
+    const existing = parseDotenv(existingContent);
+    if (Object.hasOwn(existing, name)) {
+        return existing[name] === value ? "already-present" : "conflict";
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const separator = existingContent.length > 0 && !existingContent.endsWith("\n") ? "\n" : "";
+    const next = `${existingContent}${separator}${name}=${value}\n`;
+    if (backup)
+        backup.writeFile(path, next);
+    else
+        appendFileSync(path, `${separator}${name}=${value}\n`);
+    return "created";
+}

package/dist/lib/skillProvider.d.ts

@@ -0,0 +1,13 @@
+import type { Resource, ReadResourceResult, Tool, CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+export declare class SkillProvider implements TrellisProvider {
+    readonly id = "skills";
+    listTools(): Tool[];
+    callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
+    listResources(context: RuntimeContext): Resource[];
+    readResource(uri: URL, context: RuntimeContext): ReadResourceResult;
+    private search;
+    private readSkill;
+    private readFile;
+    private readBoundedFile;
+}

package/dist/lib/skillProvider.js

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { resolve, relative, sep } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { isInScope } from "../core/adapter.js";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { resolveScope } from "../core/types.js";
+const MAX_FILE_BYTES = 256 * 1024;
+const SKILL_RESOURCE_PREFIX = "trellis://skills/";
+const SEARCH_TOOL = {
+    name: "trellis.skills.search",
+    description: "Search in-scope Trellis skills by name or description, then read one selected skill on demand.",
+    inputSchema: {
+        type: "object",
+        properties: { query: { type: "string" }, limit: { type: "number", minimum: 1, maximum: 50 } },
+        required: ["query"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+const READ_TOOL = {
+    name: "trellis.skills.read",
+    description: "Read the SKILL.md instructions for one in-scope Trellis skill.",
+    inputSchema: {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+const READ_FILE_TOOL = {
+    name: "trellis.skills.read_file",
+    description: "Read one bounded, non-secret supporting file under an in-scope skill directory.",
+    inputSchema: {
+        type: "object",
+        properties: { name: { type: "string" }, relativePath: { type: "string" } },
+        required: ["name", "relativePath"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+function textResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], structuredContent: value };
+}
+function errorResult(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function frontmatter(content) {
+    if (!content.startsWith("---"))
+        return {};
+    const end = content.indexOf("\n---", 3);
+    if (end < 0)
+        return {};
+    try {
+        const parsed = parseYaml(content.slice(3, end));
+        return {
+            name: typeof parsed?.name === "string" ? parsed.name : undefined,
+            description: typeof parsed?.description === "string" ? parsed.description : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function fingerprint(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function isSecretLikePath(path) {
+    const normalized = path.toLowerCase();
+    return normalized.includes(".env") || normalized.includes("secret") || normalized.endsWith("servers.local.env");
+}
+function skillFor(canonical, agentId, name) {
+    const skill = canonical.skills.find((candidate) => candidate.name === name);
+    if (!skill || !hasSkillDocument(skill) || !isInScope(agentId, skill.scope, canonical.managedAgents))
+        return undefined;
+    return skill;
+}
+function hasSkillDocument(skill) {
+    try {
+        return statSync(resolve(skill.dir, "SKILL.md")).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function skillUri(name) {
+    return `${SKILL_RESOURCE_PREFIX}${encodeURIComponent(name)}/SKILL.md`;
+}
+function skillMetadata(skill, canonical, agentId, content) {
+    const metadata = frontmatter(content);
+    return {
+        name: skill.name,
+        description: metadata.description ?? "",
+        fingerprint: fingerprint(content),
+        uri: skillUri(skill.name),
+        scope: resolveScope(skill.scope, canonical.managedAgents).includes(agentId) ? "in-scope" : "out-of-scope",
+        source: "canonical",
+    };
+}
+export class SkillProvider {
+    id = "skills";
+    listTools() {
+        return [SEARCH_TOOL, READ_TOOL, READ_FILE_TOOL];
+    }
+    async callTool(name, args, context) {
+        const canonical = loadCanonicalSource(context.homeDir);
+        const input = (args ?? {});
+        if (name === SEARCH_TOOL.name)
+            return this.search(canonical, context.agentId, input);
+        if (name === READ_TOOL.name)
+            return this.readSkill(canonical, context.agentId, input);
+        if (name === READ_FILE_TOOL.name)
+            return this.readFile(canonical, context.agentId, input);
+        return errorResult(`unknown skill provider tool "${name}"`);
+    }
+    listResources(context) {
+        const canonical = loadCanonicalSource(context.homeDir);
+        return canonical.skills
+            .filter((skill) => hasSkillDocument(skill) && isInScope(context.agentId, skill.scope, canonical.managedAgents))
+            .map((skill) => ({
+            uri: skillUri(skill.name),
+            name: `${skill.name}/SKILL.md`,
+            description: `Instructions for the ${skill.name} skill`,
+            mimeType: "text/markdown",
+        }));
+    }
+    readResource(uri, context) {
+        if (uri.protocol !== "trellis:" || uri.hostname !== "skills") {
+            throw new Error(`unsupported skill resource URI "${uri.toString()}"`);
+        }
+        const segments = uri.pathname.split("/").filter(Boolean).map((segment) => decodeURIComponent(segment));
+        if (segments.length !== 2 || segments[1] !== "SKILL.md") {
+            throw new Error(`unsupported skill resource URI "${uri.toString()}"`);
+        }
+        const canonical = loadCanonicalSource(context.homeDir);
+        const skill = skillFor(canonical, context.agentId, segments[0]);
+        if (!skill)
+            throw new Error(`skill "${segments[0]}" is not available to ${context.agentId}`);
+        const content = this.readBoundedFile(resolve(skill.dir, "SKILL.md"), skill.dir);
+        return { contents: [{ uri: uri.toString(), mimeType: "text/markdown", text: content }] };
+    }
+    search(canonical, agentId, input) {
+        const query = typeof input.query === "string" ? input.query.trim().toLowerCase() : "";
+        const limit = typeof input.limit === "number" ? Math.min(50, Math.max(1, Math.floor(input.limit))) : 20;
+        const results = canonical.skills
+            .filter((skill) => isInScope(agentId, skill.scope, canonical.managedAgents))
+            .map((skill) => {
+            let content;
+            try {
+                content = this.readBoundedFile(resolve(skill.dir, "SKILL.md"), skill.dir);
+            }
+            catch {
+                return undefined;
+            }
+            return { ...skillMetadata(skill, canonical, agentId, content), dir: skill.dir };
+        })
+            .filter((skill) => skill !== undefined)
+            .filter((skill) => !query || `${skill.name} ${skill.description}`.toLowerCase().includes(query))
+            .slice(0, limit)
+            .map(({ dir: _dir, ...result }) => result);
+        return textResult({ skills: results });
+    }
+    readSkill(canonical, agentId, input) {
+        if (typeof input.name !== "string" || input.name.length === 0)
+            return errorResult('"name" is required');
+        const skill = skillFor(canonical, agentId, input.name);
+        if (!skill)
+            return errorResult(`skill "${input.name}" is not available to ${agentId}`);
+        const path = resolve(skill.dir, "SKILL.md");
+        const content = this.readBoundedFile(path, skill.dir);
+        return textResult({ ...skillMetadata(skill, canonical, agentId, content), content });
+    }
+    readFile(canonical, agentId, input) {
+        if (typeof input.name !== "string" || typeof input.relativePath !== "string")
+            return errorResult('"name" and "relativePath" are required');
+        const skill = skillFor(canonical, agentId, input.name);
+        if (!skill)
+            return errorResult(`skill "${input.name}" is not available to ${agentId}`);
+        if (input.relativePath.length === 0 || input.relativePath.includes("\0") || isSecretLikePath(input.relativePath)) {
+            return errorResult("supporting file path is not allowed");
+        }
+        try {
+            const path = resolve(skill.dir, input.relativePath);
+            const root = realpathSync(skill.dir);
+            const realPath = realpathSync(path);
+            const rel = relative(root, realPath);
+            if (rel.startsWith(`..${sep}`) || rel === ".." || !existsSync(realPath) || !statSync(realPath).isFile()) {
+                return errorResult("supporting file is outside the skill root");
+            }
+            return textResult({ name: skill.name, relativePath: rel, source: "canonical-skill-supporting-file", content: this.readBoundedFile(realPath, root) });
+        }
+        catch (err) {
+            return errorResult(`could not read supporting file: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    readBoundedFile(path, root) {
+        if (isSecretLikePath(path))
+            throw new Error("secret-like files are not readable through the skill provider");
+        const rootPath = realpathSync(root);
+        const realPath = realpathSync(path);
+        const rel = relative(rootPath, realPath);
+        if (rel.startsWith(`..${sep}`) || rel === "..")
+            throw new Error("file is outside the skill root");
+        const stat = statSync(realPath);
+        if (!stat.isFile() || stat.size > MAX_FILE_BYTES)
+            throw new Error(`file exceeds the ${MAX_FILE_BYTES}-byte provider limit`);
+        return readFileSync(realPath, "utf8");
+    }
+}

package/dist/lib/taskProvider.d.ts

@@ -0,0 +1,7 @@
+import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+export declare class TaskProvider implements TrellisProvider {
+    readonly id = "tasks";
+    listTools(): Tool[];
+    callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
+}

package/dist/lib/taskProvider.js

@@ -0,0 +1,43 @@
+import { claimTask, createTask, handoffTask, listTasks, readTask, updateTask } from "./taskStore.js";
+const LIST = { name: "trellis.tasks.list", description: "List safe Trellis handoff tasks.", inputSchema: { type: "object", properties: { status: { type: "string" }, toAgent: { type: "string" } }, additionalProperties: false }, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false } };
+const READ = { name: "trellis.tasks.read", description: "Read one Trellis handoff task and its audit history.", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false }, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false } };
+const CREATE = { name: "trellis.tasks.create", description: "Create a safe durable handoff task. Requires explicit confirm=true and never launches another Agent.", inputSchema: { type: "object", properties: { objective: { type: "string" }, toAgent: { type: "string" }, context: { type: "object" }, constraints: { type: "array", items: { type: "string" } }, confirm: { type: "boolean" } }, required: ["objective", "confirm"], additionalProperties: false }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false } };
+const CLAIM = { name: "trellis.tasks.claim", description: "Claim one pending handoff task with an exclusive lease. Requires explicit confirm=true.", inputSchema: { type: "object", properties: { id: { type: "string" }, leaseMs: { type: "number" }, confirm: { type: "boolean" } }, required: ["id", "confirm"], additionalProperties: false }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false } };
+const UPDATE = { name: "trellis.tasks.update", description: "Update a claimed task status without launching another Agent. Requires explicit confirm=true.", inputSchema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" }, note: { type: "string" }, result: { type: "string" }, confirm: { type: "boolean" } }, required: ["id", "status", "confirm"], additionalProperties: false }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false } };
+const HANDOFF = { name: "trellis.tasks.handoff", description: "Hand a task to another managed Agent as data only. Requires explicit confirm=true.", inputSchema: { type: "object", properties: { id: { type: "string" }, toAgent: { type: "string" }, note: { type: "string" }, confirm: { type: "boolean" } }, required: ["id", "toAgent", "confirm"], additionalProperties: false }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false } };
+function result(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], structuredContent: value };
+}
+function failure(error) {
+    return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true };
+}
+export class TaskProvider {
+    id = "tasks";
+    listTools() { return [LIST, READ, CREATE, CLAIM, UPDATE, HANDOFF]; }
+    async callTool(name, args, context) {
+        const input = (args ?? {});
+        try {
+            if (name === LIST.name) {
+                const status = input.status;
+                const toAgent = input.toAgent;
+                return result({ tasks: listTasks(context.homeDir, { status, toAgent }) });
+            }
+            if (name === READ.name)
+                return result(readTask(context.homeDir, String(input.id ?? "")));
+            if (input.confirm !== true)
+                return failure(`task mutation "${name}" requires confirm=true; no Agent is launched automatically`);
+            if (name === CREATE.name)
+                return result(createTask(context.homeDir, { objective: String(input.objective ?? ""), fromAgent: context.agentId, ...(input.toAgent ? { toAgent: input.toAgent } : {}), ...(input.context ? { context: input.context } : {}), ...(input.constraints ? { constraints: input.constraints } : {}) }));
+            if (name === CLAIM.name)
+                return result(claimTask(context.homeDir, String(input.id ?? ""), context.agentId, input.leaseMs));
+            if (name === UPDATE.name)
+                return result(updateTask(context.homeDir, String(input.id ?? ""), context.agentId, input.status, input.note, input.result));
+            if (name === HANDOFF.name)
+                return result(handoffTask(context.homeDir, String(input.id ?? ""), context.agentId, input.toAgent, input.note));
+            return failure(`unknown task tool "${name}"`);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    }
+}

package/dist/lib/taskStore.d.ts

@@ -0,0 +1,46 @@
+import type { AgentId } from "../core/types.js";
+export type TaskStatus = "pending" | "claimed" | "in_progress" | "blocked" | "completed";
+export interface TaskContext {
+    workspace?: string;
+    commit?: string;
+    references?: string[];
+    note?: string;
+}
+export interface TaskHistoryEntry {
+    at: string;
+    agent: AgentId;
+    action: string;
+    status: TaskStatus;
+    note?: string;
+}
+export interface TaskRecord {
+    id: string;
+    objective: string;
+    fromAgent: AgentId;
+    toAgent?: AgentId;
+    status: TaskStatus;
+    context?: TaskContext;
+    constraints?: string[];
+    result?: string;
+    claimedBy?: AgentId;
+    leaseUntil?: string;
+    createdAt: string;
+    updatedAt: string;
+    history: TaskHistoryEntry[];
+}
+export declare function taskStorePath(homeDir: string): string;
+export declare function listTasks(homeDir: string, filter?: {
+    status?: TaskStatus;
+    toAgent?: AgentId;
+}): TaskRecord[];
+export declare function readTask(homeDir: string, id: string): TaskRecord;
+export declare function createTask(homeDir: string, input: {
+    objective: string;
+    fromAgent: AgentId;
+    toAgent?: AgentId;
+    context?: TaskContext;
+    constraints?: string[];
+}): TaskRecord;
+export declare function claimTask(homeDir: string, id: string, agent: AgentId, leaseMs?: number): TaskRecord;
+export declare function updateTask(homeDir: string, id: string, agent: AgentId, status: TaskStatus, note?: string, result?: string): TaskRecord;
+export declare function handoffTask(homeDir: string, id: string, agent: AgentId, toAgent: AgentId, note?: string): TaskRecord;

package/dist/lib/taskStore.js

@@ -0,0 +1,156 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const SECRET_LIKE = /(sk-|ghp_|glpat-|mcpr_|token\s*=|password\s*=|secret\s*=|authorization\s*:)/i;
+export function taskStorePath(homeDir) {
+    return join(homeDir, ".trellis", "tasks", "tasks.json");
+}
+function readFile(path) {
+    if (!existsSync(path))
+        return { tasks: [] };
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return { tasks: Array.isArray(value.tasks) ? value.tasks : [] };
+    }
+    catch {
+        throw new Error(`could not parse task store ${path}`);
+    }
+}
+function writeFile(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+}
+function assertSafeText(label, value) {
+    if (!value.trim())
+        throw new Error(`${label} must not be empty`);
+    if (SECRET_LIKE.test(value))
+        throw new Error(`${label} looks like it contains a credential or secret-like value`);
+}
+function assertSafeContext(context) {
+    if (!context)
+        return;
+    for (const [key, value] of Object.entries(context)) {
+        if (typeof value === "string")
+            assertSafeText(`context.${key}`, value);
+        if (Array.isArray(value))
+            value.forEach((item) => assertSafeText(`context.${key}`, item));
+    }
+}
+function now() {
+    return new Date().toISOString();
+}
+function assertAgent(value, label) {
+    if (value !== "claude-code" && value !== "codex" && value !== "kiro" && value !== "pi" && value !== "kimi-code") {
+        throw new Error(`${label} must be a supported Agent id`);
+    }
+}
+function taskOrThrow(file, id) {
+    const task = file.tasks.find((candidate) => candidate.id === id);
+    if (!task)
+        throw new Error(`task "${id}" was not found`);
+    return task;
+}
+function addHistory(task, agent, action, status, note) {
+    task.status = status;
+    task.updatedAt = now();
+    task.history.push({ at: task.updatedAt, agent, action, status, ...(note ? { note } : {}) });
+}
+export function listTasks(homeDir, filter) {
+    const tasks = readFile(taskStorePath(homeDir)).tasks;
+    return tasks
+        .filter((task) => !filter?.status || task.status === filter.status)
+        .filter((task) => !filter?.toAgent || task.toAgent === filter.toAgent)
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+}
+export function readTask(homeDir, id) {
+    return taskOrThrow(readFile(taskStorePath(homeDir)), id);
+}
+export function createTask(homeDir, input) {
+    assertSafeText("objective", input.objective);
+    assertAgent(input.fromAgent, "fromAgent");
+    if (input.toAgent)
+        assertAgent(input.toAgent, "toAgent");
+    assertSafeContext(input.context);
+    input.constraints?.forEach((value) => assertSafeText("constraint", value));
+    const timestamp = now();
+    const task = {
+        id: `task-${randomUUID()}`,
+        objective: input.objective,
+        fromAgent: input.fromAgent,
+        ...(input.toAgent ? { toAgent: input.toAgent } : {}),
+        status: "pending",
+        ...(input.context ? { context: input.context } : {}),
+        ...(input.constraints?.length ? { constraints: input.constraints } : {}),
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        history: [{ at: timestamp, agent: input.fromAgent, action: "created", status: "pending" }],
+    };
+    const file = readFile(taskStorePath(homeDir));
+    file.tasks.push(task);
+    writeFile(taskStorePath(homeDir), file);
+    return task;
+}
+export function claimTask(homeDir, id, agent, leaseMs = 30 * 60 * 1000) {
+    assertAgent(agent, "agent");
+    if (!Number.isFinite(leaseMs) || leaseMs < 1_000 || leaseMs > 24 * 60 * 60 * 1000)
+        throw new Error("leaseMs must be between 1000 and 86400000");
+    const path = taskStorePath(homeDir);
+    const file = readFile(path);
+    const task = taskOrThrow(file, id);
+    const timestamp = Date.now();
+    if (task.leaseUntil && new Date(task.leaseUntil).getTime() <= timestamp) {
+        task.claimedBy = undefined;
+        task.leaseUntil = undefined;
+        if (task.status === "claimed" || task.status === "in_progress")
+            task.status = "pending";
+    }
+    if (task.status !== "pending" || task.claimedBy)
+        throw new Error(`task "${id}" is already claimed or is not pending`);
+    task.claimedBy = agent;
+    task.leaseUntil = new Date(timestamp + leaseMs).toISOString();
+    addHistory(task, agent, "claimed", "claimed");
+    writeFile(path, file);
+    return task;
+}
+export function updateTask(homeDir, id, agent, status, note, result) {
+    assertAgent(agent, "agent");
+    if (!["pending", "claimed", "in_progress", "blocked", "completed"].includes(status))
+        throw new Error(`invalid task status "${status}"`);
+    if (note)
+        assertSafeText("note", note);
+    if (result)
+        assertSafeText("result", result);
+    const path = taskStorePath(homeDir);
+    const file = readFile(path);
+    const task = taskOrThrow(file, id);
+    if (task.claimedBy && task.claimedBy !== agent)
+        throw new Error(`task "${id}" is claimed by another Agent`);
+    if (status === "completed" && result)
+        task.result = result;
+    addHistory(task, agent, status === "completed" ? "completed" : "updated", status, note);
+    if (status === "completed") {
+        task.claimedBy = undefined;
+        task.leaseUntil = undefined;
+    }
+    writeFile(path, file);
+    return task;
+}
+export function handoffTask(homeDir, id, agent, toAgent, note) {
+    assertAgent(agent, "agent");
+    assertAgent(toAgent, "toAgent");
+    if (note)
+        assertSafeText("note", note);
+    const path = taskStorePath(homeDir);
+    const file = readFile(path);
+    const task = taskOrThrow(file, id);
+    if (task.claimedBy && task.claimedBy !== agent)
+        throw new Error(`task "${id}" is claimed by another Agent`);
+    task.toAgent = toAgent;
+    task.claimedBy = undefined;
+    task.leaseUntil = undefined;
+    addHistory(task, agent, "handed-off", "pending", note);
+    writeFile(path, file);
+    return task;
+}

package/dist/lib/terminalPicker.d.ts

@@ -1,45 +1,40 @@
 /**
- * Minimal, dependency-free arrow-key/checkbox terminal picker
- * (trellis-onboard-interactive-picker design.md D1) — the interaction
- * surface `trellis onboard`'s two prompts need (at most four rows, no
- * search, no pagination) doesn't need a full prompt library; this
- * hand-rolls just enough raw-mode key handling and ANSI rendering for
- * that bounded case, matching the project's existing narrow-dependency
- * precedent (src/lib/envVarNames.ts, src/lib/secretEnv.ts).
+ * Styled interactive prompts used by `trellis onboard`.
  *
- * `input`/`output` are injectable (never a CLI flag) purely so tests can
- * drive the real key-parsing/render loop against a plain stream instead
- * of a real TTY — same seam pattern (`homeDir`, etc.) used everywhere
- * else in this project.
+ * The onboarding orchestration depends on semantic values (an index or a set
+ * of indices), not on a particular terminal renderer. Clack owns raw-mode
+ * handling, color, wrapping, cursor cleanup, and cancellation; the injected
+ * streams keep the prompt loop testable without a real terminal.
  */
 import type { Readable, Writable } from "node:stream";
 export interface PickerStreams {
     input: NodeJS.ReadStream | Readable;
     output: NodeJS.WriteStream | Writable;
 }
+export interface PickerOption {
+    label: string;
+    disabled?: boolean;
+}
 /**
- * True only when both streams are real, raw-mode-capable terminals — the
- * exact gate deciding picker vs. the pre-existing numbered-typing prompt
- * (design.md D2). A stream lacking `setRawMode` (piped input, some
- * minimal TTYs) always falls back, never hangs or guesses.
+ * Clack is only started for a real interactive terminal. Piped input keeps
+ * the existing numbered fallback in onboard instead of hanging in raw mode.
  */
 export declare function canUseInteractivePicker(streams?: PickerStreams): boolean;
-/** Wrapping index navigation — pure, exported for direct unit testing. */
+/** Wrapping index navigation retained as a small public utility for callers/tests. */
 export declare function nextIndex(current: number, delta: number, length: number): number;
-/** Pure single-index toggle — exported for direct unit testing. */
+/** Pure single-index toggle retained for callers/tests. */
 export declare function toggled(checked: readonly boolean[], index: number): boolean[];
 /**
- * Single-select: Up/Down/j/k moves the highlight, Enter confirms. Resolves
- * the confirmed index, or `null` on Ctrl+C cancel. Caller (onboard.ts)
- * must have already confirmed `canUseInteractivePicker()` — this function
- * does not re-check, and assumes `streams.input` genuinely supports raw
- * mode.
+ * Single-select prompt. The returned number is the original item index, so
+ * callers do not depend on display labels or prompt-library values.
  */
-export declare function runSingleSelectPicker(items: string[], streams?: PickerStreams): Promise<number | null>;
+export declare function runSingleSelectPicker(items: readonly (string | PickerOption)[], streams?: PickerStreams, message?: string): Promise<number | null>;
 /**
- * Multi-select (checkbox): Up/Down/j/k moves the highlight, Space toggles
- * the current row, Enter confirms. Resolves the checked indices at
- * confirm time, or `null` on Ctrl+C cancel. Same precondition as
- * `runSingleSelectPicker`.
+ * Checkbox prompt. The returned indices preserve the existing onboard
+ * contract, while Clack handles checked state, wrapping, colors, and cleanup.
  */
-export declare function runMultiSelectPicker(items: string[], initiallyChecked: readonly boolean[], streams?: PickerStreams): Promise<number[] | null>;
+export declare function runMultiSelectPicker(items: string[], initiallyChecked: readonly boolean[], streams?: PickerStreams, message?: string): Promise<number[] | null>;
+/** Searchable multiselect for large skill/MCP inventories. It returns the
+ * selected labels as stable names, preserving the semantic adapter contract
+ * while avoiding a wall of dozens of rows in the onboarding terminal. */
+export declare function runSearchMultiSelectPicker(items: readonly string[], streams?: PickerStreams, message?: string): Promise<string[] | null>;