agent-trellis 0.8.0 → 0.9.0

package/dist/commands/remoteSkill.js

@@ -0,0 +1,392 @@
+/**
+ * `trellis add` and `trellis update`: GitHub-hosted Skill import with
+ * Trellis-owned canonical storage, provenance, scope, backup, and sync.
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { validateSkillScopeYaml, writeSkillScopeYaml } from "../core/canonical.js";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { ALL_AGENTS } from "../core/types.js";
+import { decideDirImport } from "../lib/dirEquals.js";
+import { directoryDigest } from "../lib/dirDigest.js";
+import { openBackupSession } from "../lib/backup.js";
+import { isBuiltinSkillName } from "../lib/builtinSkills.js";
+import { emptyRemoteSkillLock, readRemoteSkillLock, writeRemoteSkillLock } from "../lib/remoteSkillLock.js";
+import { fetchRemoteRepository, normalizeGitHubRepository } from "../lib/remoteSkillSource.js";
+import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
+function safeSkillName(name) {
+    return typeof name === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(name) && name !== "." && name !== "..";
+}
+function cloneLock(lock) {
+    return { version: lock.version, skills: Object.fromEntries(Object.entries(lock.skills).map(([name, entry]) => [name, { ...entry }])) };
+}
+function lockEntryFor(source, requestedRef, commit, selected) {
+    return { source, requestedRef, commit, subdirectory: selected.subdirectory, digest: selected.digest };
+}
+function sameLockEntry(a, b) {
+    return a !== undefined
+        && a.source === b.source
+        && a.requestedRef === b.requestedRef
+        && a.commit === b.commit
+        && a.subdirectory === b.subdirectory
+        && a.digest === b.digest;
+}
+function scopeForRequest(homeDir, agents) {
+    let canonical;
+    try {
+        canonical = loadCanonicalSource(homeDir);
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+    if (!agents || agents.length === 0)
+        return { scope: undefined };
+    const values = agents.flatMap((value) => value.split(",").map((id) => id.trim()).filter(Boolean));
+    if (values.length === 0)
+        return { error: "--agent needs at least one Agent id" };
+    if (values.includes("*")) {
+        if (values.length !== 1)
+            return { error: '--agent "*" cannot be combined with named Agents' };
+        return { scope: [...canonical.managedAgents] };
+    }
+    const resolved = [];
+    for (const id of values) {
+        if (!ALL_AGENTS.includes(id))
+            return { error: `Unknown Agent id: ${id}` };
+        const agent = id;
+        if (!canonical.managedAgents.includes(agent))
+            return { error: `${agent} is not managed. Add it with \`trellis manage add ${agent}\` before targeting it.` };
+        if (!resolved.includes(agent))
+            resolved.push(agent);
+    }
+    return { scope: resolved };
+}
+/** Builds an import plan from an already-fetched source.  Keeping fetching
+ * outside this function makes the real Git transport testable with a local
+ * bare repository while public CLI input remains GitHub-only. */
+export function collectRemoteSkillAddPlan(fetched, name, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    if (!safeSkillName(name))
+        return { name: name ?? "", action: "invalid-options", detail: "--skill must be a safe Skill directory name" };
+    if (isBuiltinSkillName(name))
+        return { name, action: "conflict", detail: `"${name}" is a Trellis package-owned Skill and cannot be replaced` };
+    const scopeResult = scopeForRequest(homeDir, opts.agents);
+    if (scopeResult.error)
+        return { name, action: "invalid-options", detail: scopeResult.error };
+    let selected;
+    try {
+        selected = fetched.select(name);
+    }
+    catch (error) {
+        return { name, action: "invalid-source", detail: error instanceof Error ? error.message : String(error) };
+    }
+    const lockRead = readRemoteSkillLock(homeDir);
+    if (!lockRead.ok)
+        return { name, action: "conflict", detail: lockRead.error };
+    const canonicalPath = join(homeDir, ".trellis", "skills", name);
+    const incoming = lockEntryFor(fetched.repository.url, fetched.requestedRef, fetched.commit, selected);
+    const existingLock = lockRead.lock.skills[name];
+    const decision = decideDirImport(selected.directory, canonicalPath);
+    if (decision === "conflict") {
+        return { name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve it by hand`, canonicalPath, scope: scopeResult.scope };
+    }
+    if (decision === "already-present") {
+        if (!sameLockEntry(existingLock, incoming)) {
+            return { name, action: "conflict", detail: `canonical skills/${name}/ already exists without matching remote provenance — resolve it by hand`, canonicalPath, scope: scopeResult.scope };
+        }
+        return { name, action: "already-present", detail: "canonical content and remote provenance are already current", source: incoming.source, requestedRef: incoming.requestedRef, commit: incoming.commit, subdirectory: incoming.subdirectory, digest: incoming.digest, canonicalPath, scope: scopeResult.scope };
+    }
+    if (existingLock) {
+        return { name, action: "conflict", detail: `provenance already tracks ${name} but its canonical directory is absent — resolve it by hand`, canonicalPath, scope: scopeResult.scope };
+    }
+    return { name, action: "create", detail: `will import ${incoming.subdirectory} at ${incoming.commit}`, source: incoming.source, requestedRef: incoming.requestedRef, commit: incoming.commit, subdirectory: incoming.subdirectory, digest: incoming.digest, canonicalPath, scope: scopeResult.scope, sourceDir: selected.directory };
+}
+function successfulAdd(plan) {
+    return plan.action === "create" || plan.action === "already-present";
+}
+function displayAddPlan(plan) {
+    const { sourceDir: _sourceDir, ...safe } = plan;
+    return safe;
+}
+export async function applyRemoteSkillAddPlan(plan, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    if (!successfulAdd(plan))
+        return { plan: displayAddPlan(plan) };
+    if (opts.dryRun)
+        return { plan: displayAddPlan(plan) };
+    const ownSession = !opts.backupSession ? openBackupSession(homeDir, "remote-skill-add") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    if (plan.action === "create") {
+        const scopePath = join(homeDir, ".trellis", "scope.yaml");
+        const scopeValidation = validateSkillScopeYaml(scopePath);
+        if (!scopeValidation.ok)
+            throw new Error(scopeValidation.error);
+        const lockRead = readRemoteSkillLock(homeDir);
+        if (!lockRead.ok)
+            throw new Error(lockRead.error);
+        session.createDirFromSource(plan.canonicalPath, plan.sourceDir);
+        const scopeWrite = writeSkillScopeYaml(scopePath, plan.name, plan.scope, session);
+        if (!scopeWrite.ok)
+            throw new Error(scopeWrite.error);
+        const lock = cloneLock(lockRead.lock);
+        lock.skills[plan.name] = {
+            source: plan.source, requestedRef: plan.requestedRef, commit: plan.commit, subdirectory: plan.subdirectory, digest: plan.digest,
+        };
+        writeRemoteSkillLock(homeDir, lock, session);
+    }
+    else {
+        // An idempotent add may still deliberately change scope.  The writer is
+        // no-op when it already matches, so it does not create a needless backup.
+        const scopeWrite = writeSkillScopeYaml(join(homeDir, ".trellis", "scope.yaml"), plan.name, plan.scope, session);
+        if (!scopeWrite.ok)
+            throw new Error(scopeWrite.error);
+    }
+    ownSession?.finalize();
+    let sync;
+    if (session.hasOperations() && existsSync(join(homeDir, ".trellis"))) {
+        sync = await collectSyncReport({ target: "skills", homeDir });
+    }
+    return { plan: displayAddPlan(plan), ...(sync ? { sync } : {}) };
+}
+/** CLI-facing remote add.  The only source accepted here is normalized
+ * GitHub input; tests use collectRemoteSkillAddPlan with a local fetch. */
+export async function runRemoteSkillAdd(sourceInput, name, opts = {}) {
+    let repository;
+    try {
+        repository = normalizeGitHubRepository(sourceInput ?? "");
+    }
+    catch (error) {
+        const plan = { name: name ?? "", action: "invalid-source", detail: error instanceof Error ? error.message : String(error) };
+        if (opts.json)
+            console.log(JSON.stringify(displayAddPlan(plan), null, 2));
+        else
+            console.error(plan.detail);
+        return { exitCode: 1 };
+    }
+    let fetched;
+    try {
+        fetched = fetchRemoteRepository(repository, { branch: opts.branch });
+    }
+    catch (error) {
+        const plan = { name: name ?? "", action: "invalid-source", detail: error instanceof Error ? error.message : String(error), source: repository.url };
+        if (opts.json)
+            console.log(JSON.stringify(displayAddPlan(plan), null, 2));
+        else
+            console.error(plan.detail);
+        return { exitCode: 1 };
+    }
+    try {
+        const plan = collectRemoteSkillAddPlan(fetched, name, opts);
+        const outcome = await applyRemoteSkillAddPlan(plan, { homeDir: opts.homeDir, dryRun: opts.dryRun });
+        if (opts.json) {
+            console.log(JSON.stringify(outcome, null, 2));
+        }
+        else {
+            console.log(`${opts.dryRun ? "[dry run] " : ""}remote skill add ${plan.name}`);
+            console.log(`  [${plan.action}] ${plan.detail}`);
+            if (plan.source)
+                console.log(`  source: ${plan.source}@${plan.commit} (${plan.subdirectory})`);
+            if (plan.canonicalPath)
+                console.log(`  canonical: ${plan.canonicalPath}`);
+            if (plan.scope !== undefined)
+                console.log(`  scope: ${plan.scope.join(", ") || "(no managed agents)"}`);
+            if (outcome.sync)
+                printSyncReport(outcome.sync, false);
+        }
+        const syncConflict = outcome.sync?.reports.some((report) => report.items.some((item) => item.action === "conflict")) ?? false;
+        return { exitCode: successfulAdd(plan) && !syncConflict ? 0 : 1 };
+    }
+    finally {
+        fetched.dispose();
+    }
+}
+export async function runRemoteSkillList(sourceInput, opts = {}) {
+    let repository;
+    try {
+        repository = normalizeGitHubRepository(sourceInput ?? "");
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        if (opts.json)
+            console.log(JSON.stringify({ action: "invalid-source", detail }, null, 2));
+        else
+            console.error(detail);
+        return { exitCode: 1 };
+    }
+    try {
+        const fetched = fetchRemoteRepository(repository, { branch: opts.branch });
+        try {
+            const report = { source: repository.url, requestedRef: fetched.requestedRef, commit: fetched.commit, skills: fetched.candidates.map(({ name, subdirectory }) => ({ name, subdirectory })) };
+            if (opts.json)
+                console.log(JSON.stringify(report, null, 2));
+            else if (report.skills.length === 0)
+                console.log("No exact-case SKILL.md entries found in the remote source.");
+            else
+                for (const skill of report.skills)
+                    console.log(`${skill.name} — ${skill.subdirectory}`);
+            return { exitCode: 0 };
+        }
+        finally {
+            fetched.dispose();
+        }
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        if (opts.json)
+            console.log(JSON.stringify({ action: "invalid-source", detail, source: repository.url }, null, 2));
+        else
+            console.error(detail);
+        return { exitCode: 1 };
+    }
+}
+function displayUpdatePlan(plan) {
+    const { sourceDir: _sourceDir, ...safe } = plan;
+    return safe;
+}
+export function collectRemoteSkillUpdatePlan(name, fetched, homeDir = homedir()) {
+    const lockRead = readRemoteSkillLock(homeDir);
+    if (!lockRead.ok)
+        return { name, action: "conflict", detail: lockRead.error };
+    const entry = lockRead.lock.skills[name];
+    if (!entry)
+        return { name, action: "not-tracked", detail: `${name} is not a remotely tracked Skill` };
+    const canonicalPath = join(homeDir, ".trellis", "skills", name);
+    if (!existsSync(canonicalPath))
+        return { name, action: "conflict", detail: `canonical skills/${name}/ is missing while provenance remains`, canonicalPath };
+    let currentDigest;
+    try {
+        currentDigest = directoryDigest(canonicalPath);
+    }
+    catch (error) {
+        return { name, action: "conflict", detail: `could not read canonical skills/${name}/ safely: ${error instanceof Error ? error.message : String(error)}`, canonicalPath };
+    }
+    if (currentDigest !== entry.digest) {
+        return { name, action: "conflict", detail: `canonical skills/${name}/ has local edits and will not be overwritten`, source: entry.source, requestedRef: entry.requestedRef, previousCommit: entry.commit, previousDigest: entry.digest, canonicalPath };
+    }
+    if (!fetched)
+        return { name, action: "invalid-source", detail: "Remote source was not fetched", source: entry.source, requestedRef: entry.requestedRef, previousCommit: entry.commit, previousDigest: entry.digest, canonicalPath };
+    let selected;
+    try {
+        selected = fetched.select(name);
+    }
+    catch (error) {
+        return { name, action: "invalid-source", detail: error instanceof Error ? error.message : String(error), source: entry.source, requestedRef: entry.requestedRef, previousCommit: entry.commit, previousDigest: entry.digest, canonicalPath };
+    }
+    if (selected.subdirectory !== entry.subdirectory) {
+        return { name, action: "conflict", detail: `remote Skill ${name} moved from ${entry.subdirectory} to ${selected.subdirectory}; resolve provenance by hand`, source: entry.source, requestedRef: entry.requestedRef, previousCommit: entry.commit, previousDigest: entry.digest, canonicalPath };
+    }
+    if (fetched.commit === entry.commit && selected.digest === entry.digest) {
+        return { name, action: "already-current", detail: "remote commit and canonical content are already current", source: entry.source, requestedRef: entry.requestedRef, previousCommit: entry.commit, commit: fetched.commit, previousDigest: entry.digest, digest: selected.digest, canonicalPath };
+    }
+    return { name, action: "update", detail: `will update ${entry.commit} -> ${fetched.commit}`, source: entry.source, requestedRef: entry.requestedRef, previousCommit: entry.commit, commit: fetched.commit, previousDigest: entry.digest, digest: selected.digest, canonicalPath, sourceDir: selected.directory, replaceDirectory: selected.digest !== entry.digest };
+}
+export async function applyRemoteSkillUpdatePlans(plans, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const updates = plans.filter((plan) => plan.action === "update");
+    if (opts.dryRun || updates.length === 0)
+        return { plans: plans.map(displayUpdatePlan) };
+    const ownSession = !opts.backupSession ? openBackupSession(homeDir, "remote-skill-update") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    const lockRead = readRemoteSkillLock(homeDir);
+    if (!lockRead.ok)
+        throw new Error(lockRead.error);
+    const lock = cloneLock(lockRead.lock);
+    // Recheck all mutable inputs before the first replacement. The plans may
+    // have been previewed some time before application, so no remote update
+    // should proceed if either the lock or canonical directory changed.
+    for (const plan of updates) {
+        const current = lock.skills[plan.name];
+        if (!current || current.commit !== plan.previousCommit || current.digest !== plan.previousDigest) {
+            throw new Error(`Remote Skill ${plan.name} provenance changed after planning; run \`trellis update\` again.`);
+        }
+        if (directoryDigest(plan.canonicalPath) !== plan.previousDigest) {
+            throw new Error(`Canonical Skill ${plan.name} changed after planning; run \`trellis update\` again.`);
+        }
+    }
+    for (const plan of updates) {
+        if (plan.replaceDirectory)
+            session.replaceDirFromSource(plan.canonicalPath, plan.sourceDir);
+        lock.skills[plan.name] = { source: plan.source, requestedRef: plan.requestedRef, commit: plan.commit, subdirectory: lock.skills[plan.name].subdirectory, digest: plan.digest };
+    }
+    writeRemoteSkillLock(homeDir, lock, session);
+    ownSession?.finalize();
+    let sync;
+    if (session.hasOperations() && existsSync(join(homeDir, ".trellis")))
+        sync = await collectSyncReport({ target: "skills", homeDir });
+    return { plans: plans.map(displayUpdatePlan), ...(sync ? { sync } : {}) };
+}
+export async function runRemoteSkillUpdate(names, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const lockRead = readRemoteSkillLock(homeDir);
+    const selectedNames = names.length > 0 ? [...new Set(names)] : lockRead.ok ? Object.keys(lockRead.lock.skills).sort() : [];
+    if (!lockRead.ok) {
+        const report = [{ name: "", action: "conflict", detail: lockRead.error }];
+        if (opts.json)
+            console.log(JSON.stringify({ plans: report }, null, 2));
+        else
+            console.error(lockRead.error);
+        return { exitCode: 1 };
+    }
+    if (selectedNames.length === 0) {
+        const report = { plans: [] };
+        if (opts.json)
+            console.log(JSON.stringify(report, null, 2));
+        else
+            console.log("No remotely tracked Skills to update.");
+        return { exitCode: 0 };
+    }
+    const fetched = new Map();
+    const plans = [];
+    try {
+        for (const name of selectedNames) {
+            const entry = lockRead.lock.skills[name];
+            if (!entry) {
+                plans.push(collectRemoteSkillUpdatePlan(name, undefined, homeDir));
+                continue;
+            }
+            // Avoid network work when the canonical tree has been edited: its plan
+            // is already a safe conflict and must never be overwritten.
+            const preliminary = collectRemoteSkillUpdatePlan(name, undefined, homeDir);
+            if (preliminary.action === "conflict") {
+                plans.push(preliminary);
+                continue;
+            }
+            try {
+                const repository = fetchRemoteRepository({ url: entry.source }, { branch: entry.requestedRef });
+                fetched.set(name, repository);
+                plans.push(collectRemoteSkillUpdatePlan(name, repository, homeDir));
+            }
+            catch (error) {
+                plans.push({ name, action: "invalid-source", detail: error instanceof Error ? error.message : String(error), source: entry.source, requestedRef: entry.requestedRef, previousCommit: entry.commit, previousDigest: entry.digest, canonicalPath: join(homeDir, ".trellis", "skills", name) });
+            }
+        }
+        // Multiple requested updates behave as a safe batch: a bad tracked Skill
+        // does not leave the rest unexpectedly changed in the same command.
+        const blocked = plans.some((plan) => plan.action === "conflict" || plan.action === "not-tracked" || plan.action === "invalid-source");
+        const outcome = blocked ? { plans: plans.map(displayUpdatePlan) } : await applyRemoteSkillUpdatePlans(plans, { homeDir, dryRun: opts.dryRun });
+        if (opts.json) {
+            console.log(JSON.stringify(outcome, null, 2));
+        }
+        else {
+            if (opts.dryRun)
+                console.log("[dry run]");
+            for (const plan of plans)
+                console.log(`update ${plan.name}: [${plan.action}] ${plan.detail}`);
+            if (outcome.sync)
+                printSyncReport(outcome.sync, false);
+        }
+        const syncConflict = outcome.sync?.reports.some((report) => report.items.some((item) => item.action === "conflict")) ?? false;
+        return { exitCode: blocked || syncConflict ? 1 : 0 };
+    }
+    finally {
+        for (const repository of fetched.values())
+            repository.dispose();
+    }
+}
+/** Used by Skill listing to distinguish remote provenance from local content
+ * without making a malformed bookkeeping file crash a read-only list. */
+export function remoteSkillProvenance(homeDir) {
+    const lock = readRemoteSkillLock(homeDir);
+    return lock.ok ? lock.lock.skills : emptyRemoteSkillLock().skills;
+}

