agent-trellis 0.7.0 → 0.8.2

package/dist/commands/rollback.js

@@ -8,7 +8,7 @@
  * 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";
@@ -99,6 +99,23 @@ async function planOperation(homeDir, runId, op) {
             }
             return { action: "restore", path: op.path, description: `recreate ${op.path} -> ${op.beforeLinkTarget}` };
         }
+        // Directory conflict detection is existence-only, not a deep content
+        // hash (see BackupOperation's "dir-create"/"dir-remove" doc comment
+        // in backup.ts) — a real, documented simplification, not an
+        // oversight: something touching a file inside an otherwise-untouched
+        // directory won't be caught as a conflict.
+        case "dir-create": {
+            if (!existsSync(op.path)) {
+                return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
+            }
+            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)})` };
+        }
     }
 }
 export async function collectRollbackPlan(homeDirInput, runIdInput) {
@@ -130,11 +147,20 @@ 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;
     }
 }
 export async function applyRollbackPlan(homeDir, runId, manifest, items) {
     const restorePaths = new Set(items.filter((i) => i.action === "restore").map((i) => i.path));
-    for (const op of manifest.operations) {
+    // Restore in reverse write order. A single onboarding transaction may
+    // update servers.yaml several times (mode, memory, routes); replaying
+    // restores forward would leave the file at an intermediate snapshot.
+    for (const op of [...manifest.operations].reverse()) {
         if (!restorePaths.has(op.path))
             continue;
         await restoreOperation(homeDir, runId, op);

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

@@ -8,6 +8,24 @@
  * symlinkPlan.ts`'s pre-existing stale-symlink removal.
  */
 import type { AgentId } from "../core/types.js";
+import { type BackupSession } from "../lib/backup.js";
+import type { SyncReport } from "./sync.js";
+export type BuiltinSkillUpdateAction = "create" | "update" | "already-current";
+export interface BuiltinSkillUpdatePlan {
+    name: "trellis-runtime";
+    action: BuiltinSkillUpdateAction;
+    detail: string;
+    path: string;
+}
+export declare function collectBuiltinSkillUpdatePlan(homeDir?: string): BuiltinSkillUpdatePlan;
+export declare function applyBuiltinSkillUpdatePlan(plan: BuiltinSkillUpdatePlan, backup?: BackupSession): void;
+export declare function runSkillUpdateBuiltin(opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};
 export interface SkillListEntry {
     name: string;
     scope: readonly AgentId[];
@@ -27,25 +45,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;
-};
+}>;

package/dist/commands/skill.js

@@ -7,16 +7,57 @@
  * `decideDirImport` (src/lib/dirEquals.ts) and `src/adapters/
  * symlinkPlan.ts`'s pre-existing stale-symlink removal.
  */
