@fission-ai/openspec 1.7.0 → 1.9.0

package/README.md

@@ -248,7 +248,9 @@ OpenSpec collects anonymous usage stats.
 
 We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
 
-**Opt-out:** `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`
+**Opt-out (any one is enough):**
+- `openspec config set telemetry.enabled false` (global config; unset means on)
+- `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1` (env overrides config)
 
 </details>
 

package/dist/cli/index.d.ts

@@ -5,6 +5,21 @@ declare const program: Command;
  * For example: 'change show' -> 'change:show'
  */
 export declare function getCommandPath(command: Command): string;
+/**
+ * True when the executing command asked for JSON output — used to suppress the
+ * first-run telemetry notice so stdout stays a single valid JSON document.
+ *
+ * `--json` reaches commands three ways, so a single parsed option is not enough:
+ * - declared on the leaf (`openspec status --json`) → `opts().json`
+ * - declared on a parent group and read via globals (`openspec workset --json list`)
+ *   → `optsWithGlobals().json`
+ * - a residual arg on a permissive group that never declares the option
+ *   (`openspec store --json`, which detects it from `command.args`) → `args`
+ *
+ * Suppressing is always safe: the disclosure is only deferred to the next
+ * non-JSON run, never lost, whereas printing it on a JSON run corrupts stdout.
+ */
+export declare function isJsonRun(command: Command): boolean;
 export { program };
 export declare function runCli(argv?: string[]): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import { createRequire } from 'module';
 import ora from 'ora';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { promises as fs } from 'fs';
+import { existsSync, promises as fs } from 'fs';
 import { AI_TOOLS, TOOL_ID_ALIASES } from '../core/config.js';
 import { UpdateCommand } from '../core/update.js';
 import { getAvailableCliUpdate, displayCliUpdateNote, shouldOfferUpgrade, getInstallDir, offerCliUpgrade, rerunUpdateWithUpgradedCli, displayUpgradeCommand, isSourceCheckout, } from '../core/version-check.js';
@@ -72,6 +72,24 @@ export function getCommandPath(command) {
     }
     return names.join(':') || 'openspec';
 }
+/**
+ * True when the executing command asked for JSON output — used to suppress the
+ * first-run telemetry notice so stdout stays a single valid JSON document.
+ *
+ * `--json` reaches commands three ways, so a single parsed option is not enough:
+ * - declared on the leaf (`openspec status --json`) → `opts().json`
+ * - declared on a parent group and read via globals (`openspec workset --json list`)
+ *   → `optsWithGlobals().json`
+ * - a residual arg on a permissive group that never declares the option
+ *   (`openspec store --json`, which detects it from `command.args`) → `args`
+ *
+ * Suppressing is always safe: the disclosure is only deferred to the next
+ * non-JSON run, never lost, whereas printing it on a JSON run corrupts stdout.
+ */
+export function isJsonRun(command) {
+    return (command.optsWithGlobals().json === true ||
+        command.args.includes('--json'));
+}
 program
     .name('openspec')
     .description('AI-native system for spec-driven development')
@@ -87,8 +105,9 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
-    // Show first-run telemetry notice (if not seen)
-    await maybeShowTelemetryNotice();
+    // Show first-run telemetry notice (if not seen). Suppress it whenever the run
+    // asked for JSON so stdout stays a single valid JSON document (see isJsonRun).
+    await maybeShowTelemetryNotice({ silent: isJsonRun(actionCommand) });
     // Track command execution (use actionCommand to get the actual subcommand)
     const commandPath = getCommandPath(actionCommand);
     await trackCommand(commandPath, version);
@@ -97,7 +116,9 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
 program.hook('postAction', async () => {
     await shutdown();
 });
-const availableToolIds = AI_TOOLS.filter((tool) => tool.skillsDir).map((tool) => tool.value);
+const availableToolIds = AI_TOOLS
+    .filter((tool) => tool.skillsDir || tool.globalSkillsDir)
+    .map((tool) => tool.value);
 const toolAliasNote = Object.entries(TOOL_ID_ALIASES)
     .map(([retired, current]) => `${retired} (now ${current})`)
     .join(', ');