package/dist/commands/rollback.js

@@ -8,11 +8,12 @@
  * already hold themselves to for every other kind of conflict.
  */
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { readlink, rm, symlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { backupsRoot } from "../lib/backup.js";
+import { directoryDigest } from "../lib/dirDigest.js";
 function sha256(content) {
     return `sha256:${createHash("sha256").update(content).digest("hex")}`;
 }
@@ -99,6 +100,49 @@ async function planOperation(homeDir, runId, op) {
             }
             return { action: "restore", path: op.path, description: `recreate ${op.path} -> ${op.beforeLinkTarget}` };
         }
+        // Historical `dir-remove` operations remain existence-only because they
+        // predate directory manifests. New directory creates/replacements carry a
+        // deterministic digest, so remote Skill rollback refuses an edited tree.
+        case "dir-create": {
+            if (!existsSync(op.path)) {
+                return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
+            }
+            if (op.afterDigest !== undefined) {
+                let digest;
+                try {
+                    digest = directoryDigest(op.path);
+                }
+                catch {
+                    return { action: "conflict", path: op.path, description: `${op.path} can no longer be read safely — left untouched` };
+                }
+                if (digest !== op.afterDigest) {
+                    return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
+                }
+            }
+            return { action: "restore", path: op.path, description: `delete ${op.path} (created by this run)` };
+        }
+        case "dir-remove": {
+            if (existsSync(op.path)) {
+                return { action: "conflict", path: op.path, description: `${op.path} exists again since this run — left untouched` };
+            }
+            return { action: "restore", path: op.path, description: `recreate ${op.path} from its content before this run (${join(runDir, op.beforeDir)})` };
+        }
+        case "dir-replace": {
+            if (!existsSync(op.path)) {
+                return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
+            }
+            let digest;
+            try {
+                digest = directoryDigest(op.path);
+            }
+            catch {
+                return { action: "conflict", path: op.path, description: `${op.path} can no longer be read safely — left untouched` };
+            }
+            if (digest !== op.afterDigest) {
+                return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
+            }
+            return { action: "restore", path: op.path, description: `restore ${op.path} to its content before this run (${join(runDir, op.beforeDir)})` };
+        }
     }
 }
 export async function collectRollbackPlan(homeDirInput, runIdInput) {
@@ -130,6 +174,16 @@ async function restoreOperation(homeDir, runId, op) {
         case "symlink-remove":
             await symlink(op.beforeLinkTarget, op.path);
             return;
+        case "dir-create":
+            rmSync(op.path, { recursive: true, force: true });
+            return;
+        case "dir-remove":
+            cpSync(join(runDir, op.beforeDir), op.path, { recursive: true });
+            return;
+        case "dir-replace":
+            rmSync(op.path, { recursive: true, force: true });
+            cpSync(join(runDir, op.beforeDir), op.path, { recursive: true });
+            return;
     }
 }
 export async function applyRollbackPlan(homeDir, runId, manifest, items) {

package/dist/commands/secretsAudit.js

@@ -26,7 +26,9 @@ import { loadCanonicalSource } from "../core/canonical.js";
 import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
-import { declaredEnvNames, extractJsonEnvVarNames, extractTomlEnvVarNames } from "../lib/envVarNames.js";
+import { ZcodeAdapter } from "../adapters/zcode.js";
+import { declaredEnvNames, extractJsonEnvVarNames, extractTomlEnvVarNames, extractZcodeEnvVarNames } from "../lib/envVarNames.js";
+import { resolveZcodeProfile } from "../probes/zcode.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 /** Only agents in `managedAgents` — a present-but-unmanaged agent's config
  * file is never even read (trellis-managed-agents), same restriction as
@@ -38,6 +40,7 @@ function auditedAgents(homeDir, managedAgents) {
         { id: "claude-code", probe: () => new ClaudeCodeAdapter(homeDir).probe(), configPath: (h) => join(h, ".claude.json"), extractNames: extractJsonEnvVarNames },
         { id: "codex", probe: () => new CodexAdapter(homeDir).probe(), configPath: (h) => join(h, ".codex", "config.toml"), extractNames: extractTomlEnvVarNames },
         { id: "kiro", probe: () => new KiroAdapter(homeDir).probe(), configPath: (h) => join(h, ".kiro", "settings", "mcp.json"), extractNames: extractJsonEnvVarNames },
+        { id: "zcode", probe: () => new ZcodeAdapter(homeDir).probe(), configPath: (h) => resolveZcodeProfile(h)?.configPath ?? join(h, ".zcode", "cli", "config.json"), extractNames: extractZcodeEnvVarNames },
     ];
     return all.filter((a) => managedAgents.includes(a.id));
 }