-import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { findSkillFile } from "../lib/skillFile.js";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { resolveScope } from "../core/types.js";
+import { isBuiltinSkillName } from "../lib/builtinSkills.js";
+import { openBackupSession } from "../lib/backup.js";
+import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
+function builtinSkillTemplate() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
+}
+export function collectBuiltinSkillUpdatePlan(homeDir = homedir()) {
+    const path = join(homeDir, ".trellis", "skills", "trellis-runtime", "SKILL.md");
+    if (!existsSync(path))
+        return { name: "trellis-runtime", action: "create", detail: "will install the package-owned Runtime Skill", path };
+    if (readFileSync(path, "utf8") === builtinSkillTemplate())
+        return { name: "trellis-runtime", action: "already-current", detail: "package-owned Runtime Skill is already current", path };
+    return { name: "trellis-runtime", action: "update", detail: "will refresh the package-owned Runtime Skill; existing Agent symlinks will see the update", path };
+}
+export function applyBuiltinSkillUpdatePlan(plan, backup) {
+    if (plan.action === "already-current")
+        return;
+    const content = builtinSkillTemplate();
+    mkdirSync(dirname(plan.path), { recursive: true });
+    if (backup)
+        backup.writeFile(plan.path, content);
+    else
+        writeFileSync(plan.path, content);
+}
+export function runSkillUpdateBuiltin(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectBuiltinSkillUpdatePlan(homeDir);
+    if (!opts.dryRun && plan.action !== "already-current") {
+        const backup = openBackupSession(homeDir, "skill-update-builtin");
+        applyBuiltinSkillUpdatePlan(plan, backup);
+        backup.finalize();
+    }
+    if (opts.json)
+        console.log(JSON.stringify(plan, null, 2));
+    else
+        console.log(`${opts.dryRun ? "[dry run] " : ""}skill update-builtin\n  [${plan.action}] ${plan.detail}`);
+    return { exitCode: 0 };
+}
 export function collectSkillList(homeDir = homedir()) {
     const canonical = loadCanonicalSource(homeDir);
-    return canonical.skills.map((skill) => ({
+    return canonical.skills.filter((skill) => !isBuiltinSkillName(skill.name)).map((skill) => ({
         name: skill.name,
         scope: resolveScope(skill.scope, canonical.managedAgents),
     }));
@@ -37,6 +78,9 @@ export function runSkillList(opts = {}) {
     return { exitCode: 0 };
 }
 export function collectSkillAddPlan(name, fromPath, homeDir = homedir()) {
+    if (isBuiltinSkillName(name)) {
+        return { name, action: "conflict", detail: `"${name}" is a Trellis package-owned Skill and cannot be replaced with skill add` };
+    }
     const skillFile = findSkillFile(fromPath);
     if (!skillFile) {
         return { name, action: "invalid-source", detail: `${fromPath} has no SKILL.md` };
@@ -54,51 +98,106 @@ export function collectSkillAddPlan(name, fromPath, homeDir = homedir()) {
             return { name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
     }
 }
-export function applySkillAddPlan(plan, homeDir = homedir()) {
+export function applySkillAddPlan(plan, homeDir = homedir(), backup) {
     if (plan.action !== "create" || !plan.sourceDir)
         return;
     const dest = join(homeDir, ".trellis", "skills", plan.name);
+    if (backup) {
+        backup.createDirFromSource(dest, plan.sourceDir);
+        return;
+    }
     mkdirSync(dest, { recursive: true });
     cpSync(plan.sourceDir, dest, { recursive: true });
 }
-export function runSkillAdd(name, fromPath, opts = {}) {
+/**
+ * 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 async function applySkillAddWithSync(plan, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const plan = collectSkillAddPlan(name, fromPath, homeDir);
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "create" ? openBackupSession(homeDir, "skill-add") : undefined;
+    const session = opts.backupSession ?? ownSession;
     if (!opts.dryRun && plan.action === "create") {
-        applySkillAddPlan(plan, homeDir);
+        applySkillAddPlan(plan, homeDir, session);
+    }
+    ownSession?.finalize();
+    const failed = plan.action === "conflict" || plan.action === "invalid-source";
+    let syncReport;
+    if (!failed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectSyncReport({ target: "skills", homeDir, dryRun: opts.dryRun });
     }
+    return { plan, ...(syncReport ? { sync: syncReport } : {}) };
+}
+export async function runSkillAdd(name, fromPath, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectSkillAddPlan(name, fromPath, homeDir);
+    const { sync: syncReport } = await applySkillAddWithSync(plan, { homeDir, dryRun: opts.dryRun });
+    const failed = plan.action === "conflict" || plan.action === "invalid-source";
     if (opts.json) {
-        console.log(JSON.stringify(plan, null, 2));
+        console.log(JSON.stringify(syncReport ? { ...plan, sync: syncReport } : plan, null, 2));
     }
     else {
         console.log(`${opts.dryRun ? "[dry run] " : ""}skill add ${name}`);
         console.log(`  [${plan.action}] ${plan.detail}`);
+        if (syncReport)
+            printSyncReport(syncReport, opts.dryRun ?? false);
     }
-    return { exitCode: plan.action === "conflict" || plan.action === "invalid-source" ? 1 : 0 };
+    const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+    return { exitCode: failed || syncConflict ? 1 : 0 };
 }
 export function collectSkillRemovePlan(name, homeDir = homedir()) {
+    if (isBuiltinSkillName(name))
+        return { name, action: "not-found" };
     const dir = join(homeDir, ".trellis", "skills", name);
     return { name, action: existsSync(dir) ? "removed" : "not-found" };
 }
-export function applySkillRemovePlan(plan, homeDir = homedir()) {
+export function applySkillRemovePlan(plan, homeDir = homedir(), backup) {
     if (plan.action !== "removed")
         return;
-    rmSync(join(homeDir, ".trellis", "skills", plan.name), { recursive: true, force: true });
+    const dir = join(homeDir, ".trellis", "skills", plan.name);
+    if (backup) {
+        backup.removeDir(dir);
+        return;
+    }
+    rmSync(dir, { recursive: true, force: true });
 }
-export function runSkillRemove(name, opts = {}) {
+/** See `applySkillAddWithSync`'s doc comment — same split, same reason,
+ * same own-backup-session fix. */
+export async function applySkillRemoveWithSync(plan, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const plan = collectSkillRemovePlan(name, homeDir);
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "removed" ? openBackupSession(homeDir, "skill-remove") : undefined;
+    const session = opts.backupSession ?? ownSession;
     if (!opts.dryRun) {
-        applySkillRemovePlan(plan, homeDir);
+        applySkillRemovePlan(plan, homeDir, session);
     }
+    ownSession?.finalize();
+    const failed = plan.action === "not-found";
+    let syncReport;
+    if (!failed && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectSyncReport({ target: "skills", homeDir, dryRun: opts.dryRun });
+    }
+    return { plan, ...(syncReport ? { sync: syncReport } : {}) };
+}
+export async function runSkillRemove(name, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectSkillRemovePlan(name, homeDir);
+    const { sync: syncReport } = await applySkillRemoveWithSync(plan, { homeDir, dryRun: opts.dryRun });
+    const failed = plan.action === "not-found";
     if (opts.json) {
-        console.log(JSON.stringify(plan, null, 2));
+        console.log(JSON.stringify(syncReport ? { ...plan, sync: syncReport } : plan, null, 2));
     }
     else if (plan.action === "not-found") {
         console.error(`"${name}" is not a canonical skill — nothing to remove.`);
     }
     else {
         console.log(`${opts.dryRun ? "[dry run] " : ""}removed skill "${name}" from canonical source.`);
+        if (syncReport)
+            printSyncReport(syncReport, opts.dryRun ?? false);
     }
-    return { exitCode: plan.action === "not-found" ? 1 : 0 };
+    const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+    return { exitCode: failed || syncConflict ? 1 : 0 };
 }

package/dist/commands/sync.js

@@ -11,12 +11,16 @@ import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
 import { PiAdapter } from "../adapters/pi.js";
+import { KimiCodeAdapter } from "../adapters/kimi-code.js";
+import { ZcodeAdapter } from "../adapters/zcode.js";
 import { openBackupSession } from "../lib/backup.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
     codex: (homeDir) => new CodexAdapter(homeDir),
     kiro: (homeDir) => new KiroAdapter(homeDir),
     pi: (homeDir) => new PiAdapter(homeDir),
+    "kimi-code": (homeDir) => new KimiCodeAdapter(homeDir),
+    zcode: (homeDir) => new ZcodeAdapter(homeDir),
 };
 /** Only agents in `canonical.managedAgents` — an agent present on this
  * machine but not managed gets no adapter at all, not a zero-item plan
@@ -58,7 +62,7 @@ export async function collectSyncReport(opts = {}) {
             // out (found via the sandbox: every agent reported "already in
             // sync" even with real create items pending).
             const kind = opts.target === "skills" ? "skill" : "instructions";
-            items = items.filter((item) => item.kind === kind);
+            items = items.filter((item) => item.kind === kind || (kind === "skill" && item.kind === "zcode-skill-control"));
         }
         if (!opts.dryRun) {
             await adapter.apply(items, backup);

package/dist/core/adapter.d.ts

@@ -46,7 +46,7 @@ export interface AdapterPlanItem {
      * a completely different target file and merge mechanism (see
      * `approvedEnvVars` below) from `"mcp"`, not something the other
      * three agents have an equivalent of. */
-    kind: "skill" | "instructions" | "mcp" | "extension" | "kiro-approved-env-vars";
+    kind: "skill" | "instructions" | "mcp" | "extension" | "kiro-approved-env-vars" | "zcode-skill-control";
     /** Human-readable description of one change this adapter would make
      * ("create" / "remove") or why it refused to ("conflict"). */
     description: string;
@@ -88,6 +88,16 @@ export interface AdapterPlanItem {
      * for Kiro, never a subtraction (trellis-kiro-approved-env-vars
      * design.md D3/D4). */
     approvedEnvVars?: string[];
+    /** ZCode Runtime-only isolation. `null` means the previous profile did
+     * not declare the value and restoration must remove the property. */
+    zcodeSkillControls?: {
+        featuresSkill: boolean | null;
+        skillsEnabled: boolean | null;
+        previous?: {
+            featuresSkill: boolean | null;
+            skillsEnabled: boolean | null;
+        };
+    };
 }
 export interface AdapterVerifyResult {
     ok: boolean;

package/dist/core/canonical.d.ts

@@ -4,7 +4,8 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import type { AgentId, CanonicalSource, McpServerDef } from "./types.js";
+import type { AgentId, CapabilityDelivery, CanonicalSource, McpRoute, McpServerDef } from "./types.js";
+import type { BackupSession } from "../lib/backup.js";
 /**
  * The on-disk shape for one server entry — `static_env`/`env_aliases`
  * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
@@ -27,10 +28,10 @@ export type ServersYamlWriteResult = {
     ok: false;
     error: string;
 };
-export declare function upsertServerYaml(path: string, name: string, def: McpServerDef): ServersYamlWriteResult;
+export declare function upsertServerYaml(path: string, name: string, def: McpServerDef, backup?: BackupSession): ServersYamlWriteResult;
 /** Inverse of `upsertServerYaml` — same preservation guarantee, same
  * refusal posture on a missing/unparseable file. */
-export declare function removeServerYaml(path: string, name: string): ServersYamlWriteResult;
+export declare function removeServerYaml(path: string, name: string, backup?: BackupSession): ServersYamlWriteResult;
 /**
  * `trellis onboard --mcp-mode <value>` (trellis-onboard-mcp-mode) —
  * everything needed to select or clear the top-level `hub`/`gateway`
@@ -56,7 +57,14 @@ export type McpMode = {
  * starter file). Selecting one mode always clears the other two
  * (design.md D3) — never left for the caller to remember.
  */
-export declare function writeMcpModeYaml(path: string, mode: McpMode): ServersYamlWriteResult;
+export declare function writeMcpModeYaml(path: string, mode: McpMode, backup?: BackupSession): ServersYamlWriteResult;
+export type McpRoutesWriteResult = ServersYamlWriteResult;
+/** Writes explicit per-agent routes while preserving legacy hub/gateway
+ * shorthand. An empty route map removes the optional key. */
+export declare function writeMcpRoutesYaml(path: string, routes: Partial<Record<AgentId, McpRoute>>, backup?: BackupSession): McpRoutesWriteResult;
+/** Writes per-agent capability delivery preferences into servers.yaml.
+ * Omitted entries continue to use the native default. */
+export declare function writeMcpRuntimeDeliveryYaml(path: string, delivery: Partial<Record<AgentId, CapabilityDelivery>>, backup?: BackupSession): ServersYamlWriteResult;
 export type SecretsPolicyWriteResult = {
     ok: true;
 } | {
@@ -78,7 +86,7 @@ export type SecretsPolicyWriteResult = {
 export declare function writeSecretsPolicyExtraction(path: string, extraction: {
     varName: string;
     envFilePath: string;
-}): SecretsPolicyWriteResult;
+}, backup?: BackupSession): SecretsPolicyWriteResult;
 /**
  * Ensures one exact line is present in a `.gitignore` file, creating the
  * file if it doesn't exist yet — idempotent (a no-op if the line is
@@ -89,7 +97,7 @@ export declare function writeSecretsPolicyExtraction(path: string, extraction: {
  * init`'s own bootstrap, so a machine that never extracts a secret never
  * gains this file at all.
  */
-export declare function ensureGitignoreEntry(gitignorePath: string, line: string): void;
+export declare function ensureGitignoreEntry(gitignorePath: string, line: string, backup?: BackupSession): void;
 /**
  * Ensures a shell rc file sources the local secrets env file on every new
  * shell — one generic pointer block, appended once, idempotent (detected
@@ -102,7 +110,7 @@ export declare function ensureGitignoreEntry(gitignorePath: string, line: string
  * lines `parseDotenv` already expects, so that format never needs an
  * `export` prefix of its own.
  */
-export declare function ensureShellEnvSource(rcPath: string, envFilePath: string): void;
+export declare function ensureShellEnvSource(rcPath: string, envFilePath: string, backup?: BackupSession): void;
 /**
  * `homeDir` defaults to the real `~` and is only ever overridden for tests
  * and `scripts/sandbox.sh` — the same seam P0's probes use