@@ -109,6 +130,8 @@ program
     .option('--force', 'Auto-cleanup legacy files without prompting')
     .option('--profile <profile>', 'Override global config profile (core or custom)')
     .option('--no-animation', 'Show a static welcome screen instead of the animated one')
+    .option('--copilot-cloud', 'Set up GitHub Copilot cloud coding-agent files without prompting')
+    .option('--no-copilot-cloud', 'Skip GitHub Copilot cloud coding-agent files without prompting')
     .action(async (targetPath = '.', options) => {
     try {
         // Validate that the path is a valid directory
@@ -137,6 +160,7 @@ program
             force: options?.force,
             profile: options?.profile,
             animation: options?.animation,
+            copilotCloud: options?.copilotCloud,
         });
         await initCommand.execute(targetPath);
     }
@@ -241,6 +265,9 @@ program
         const root = await resolveRootForCommand(options ?? {}, {
             json: options?.json,
             failurePayload: options?.specs ? { specs: [], root: null } : { changes: [], root: null },
+            // Preserve the cwd fallback for pre-config.yaml projects. The resolver
+            // still lets a registered/default store take precedence over it.
+            allowImplicitRoot: existsSync(path.join(process.cwd(), 'openspec', 'project.md')),
         });
         if (!root) {
             return;
@@ -378,6 +405,7 @@ program
     .option('--all', 'Validate all changes and specs')
     .option('--changes', 'Validate all changes')
     .option('--specs', 'Validate all specs')
+    .option('--archived', 'Validate that archived changes have all tasks completed (for pre-commit linting)')
     .option('--type <type>', 'Specify item type when ambiguous: change|spec')
     .option('--strict', 'Enable strict validation mode')
     .option('--json', 'Output validation results as JSON')
@@ -567,12 +595,18 @@ program
     .command('schemas')
     .description('List available workflow schemas with descriptions')
     .option('--json', 'Output as JSON (for agent use)')
+    .option('--store <id>', STORE_OPTION_DESCRIPTION)
+    .addOption(hiddenStorePathOption())
     .action(async (options) => {
     try {
         await schemasCommand(options);
     }
     catch (error) {
-        failWithError(error);
+        failWithError(error, {
+            enabled: options.json,
+            payload: { schemas: [], root: null },
+            fallbackCode: 'schemas_error',
+        });
         process.exit(1);
     }
 });

package/dist/commands/change.js

@@ -7,6 +7,7 @@ import { ChangeParser } from '../core/parsers/change-parser.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds } from '../utils/item-discovery.js';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
+import { FileSystemUtils } from '../utils/file-system.js';
 /**
  * True only when `target` is definitively absent. An EACCES or I/O failure
  * means existence cannot be determined, so callers fall through to their
@@ -95,12 +96,15 @@ export class ChangeCommand {
             }
             throw new Error(`Change "${changeName}" not found at ${proposalPath}`);
         }
+        FileSystemUtils.assertPathWithin(path.dirname(proposalPath), proposalPath);
         if (options?.json) {
+            FileSystemUtils.assertPathWithin(changeDir, proposalPath);
             const jsonOutput = await this.converter.convertChangeToJson(proposalPath);
             if (options.requirementsOnly) {
                 console.error('Flag --requirements-only is deprecated; use --deltas-only instead.');
             }
             const parsed = JSON.parse(jsonOutput);
+            FileSystemUtils.assertPathWithin(changeDir, proposalPath);
             const contentForTitle = await fs.readFile(proposalPath, 'utf-8');
             const title = this.extractTitle(contentForTitle, changeName);
             const id = parsed.name;
@@ -115,6 +119,7 @@ export class ChangeCommand {
             console.log(JSON.stringify(output, null, 2));
         }
         else {
+            FileSystemUtils.assertPathWithin(changeDir, proposalPath);
             const content = await fs.readFile(proposalPath, 'utf-8');
             console.log(content);
         }
@@ -147,6 +152,7 @@ export class ChangeCommand {
                     return { id: changeName, title: changeName, deltaCount: 0, taskStatus };
                 }
                 try {
+                    FileSystemUtils.assertPathWithin(changeDir, proposalPath);
                     const content = await fs.readFile(proposalPath, 'utf-8');
                     const parser = new ChangeParser(content, changeDir);
                     const change = await parser.parseChangeWithDeltas(changeName);
@@ -186,6 +192,7 @@ export class ChangeCommand {
                     continue;
                 }
                 try {
+                    FileSystemUtils.assertPathWithin(changeDir, proposalPath);
                     const content = await fs.readFile(proposalPath, 'utf-8');
                     const title = this.extractTitle(content, changeName);
                     const parser = new ChangeParser(content, changeDir);
@@ -225,6 +232,9 @@ export class ChangeCommand {
             }
         }
         const changeDir = path.join(changesPath, changeName);
+        if (!isChangeDirectoryName(changesPath, changeDir)) {
+            throw new Error(`Change "${changeName}" not found at ${changeDir}`);
+        }
         try {
             await fs.access(changeDir);
         }
@@ -232,7 +242,12 @@ export class ChangeCommand {
             throw new Error(`Change "${changeName}" not found at ${changeDir}`);
         }
         const validator = new Validator(options?.strict || false);
-        const report = await validator.validateChangeDeltaSpecs(changeDir);
+        const report = await validator.validateChangeDeltaSpecs(changeDir, {
+            // Derived from changesPath so the main specs come from the same root the
+            // change itself was resolved against.
+            mainSpecsDir: path.join(path.dirname(changesPath), 'specs'),
+            projectRoot: path.dirname(path.dirname(changesPath)),
+        });
         if (options?.json) {
             console.log(JSON.stringify(report, null, 2));
         }

package/dist/commands/config.d.ts

@@ -10,6 +10,11 @@ interface ProfileStateDiff {
     hasChanges: boolean;
     lines: string[];
 }
+interface WorkflowPromptMeta {
+    name: string;
+    description: string;
+}
+export declare const WORKFLOW_PROMPT_META: Record<string, WorkflowPromptMeta>;
 /**
  * Resolve the effective current profile state from global config defaults.
  */

package/dist/commands/config.js

@@ -8,7 +8,7 @@ import { OPENSPEC_DIR_NAME } from '../core/config.js';
 import { hasProjectConfigDrift } from '../core/profile-sync-drift.js';
 import { UpdateCommand } from '../core/update.js';
 import { asErrorMessage, isPromptCancellationError } from './shared-output.js';
-const WORKFLOW_PROMPT_META = {
+export const WORKFLOW_PROMPT_META = {
     propose: {
         name: 'Propose change',
         description: 'Create proposal, design, and tasks from a request',
@@ -29,6 +29,10 @@ const WORKFLOW_PROMPT_META = {
         name: 'Apply tasks',
         description: 'Implement tasks from the current change',
     },
+    update: {
+        name: 'Update change',
+        description: 'Revise the planning artifacts of an existing change',
+    },
     ff: {
         name: 'Fast-forward',
         description: 'Run a faster implementation workflow',

package/dist/commands/schema.js

@@ -1,9 +1,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { createHash } from 'node:crypto';
 import ora from 'ora';
-import { stringify as stringifyYaml } from 'yaml';
+import { stringify as stringifyYaml, parseDocument } from 'yaml';
 import { getSchemaDir, getProjectSchemasDir, getUserSchemasDir, getPackageSchemasDir, isSchemaDir, listSchemas, } from '../core/artifact-graph/resolver.js';
 import { parseSchema, SchemaValidationError } from '../core/artifact-graph/schema.js';
+import { FileSystemUtils } from '../utils/file-system.js';
 /**
  * Check all three locations for a schema and return which ones exist.
  */
@@ -129,21 +131,30 @@ function validateSchema(schemaDir, verbose = false) {
         }
         return { valid: false, issues };
     }
-    // Check template files exist
-    // Templates can be in schemaDir directly or in a templates/ subdirectory
+    // Check template files exist in the same directory used at runtime.
     if (verbose) {
         console.log('  Checking template files...');
     }
     for (const artifact of schema.artifacts) {
-        // Try templates subdirectory first (standard location), then root
-        const templatePathInTemplates = path.join(schemaDir, 'templates', artifact.template);
-        const templatePathInRoot = path.join(schemaDir, artifact.template);
-        if (!fs.existsSync(templatePathInTemplates) && !fs.existsSync(templatePathInRoot)) {
+        const templatesDir = path.join(schemaDir, 'templates');
+        const existingTemplatePath = path.join(templatesDir, artifact.template);
+        if (!fs.existsSync(existingTemplatePath)) {
             issues.push({
                 level: 'error',
                 path: `artifacts.${artifact.id}.template`,
                 message: `Template file '${artifact.template}' not found for artifact '${artifact.id}'`,
             });
+            continue;
+        }
+        try {
+            FileSystemUtils.assertPathWithin(templatesDir, existingTemplatePath);
+        }
+        catch {
+            issues.push({
+                level: 'error',
+                path: `artifacts.${artifact.id}.template`,
+                message: `Template file '${artifact.template}' points outside the schema templates directory`,
+            });
         }
     }
     // Dependency graph validation is already done by parseSchema
@@ -162,19 +173,121 @@ function isValidSchemaName(name) {
 /**
  * Copy a directory recursively.
  */
-function copyDirRecursive(src, dest) {
+function resolveSchemaCopyPath(allowedRoot, sourcePath) {
+    try {
+        const canonicalRoot = fs.realpathSync(allowedRoot);
+        const canonicalPath = fs.realpathSync(sourcePath);
+        FileSystemUtils.assertPathWithin(canonicalRoot, canonicalPath);
+        return canonicalPath;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Cannot fork schema with linked or unsupported entry: ${sourcePath}: ${detail}`, { cause: error });
+    }
+}
+function copyDirRecursive(src, dest, allowedRoot = src, ancestors = new Set()) {
+    const canonicalSrc = resolveSchemaCopyPath(allowedRoot, src);
+    if (ancestors.has(canonicalSrc)) {
+        throw new Error(`Cannot fork schema with a linked directory cycle: ${src}`);
+    }
+    ancestors.add(canonicalSrc);
     fs.mkdirSync(dest, { recursive: true });
-    const entries = fs.readdirSync(src, { withFileTypes: true });
-    for (const entry of entries) {
-        const srcPath = path.join(src, entry.name);
-        const destPath = path.join(dest, entry.name);
-        if (entry.isDirectory()) {
-            copyDirRecursive(srcPath, destPath);
+    try {
+        const entries = fs.readdirSync(src, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            const canonicalEntry = resolveSchemaCopyPath(allowedRoot, srcPath);
+            const stats = fs.statSync(canonicalEntry);
+            if (stats.isDirectory()) {
+                copyDirRecursive(canonicalEntry, destPath, allowedRoot, ancestors);
+            }
+            else if (stats.isFile()) {
+                // Dereference confined links so the fork is an independent schema.
+                fs.copyFileSync(canonicalEntry, destPath);
+            }
+            else {
+                throw new Error(`Cannot fork schema with linked or unsupported entry: ${srcPath}`);
+            }
         }
-        else {
-            fs.copyFileSync(srcPath, destPath);
+    }
+    finally {
+        ancestors.delete(canonicalSrc);
+    }
+}
+/**
+ * Verifies a schema tree before replacing or creating the fork destination.
+ */
+function assertSchemaTreeCanBeCopied(src, allowedRoot = src, ancestors = new Set()) {
+    const canonicalSrc = resolveSchemaCopyPath(allowedRoot, src);
+    if (ancestors.has(canonicalSrc)) {
+        throw new Error(`Cannot fork schema with a linked directory cycle: ${src}`);
+    }
+    ancestors.add(canonicalSrc);
+    try {
+        for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+            const entryPath = path.join(src, entry.name);
+            const canonicalEntry = resolveSchemaCopyPath(allowedRoot, entryPath);
+            const stats = fs.statSync(canonicalEntry);
+            if (stats.isDirectory()) {
+                assertSchemaTreeCanBeCopied(canonicalEntry, allowedRoot, ancestors);
+            }
+            else if (!stats.isFile()) {
+                throw new Error(`Cannot fork schema with linked or unsupported entry: ${entryPath}`);
+            }
         }
     }
+    finally {
+        ancestors.delete(canonicalSrc);
+    }
+}
+/**
+ * Produces a stable content fingerprint of a directory: a SHA-256 over every
+ * file's relative path AND its bytes (plus directory paths), walked in sorted
+ * order. Two directories with byte-identical trees produce the same digest, and
+ * ANY change to a file's contents, size, or the set of paths changes it. Used to
+ * detect a concurrent modification of a fork destination between the moment the
+ * overwrite is authorized and the moment it is actually moved/deleted, so those
+ * changes are never silently destroyed.
+ */
+function fingerprintDir(dir) {
+    const hash = createHash('sha256');
+    const walk = (current, rel) => {
+        const entries = fs
+            .readdirSync(current, { withFileTypes: true })
+            .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const abs = path.join(current, entry.name);
+            const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+            // Use the entry type from readdir (no separate lstat), then read the file
+            // directly — avoiding a stat-then-read check/use gap. Size is derived from
+            // the bytes actually read, so the digest still covers content and length.
+            if (entry.isDirectory()) {
+                hash.update(`D:${relPath}\n`);
+                walk(abs, relPath);
+            }
+            else if (entry.isFile()) {
+                const contents = fs.readFileSync(abs);
+                hash.update(`F:${relPath}:${contents.length}:`);
+                hash.update(contents);
+                hash.update('\n');
+            }
+            else {
+                // Symlinks / other entry types: record the type + path (and the link
+                // target when readable) so a swap of one for another is still detected.
+                let target = '';
+                try {
+                    target = fs.readlinkSync(abs);
+                }
+                catch {
+                    // Non-symlink or unreadable target; the type marker below suffices.
+                }
+                hash.update(`O:${relPath}:${target}\n`);
+            }
+        }
+    };
+    walk(dir, '');
+    return hash.digest('hex');
 }
 /**
  * Default artifacts with descriptions for schema init.
@@ -378,9 +491,9 @@ export function registerSchemaCommand(program) {
                             console.log(`    ${issue.level}: ${issue.message}`);
                         }
                     }
-                    if (anyInvalid) {
-                        process.exitCode = 1;
-                    }
+                }
+                if (anyInvalid) {
+                    process.exitCode = 1;
                 }
                 return;
             }
@@ -423,9 +536,11 @@ export function registerSchemaCommand(program) {
                     for (const issue of result.issues) {
                         console.log(`  ${issue.level}: ${issue.message}`);
                     }
-                    process.exitCode = 1;
                 }
             }
+            if (!result.valid) {
+                process.exitCode = 1;
+            }
         }
         catch (error) {
             if (options?.json) {
@@ -487,39 +602,158 @@ export function registerSchemaCommand(program) {
             // Determine source location
             const sourceResolution = getSchemaResolution(source, projectRoot);
             const sourceLocation = sourceResolution?.source || 'package';
+            // Validate the complete source before a forced fork removes anything.
+            const trustedSourceDir = fs.realpathSync(sourceDir);
+            assertSchemaTreeCanBeCopied(trustedSourceDir);
+            // Validate the source's schema content up front too, so a structurally
+            // invalid source is rejected before the --force path can remove an
+            // existing destination. This keeps `fork --force` atomic — an unusable
+            // source never destroys a valid destination — matching `schema init`,
+            // which likewise validates before it overwrites.
+            parseSchema(fs.readFileSync(path.join(trustedSourceDir, 'schema.yaml'), 'utf-8'));
             // Check destination
-            const destinationDir = path.join(getProjectSchemasDir(projectRoot), destinationName);
-            if (fs.existsSync(destinationDir)) {
-                if (!options?.force) {
-                    if (options?.json) {
-                        console.log(JSON.stringify({
-                            forked: false,
-                            error: `Schema '${destinationName}' already exists`,
-                            suggestion: 'Use --force to overwrite',
-                        }, null, 2));
+            const schemasDir = getProjectSchemasDir(projectRoot);
+            const destinationDir = path.join(schemasDir, destinationName);
+            // Reject a self-fork. Forking a schema onto itself with --force would
+            // otherwise remove the source at the replacement step below and then
+            // fail the copy, destroying the only copy of the schema. Resolve both
+            // sides to their real paths (realpathSync follows symlinks; path.resolve
+            // is a fallback only for a destination that does not exist yet) so a
+            // symlink or a `.`/`..` spelling of the same directory is still caught.
+            const resolvedDestination = fs.existsSync(destinationDir)
+                ? fs.realpathSync(destinationDir)
+                : path.resolve(destinationDir);
+            if (resolvedDestination === trustedSourceDir) {
+                throw new Error(`Cannot fork schema '${source}' onto itself; choose a different destination name`);
+            }
+            const destinationExists = fs.existsSync(destinationDir);
+            if (destinationExists && !options?.force) {
+                if (options?.json) {
+                    console.log(JSON.stringify({
+                        forked: false,
+                        error: `Schema '${destinationName}' already exists`,
+                        suggestion: 'Use --force to overwrite',
+                    }, null, 2));
+                }
+                else {
+                    console.error(`Error: Schema '${destinationName}' already exists at ${destinationDir}`);
+                    console.error('Use --force to overwrite');
+                }
+                process.exitCode = 1;
+                return;
+            }
+            // Fingerprint the destination the user authorized us to overwrite, BEFORE
+            // we spend time staging. Staging can take a while, and a concurrent
+            // process may edit the destination in that window; the fingerprint lets
+            // us detect such a change and abort rather than clobber it.
+            const authorizedDestinationFingerprint = destinationExists
+                ? fingerprintDir(destinationDir)
+                : null;
+            // Stage the complete fork in a temporary sibling directory first, then
+            // swap it into place. This keeps `fork --force` atomic: an existing
+            // destination is only removed once the new fork has been fully copied,
+            // name-updated, and (via the up-front parseSchema above) validated. Any
+            // failure while staging leaves both the source and the existing
+            // destination exactly as they were.
+            if (spinner)
+                spinner.start(`Forking '${source}' to '${destinationName}'...`);
+            fs.mkdirSync(schemasDir, { recursive: true });
+            const stagingDir = fs.mkdtempSync(path.join(schemasDir, '.fork-staging-'));
+            try {
+                copyDirRecursive(trustedSourceDir, stagingDir);
+                // Update name in the staged schema.yaml via yaml's Document API
+                // instead of re-serializing the parsed object, so block scalars,
+                // comments, and key order in the source schema.yaml survive the fork.
+                const stagedSchemaPath = path.join(stagingDir, 'schema.yaml');
+                const schemaContent = fs.readFileSync(stagedSchemaPath, 'utf-8');
+                const doc = parseDocument(schemaContent);
+                doc.set('name', destinationName);
+                fs.writeFileSync(stagedSchemaPath, doc.toString());
+                // Authoritative gate: validate the COMPLETED staged schema — the exact
+                // bytes we are about to install — not just the source at the pre-check.
+                // The source files copyDirRecursive reads can change mid-copy, so a
+                // source that was valid up front can still produce an invalid staged
+                // fork. Validating here, before ANY destructive step, guarantees we
+                // never install an invalid fork or delete a valid destination for one.
+                try {
+                    parseSchema(fs.readFileSync(stagedSchemaPath, 'utf-8'));
+                }
+                catch (validationError) {
+                    throw new Error(`The staged fork of '${source}' is not a valid schema (the source may have changed during copy); ` +
+                        `aborted, '${destinationName}' was not modified.`, { cause: validationError });
+                }
+                // Swap the staged fork into place. When a destination already exists,
+                // move it aside to a sibling backup FIRST, then install the staged
+                // fork; only once the install succeeds is the backup discarded. If the
+                // install rename itself fails (e.g. a Windows lock), the backup is
+                // moved back so the user's original destination is never lost.
+                if (destinationExists) {
+                    if (spinner)
+                        spinner.text = `Replacing existing schema '${destinationName}'...`;
+                    // Revalidate immediately before the destructive move: if the
+                    // destination changed on disk while we were staging (or was removed),
+                    // its fingerprint no longer matches what the user authorized. Abort
+                    // WITHOUT touching it, so the concurrent changes are preserved. The
+                    // outer catch cleans up staging.
+                    const currentFingerprint = fs.existsSync(destinationDir)
+                        ? fingerprintDir(destinationDir)
+                        : null;
+                    if (currentFingerprint !== authorizedDestinationFingerprint) {
+                        throw new Error(`Schema '${destinationName}' at ${destinationDir} changed on disk while the fork was being prepared. ` +
+                            `Aborted to preserve those concurrent changes; nothing was overwritten. Re-run the fork to overwrite the current contents.`);
+                    }
+                    const backupDir = `${destinationDir}.fork-backup-${process.pid}-${Date.now()}`;
+                    fs.renameSync(destinationDir, backupDir);
+                    try {
+                        fs.renameSync(stagingDir, destinationDir);
+                    }
+                    catch (installError) {
+                        // Install failed after the original was moved aside. Try to move
+                        // it back. If that restore ALSO fails, the original is stranded in
+                        // the backup dir — surface an error naming both the backup and the
+                        // destination so the user can recover manually, and attach the
+                        // original install error as the cause. Never swallow this.
+                        try {
+                            fs.renameSync(backupDir, destinationDir);
+                        }
+                        catch (restoreError) {
+                            throw new Error(`Failed to install the forked schema and could not restore the previous '${destinationName}'. ` +
+                                `Your previous schema is preserved at ${backupDir}; move it back to ${destinationDir} to restore. ` +
+                                `Restore error: ${restoreError.message}`, { cause: installError });
+                        }
+                        throw installError;
+                    }
+                    // Revalidate before discarding the backup: only delete it if it is
+                    // still byte-for-byte the original destination we moved aside. If it
+                    // changed during the install window (a concurrent write to the
+                    // moved-aside directory), do NOT delete it — leave it in place and
+                    // surface where it is so nothing is lost.
+                    if (fingerprintDir(backupDir) === authorizedDestinationFingerprint) {
+                        fs.rmSync(backupDir, { recursive: true, force: true });
                     }
                     else {
-                        console.error(`Error: Schema '${destinationName}' already exists at ${destinationDir}`);
-                        console.error('Use --force to overwrite');
+                        console.error(`Warning: the previous '${destinationName}' changed during the fork and was NOT deleted; ` +
+                            `its pre-fork copy is preserved at ${backupDir}.`);
                     }
-                    process.exitCode = 1;
-                    return;
                 }
-                // Remove existing
-                if (spinner)
-                    spinner.start(`Removing existing schema '${destinationName}'...`);
-                fs.rmSync(destinationDir, { recursive: true });
+                else {
+                    fs.renameSync(stagingDir, destinationDir);
+                }
+            }
+            catch (error) {
+                // Remove only the staging directory we created this run; the source
+                // and any existing destination are left exactly as we found them.
+                // Guard the cleanup in its own try/catch so a failed removal (e.g. a
+                // locked file on Windows) can never mask the original error, then
+                // rethrow so the real failure still drives the JSON/exit-code report.
+                try {
+                    fs.rmSync(stagingDir, { recursive: true, force: true });
+                }
+                catch {
+                    // Best-effort cleanup; the original error below is what matters.
+                }
+                throw error;
             }
-            // Copy schema
-            if (spinner)
-                spinner.start(`Forking '${source}' to '${destinationName}'...`);
-            copyDirRecursive(sourceDir, destinationDir);
-            // Update name in schema.yaml
-            const destSchemaPath = path.join(destinationDir, 'schema.yaml');
-            const schemaContent = fs.readFileSync(destSchemaPath, 'utf-8');
-            const schema = parseSchema(schemaContent);
-            schema.name = destinationName;
-            fs.writeFileSync(destSchemaPath, stringifyYaml(schema));
             if (spinner)
                 spinner.succeed(`Forked '${source}' to '${destinationName}'`);
             if (options?.json) {