package/dist/commands/skill.d.ts

@@ -9,6 +9,8 @@
  */
 import type { AgentId } from "../core/types.js";
 import { type BackupSession } from "../lib/backup.js";
+import type { SyncReport } from "./sync.js";
+import type { RemoteSkillLockEntry } from "../lib/remoteSkillLock.js";
 export type BuiltinSkillUpdateAction = "create" | "update" | "already-current";
 export interface BuiltinSkillUpdatePlan {
     name: "trellis-runtime";
@@ -28,6 +30,7 @@ export declare function runSkillUpdateBuiltin(opts?: {
 export interface SkillListEntry {
     name: string;
     scope: readonly AgentId[];
+    remote?: Pick<RemoteSkillLockEntry, "source" | "requestedRef" | "commit" | "subdirectory" | "digest">;
 }
 export declare function collectSkillList(homeDir?: string): SkillListEntry[];
 export declare function runSkillList(opts?: {
@@ -44,25 +47,53 @@ export interface SkillAddPlan {
     sourceDir?: string;
 }
 export declare function collectSkillAddPlan(name: string, fromPath: string, homeDir?: string): SkillAddPlan;
-export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string): void;
+export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string, backup?: BackupSession): void;
+export interface SkillAddOutcome {
+    plan: SkillAddPlan;
+    sync?: SyncReport;
+}
+/**
+ * See `applyMcpAddWithSync`'s doc comment (mcp.ts) — same split, same
+ * reason: a non-CLI caller needs the structured result a JSON-mode CLI
+ * run prints, without scraping stdout. Also opens its own backup session
+ * around the canonical copy-in, for the same reason `applyMcpAddWithSync`
+ * does (trellis-gui tasks.md 3.5): this direct write used to be the one
+ * path in this file with no backup/rollback trace at all.
+ */
+export declare function applySkillAddWithSync(plan: SkillAddPlan, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<SkillAddOutcome>;
 export declare function runSkillAdd(name: string, fromPath: string, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
-}): {
+}): Promise<{
     exitCode: number;
-};
+}>;
 export type SkillRemoveAction = "removed" | "not-found";
 export interface SkillRemovePlan {
     name: string;
     action: SkillRemoveAction;
 }
 export declare function collectSkillRemovePlan(name: string, homeDir?: string): SkillRemovePlan;
-export declare function applySkillRemovePlan(plan: SkillRemovePlan, homeDir?: string): void;
+export declare function applySkillRemovePlan(plan: SkillRemovePlan, homeDir?: string, backup?: BackupSession): void;
+export interface SkillRemoveOutcome {
+    plan: SkillRemovePlan;
+    sync?: SyncReport;
+}
+/** See `applySkillAddWithSync`'s doc comment — same split, same reason,
+ * same own-backup-session fix. */
+export declare function applySkillRemoveWithSync(plan: SkillRemovePlan, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<SkillRemoveOutcome>;
 export declare function runSkillRemove(name: string, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
-}): {
+}): Promise<{
     exitCode: number;
-};
+}>;