@stacksjs/defaults 0.75.360 → 0.75.362

package/ai/skills/stacks-technical-diagrams/bin/open-artifact.mjs

@@ -5,28 +5,78 @@ const OPENERS = {
   darwin: {
     command: 'open',
     method: 'open',
+    timeoutMs: 5000,
     args: (target) => [target],
   },
   linux: {
     command: 'xdg-open',
     method: 'xdg-open',
+    timeoutMs: 5000,
     args: (target) => [target],
   },
   win32: {
     command: 'powershell.exe',
     method: 'powershell',
-    // Keep the command constant and pass the target through PowerShell's
-    // argument array. Paths are never interpolated into executable source.
-    args: (target) => [
+    // PowerShell cold starts can approach five seconds on hosted Windows
+    // runners. Keep the launch bounded without treating normal startup as a
+    // timeout.
+    timeoutMs: 15000,
+    // Keep the command constant and pass the target through a child-only
+    // environment variable. Paths are never interpolated into executable source.
+    args: () => [
       '-NoProfile',
       '-NonInteractive',
       '-Command',
-      'Start-Process -FilePath $args[0]',
-      target,
+      'Start-Process -FilePath $env:ARCHIFY_OPEN_TARGET',
     ],
   },
 };
 
+function failureDetails(result, opener, timeoutMs) {
+  const error = result?.error;
+  if (error?.code === 'ENOENT') {
+    return {
+      code: 'opener/unavailable',
+      reason: `Could not find ${opener.command}. Install or enable the platform opener, then open the target manually.`,
+      systemCode: 'ENOENT',
+    };
+  }
+  if (error?.code === 'ETIMEDOUT') {
+    return {
+      code: 'opener/timeout',
+      reason: `${opener.command} did not finish within ${timeoutMs}ms. Open the target manually or retry when the system is less busy.`,
+      systemCode: 'ETIMEDOUT',
+      timeoutMs,
+    };
+  }
+  if (error) {
+    return {
+      code: 'opener/spawn-failed',
+      reason: error.message || `${opener.command} could not be started. Open the target manually.`,
+      ...(error.code ? { systemCode: String(error.code) } : {}),
+    };
+  }
+  if (result?.signal) {
+    return {
+      code: 'opener/signaled',
+      reason: `${opener.command} was terminated by ${result.signal}. Open the target manually.`,
+      signal: result.signal,
+    };
+  }
+  if (result?.status !== 0) {
+    return {
+      code: 'opener/nonzero-exit',
+      reason: `${opener.command} exited with status ${result?.status ?? 'unknown'}. Open the target manually.`,
+      exitCode: result?.status ?? null,
+    };
+  }
+  return null;
+}
+
+function launchTimeout(value, fallback) {
+  return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
 function launchTarget(target, options = {}) {
   const platform = options.platform || process.platform;
   const opener = OPENERS[platform];
@@ -40,28 +90,38 @@ function launchTarget(target, options = {}) {
   }
 
   const spawn = options.spawn || spawnSync;
+  const timeoutMs = launchTimeout(options.timeoutMs, opener.timeoutMs);
   let result;
   try {
-    result = spawn(opener.command, opener.args(target), {
+    const spawnOptions = {
       encoding: 'utf8',
       shell: false,
       stdio: 'ignore',
-      timeout: options.timeoutMs || 5000,
+      timeout: timeoutMs,
       windowsHide: true,
-    });
-  } catch {
-    result = { error: new Error('opener threw') };
+    };
+    if (platform === 'win32') {
+      spawnOptions.env = {
+        ...process.env,
+        ARCHIFY_OPEN_TARGET: target,
+      };
+    }
+    result = spawn(opener.command, opener.args(target), spawnOptions);
+  } catch (error) {
+    result = { error };
   }
 
+  const failure = failureDetails(result, opener, timeoutMs);
   let status = 'opened';
-  if (result?.error?.code === 'ENOENT') status = 'unsupported';
-  else if (result?.error || result?.signal || result?.status !== 0) status = 'failed';
+  if (failure?.code === 'opener/unavailable') status = 'unsupported';
+  else if (failure) status = 'failed';
 
   return {
     requested: true,
     status,
     target,
     method: opener.method,
+    ...(failure ? { failure } : {}),
   };
 }
 

package/ai/skills/stacks-technical-diagrams/bin/preview.mjs

@@ -1,3 +1,5 @@
+import { runtimeArgs } from '../renderers/shared/bun-runtime.mjs';
+import { softwareNoticesHtml } from '../renderers/shared/software-notices.mjs';
 import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
@@ -7,7 +9,16 @@ import { fileURLToPath } from 'node:url';
 
 import { openLoopbackUrl } from './open-artifact.mjs';
 import { resolveOutputPath } from '../renderers/shared/output-path.mjs';
-import { runtimeArgs } from '../renderers/shared/bun-runtime.mjs';
+import { sameLocation } from '../renderers/shared/path-semantics.mjs';
+import {
+  captureAtomicOutput,
+  captureRegularFileBinding,
+  publishRegularFileBinding,
+  releaseRegularFileBinding,
+  removeEmptyDirectoryWithRetry,
+  removeOwnedRegularFile,
+  verifyAtomicOutput,
+} from '../renderers/shared/atomic-output.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const cliPath = path.join(here, 'archify.mjs');
@@ -16,7 +27,8 @@ const defaultDebounceMs = 400;
 const defaultPollMs = 800;
 const defaultStopGraceMs = 3000;
 const defaultStopKillMs = 750;
-const diagramTypes = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle']);
+const diagramTypes = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle', 'erd', 'tree', 'class', 'timeline', 'waterfall']);
+let previewCommitSequence = 0;
 
 function sha256(value) {
   return createHash('sha256').update(value).digest('hex');
@@ -34,7 +46,7 @@ function sourceDigest(inputPath) {
 function initialAuthoredOutput(inputPath) {
   try {
     const source = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
-    if (typeof source?.meta?.output === 'string' && source.meta.output) {
+    if (typeof source?.meta?.output === 'string') {
       return source.meta.output;
     }
   } catch {
@@ -48,9 +60,9 @@ function previewPage() {
   return `<!doctype html>
 <html lang="en">
 <head>
-  <meta charset="utf-8">
+  <meta charset="utf-8">${softwareNoticesHtml}
   <meta name="viewport" content="width=device-width,initial-scale=1">
-  <title>Technical Diagrams Live Preview</title>
+  <title>Archify Live Preview</title>
   <style>
     :root { color-scheme: light dark; font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
     * { box-sizing: border-box; }
@@ -78,7 +90,7 @@ function previewPage() {
 </head>
 <body data-state="checking" data-has-artifact="false">
   <header>
-    <span class="brand">Live Preview</span>
+    <span class="brand">Archify Preview</span>
     <details id="failure" hidden>
       <summary role="button" aria-controls="diagnostic-panel">View diagnostic</summary>
       <div class="diagnostic" id="diagnostic-panel"><pre id="diagnostic"></pre><button id="copy" type="button">Copy diagnostic</button></div>
@@ -87,7 +99,7 @@ function previewPage() {
   </header>
   <main>
     <div id="empty">Waiting for the first verified diagram. Invalid input will stay here with an exact diagnostic.</div>
-    <iframe id="artifact" title="Verified diagram"></iframe>
+    <iframe id="artifact" title="Verified Archify diagram"></iframe>
   </main>
   <script>
     (function () {
@@ -179,6 +191,161 @@ function parseReceipt(stdout) {
   }
 }
 
+function atomicOutputFailure(result) {
+  const code = result?.reason?.code || 'unclassified';
+  let diagnosticCode = 'output/target-indeterminate';
+  let message;
+  if (code === 'target-hardlinked' || code === 'candidate-hardlinked') {
+    diagnosticCode = 'output/target-hardlinked';
+    message = code === 'candidate-hardlinked'
+      ? 'Preview commit candidate has multiple hard-link names and cannot be published safely.'
+      : 'Preview output has multiple hard-link names; atomic publication cannot update every name.';
+  } else if (code === 'target-not-regular-file' || code === 'candidate-not-regular-file') {
+    diagnosticCode = 'output/target-not-regular-file';
+    message = code === 'candidate-not-regular-file'
+      ? 'Preview commit candidate is no longer a regular file.'
+      : 'Preview output already exists and is not a regular file.';
+  } else if (result?.status === 'different') {
+    diagnosticCode = 'output/target-changed';
+    message = `Preview output changed while the verified candidate was being prepared (${code}).`;
+  } else {
+    message = `Preview output stability could not be determined safely (${code}).`;
+  }
+  return {
+    code: diagnosticCode,
+    message,
+    evidence: { relation: result?.reason || { code } },
+  };
+}
+
+function atomicOutputError(result) {
+  const failure = atomicOutputFailure(result);
+  return Object.assign(new Error(failure.message), { previewFailure: failure });
+}
+
+function stagePreviewCommit(commitPath, artifact, mode) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    previewCommitSequence += 1;
+    const candidatePath = path.join(
+      path.dirname(commitPath),
+      `.archify-preview-commit-${process.pid}-${Date.now().toString(36)}-${previewCommitSequence}.tmp`,
+    );
+    let descriptor;
+    let identity;
+    try {
+      const noFollow = process.platform === 'win32' ? 0 : (fs.constants.O_NOFOLLOW || 0);
+      descriptor = fs.openSync(
+        candidatePath,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow,
+        mode ?? 0o666,
+      );
+      let metadata;
+      try {
+        metadata = fs.fstatSync(descriptor, { bigint: true });
+      } catch (error) {
+        try {
+          const retry = fs.fstatSync(descriptor, { bigint: true });
+          if (retry.isFile() && retry.ino !== 0n) {
+            identity = { device: retry.dev, inode: retry.ino };
+          }
+        } catch {}
+        throw error;
+      }
+      if (!metadata.isFile() || metadata.ino === 0n) {
+        throw new Error('Preview commit candidate identity could not be verified safely.');
+      }
+      identity = { device: metadata.dev, inode: metadata.ino };
+      fs.writeFileSync(descriptor, artifact);
+      if (mode !== null) fs.fchmodSync(descriptor, mode);
+      fs.closeSync(descriptor);
+      descriptor = undefined;
+      return { candidatePath, identity };
+    } catch (error) {
+      if (descriptor !== undefined) {
+        try { fs.closeSync(descriptor); } catch {}
+      }
+      if (error.code === 'EEXIST') continue;
+      if (identity) removeOwnedRegularFile(candidatePath, identity);
+      throw error;
+    }
+  }
+  throw Object.assign(new Error('Could not reserve a preview commit candidate beside the output.'), {
+    code: 'EEXIST',
+    errno: -17,
+    syscall: 'open',
+  });
+}
+
+function captureOwnedDirectory(directoryPath) {
+  const metadata = fs.lstatSync(directoryPath, { bigint: true });
+  if (!metadata.isDirectory() || metadata.ino === 0n) {
+    throw new Error('Preview staging directory identity could not be verified safely.');
+  }
+  return { device: metadata.dev, inode: metadata.ino };
+}
+
+function cleanupOwnedDirectory(directoryPath, identity) {
+  let current;
+  try {
+    current = fs.lstatSync(directoryPath, { bigint: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return;
+    throw error;
+  }
+  // Preserve a replacement rather than recursively deleting a directory that
+  // this preview instance did not create.
+  if (!current.isDirectory()
+    || current.ino === 0n
+    || current.dev !== identity.device
+    || current.ino !== identity.inode) return;
+  try {
+    removeEmptyDirectoryWithRetry(directoryPath);
+  } catch (error) {
+    // An entry whose identity was never bound to this preview may be an
+    // external claimant. Preserve the private directory as recovery material
+    // instead of recursively deleting unknown contents.
+    if (error?.code !== 'ENOTEMPTY' && error?.code !== 'EEXIST') throw error;
+  }
+}
+
+function captureOwnedDeliverySidecars(candidatePath, snapshotPath, receipt) {
+  const suffixes = ['.delivery.json', '.delivery-pending.json'];
+  const capturedSidecars = [];
+  for (const suffix of suffixes) {
+    const sidecarPath = candidatePath.replace(/\.html$/iu, suffix);
+    const captured = captureRegularFileBinding(sidecarPath, {
+      subject: 'preview-delivery-sidecar',
+      expectedLinks: 1,
+      includeContent: true,
+    });
+    if (captured.status !== 'captured') continue;
+    try {
+      const sidecar = JSON.parse(captured.content.buffer.toString('utf8'));
+      const commonMatches = sidecar?.schemaVersion === 1
+        && sidecar.command === 'deliver'
+        && sameLocation(sidecar.output, candidatePath).status === 'match'
+        && (!receipt?.receiptId || sidecar.receiptId === receipt.receiptId);
+      const currentMatches = suffix === '.delivery.json'
+        && commonMatches
+        && sidecar.status === 'current'
+        && receipt?.artifact?.sha256
+        && sidecar.artifact?.sha256 === receipt.artifact.sha256;
+      const pendingMatches = suffix === '.delivery-pending.json'
+        && commonMatches
+        && sidecar.status === 'pending'
+        && sameLocation(sidecar.input, snapshotPath).status === 'match';
+      if (currentMatches || pendingMatches) {
+        capturedSidecars.push({ path: sidecarPath, identity: captured.identity });
+      }
+    } catch {
+      // Preserve malformed or claimant-controlled sidecars for recovery.
+    } finally {
+      releaseRegularFileBinding(captured.binding);
+    }
+  }
+  return capturedSidecars;
+}
+
 export async function startPreview(options) {
   const type = options.type;
   if (!diagramTypes.has(type)) throw new Error(`Unknown diagram type "${type}".`);
@@ -203,7 +370,20 @@ export async function startPreview(options) {
   const shouldOpen = options.open !== false;
 
   fs.mkdirSync(outputDirectory, { recursive: true });
-  const stagingDirectory = fs.mkdtempSync(path.join(outputDirectory, '.archify-preview-'));
+  // Keep cleanup bound to the physical directory selected at startup. A
+  // symlink or junction in the requested output parent may be redirected while
+  // preview is running and must not redirect recursive cleanup to a claimant.
+  const physicalOutputDirectory = fs.realpathSync.native(outputDirectory);
+  const stagingDirectory = fs.mkdtempSync(path.toNamespacedPath(
+    path.join(physicalOutputDirectory, '.archify-preview-'),
+  ));
+  let stagingIdentity;
+  try {
+    stagingIdentity = captureOwnedDirectory(stagingDirectory);
+  } catch (error) {
+    try { fs.rmdirSync(stagingDirectory); } catch {}
+    throw error;
+  }
 
   let port = 0;
   let watcher;
@@ -213,6 +393,7 @@ export async function startPreview(options) {
   let stopKillTimer;
   let child;
   let stopping = false;
+  let forceStopping = false;
   let stopped = false;
   let serverClosing = false;
   let serverClosed = false;
@@ -224,6 +405,7 @@ export async function startPreview(options) {
   let pendingBuild = false;
   let artifactBuffer = null;
   const clients = new Set();
+  const sockets = new Set();
   const state = {
     schemaVersion: 1,
     status: 'checking',
@@ -315,6 +497,14 @@ export async function startPreview(options) {
     res.end('Not found');
   });
 
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.once('close', () => sockets.delete(socket));
+    // A connection event already queued when force-stop begins must not keep
+    // server.close() waiting after the current sockets have been destroyed.
+    if (forceStopping) socket.destroy();
+  });
+
   try {
     await new Promise((resolve, reject) => {
       server.once('error', reject);
@@ -326,7 +516,7 @@ export async function startPreview(options) {
     });
   } catch (error) {
     try { server.close(); } catch {}
-    fs.rmSync(stagingDirectory, { recursive: true, force: true });
+    cleanupOwnedDirectory(stagingDirectory, stagingIdentity);
     throw error;
   }
 
@@ -340,7 +530,7 @@ export async function startPreview(options) {
     clearTimeout(stopGraceTimer);
     clearTimeout(stopKillTimer);
     try {
-      fs.rmSync(stagingDirectory, { recursive: true, force: true });
+      cleanupOwnedDirectory(stagingDirectory, stagingIdentity);
     } finally {
       resolveClosed();
     }
@@ -383,6 +573,7 @@ export async function startPreview(options) {
   }
 
   async function stop({ force = false } = {}) {
+    if (force) forceStopping = true;
     if (!stopping) {
       stopping = true;
       clearTimeout(debounceTimer);
@@ -390,6 +581,9 @@ export async function startPreview(options) {
       watcher?.close();
       closeServer();
     }
+    if (forceStopping) {
+      for (const socket of sockets) socket.destroy();
+    }
     if (child && force) {
       clearTimeout(stopGraceTimer);
       clearTimeout(stopKillTimer);
@@ -423,6 +617,8 @@ export async function startPreview(options) {
     state.status = 'needs-fix';
     state.failure = {
       stage: receipt?.stage || 'render',
+      ...(receipt?.code ? { code: receipt.code } : {}),
+      ...(receipt?.evidence ? { evidence: receipt.evidence } : {}),
       message: redactDiagnostic(
         diagnostic,
         [
@@ -440,25 +636,69 @@ export async function startPreview(options) {
     broadcast();
   }
 
-  function commitCandidate(candidatePath, receipt, generationHash) {
+  function commitCandidate(candidatePath, receipt, generationHash, outputCapture) {
     let candidate;
+    let sourceCandidateBinding;
+    let sourceCandidateIdentity;
+    let commitCandidatePath;
+    let commitCandidateIdentity;
+    let commitCandidateBinding;
     try {
-      candidate = fs.readFileSync(candidatePath);
-      const digest = sha256(candidate);
-      if (digest !== receipt?.artifact?.sha256) {
-        throw new Error('Verified candidate bytes do not match the delivery receipt.');
-      }
+      const sourceCapture = captureRegularFileBinding(candidatePath, {
+        subject: 'candidate',
+        expectedSha256: receipt?.artifact?.sha256,
+        expectedBytes: receipt?.artifact?.bytes,
+        includeContent: true,
+      });
+      if (sourceCapture.status !== 'captured') throw atomicOutputError(sourceCapture);
+      sourceCandidateBinding = sourceCapture.binding;
+      sourceCandidateIdentity = sourceCapture.identity;
+      candidate = sourceCapture.content.buffer;
+      const digest = sourceCapture.content.sha256;
+      const releasedSource = releaseRegularFileBinding(sourceCandidateBinding);
+      sourceCandidateBinding = undefined;
+      if (releasedSource.status !== 'released') throw atomicOutputError(releasedSource);
       resolveOutputPath(outputRequest);
       const sameArtifact = state.lastVerified?.sha256 === digest;
-      let outputMatches = false;
-      if (sameArtifact) {
-        try { outputMatches = sha256(fs.readFileSync(outputPath)) === digest; } catch {}
-      }
       const currentSource = sourceDigest(inputPath);
       if (currentSource.hash !== generationHash) {
-        return { committed: false, supersededBy: currentSource };
+        return {
+          committed: false,
+          supersededBy: currentSource,
+          candidateIdentity: sourceCandidateIdentity,
+        };
+      }
+      const beforeStage = verifyAtomicOutput(outputCapture.snapshot);
+      if (beforeStage.status !== 'match') throw atomicOutputError(beforeStage);
+      ({
+        candidatePath: commitCandidatePath,
+        identity: commitCandidateIdentity,
+      } = stagePreviewCommit(outputCapture.commitPath, candidate, outputCapture.mode));
+      const candidateCapture = captureRegularFileBinding(commitCandidatePath, {
+        subject: 'candidate',
+        expectedSha256: digest,
+        expectedBytes: candidate.byteLength,
+        expectedIdentity: commitCandidateIdentity,
+        ...(outputCapture.mode === null ? {} : { expectedMode: outputCapture.mode }),
+      });
+      if (candidateCapture.status !== 'captured') throw atomicOutputError(candidateCapture);
+      commitCandidateBinding = candidateCapture.binding;
+      const beforeCommit = verifyAtomicOutput(outputCapture.snapshot);
+      if (beforeCommit.status !== 'match') throw atomicOutputError(beforeCommit);
+      const publication = publishRegularFileBinding(
+        commitCandidateBinding,
+        commitCandidatePath,
+        outputCapture.snapshot,
+        { subject: 'candidate' },
+      );
+      if (!['committed', 'committed-with-warning'].includes(publication.status)) {
+        throw atomicOutputError(publication);
       }
-      if (!sameArtifact || !outputMatches) fs.renameSync(candidatePath, outputPath);
+      const releasedCandidate = releaseRegularFileBinding(commitCandidateBinding);
+      commitCandidateBinding = undefined;
+      if (releasedCandidate.status !== 'released') throw atomicOutputError(releasedCandidate);
+      commitCandidatePath = undefined;
+      commitCandidateIdentity = undefined;
       artifactBuffer = candidate;
       lastGoodSourceHash = generationHash;
       state.status = 'verified';
@@ -475,10 +715,20 @@ export async function startPreview(options) {
       }
       state.failure = null;
       broadcast();
-      return { committed: true, supersededBy: null };
+      return { committed: true, supersededBy: null, candidateIdentity: sourceCandidateIdentity };
     } catch (error) {
-      publishFailure({ stage: 'commit', error: `Could not publish the verified preview: ${error.message}` }, '', '', candidatePath);
-      return { committed: false, supersededBy: null };
+      publishFailure({
+        stage: 'commit',
+        error: `Could not publish the verified preview: ${error.message}`,
+        ...(error.previewFailure || {}),
+      }, '', '', candidatePath);
+      return { committed: false, supersededBy: null, candidateIdentity: sourceCandidateIdentity };
+    } finally {
+      if (sourceCandidateBinding) releaseRegularFileBinding(sourceCandidateBinding);
+      if (commitCandidateBinding) releaseRegularFileBinding(commitCandidateBinding);
+      if (commitCandidatePath && commitCandidateIdentity) {
+        removeOwnedRegularFile(commitCandidatePath, commitCandidateIdentity);
+      }
     }
   }
 
@@ -493,9 +743,38 @@ export async function startPreview(options) {
 
     const candidatePath = path.join(stagingDirectory, `generation-${state.generation}.html`);
     const snapshotPath = path.join(stagingDirectory, `generation-${state.generation}.json`);
+    let snapshotIdentity;
+    const outputCapture = captureAtomicOutput(outputPath);
+    if (outputCapture.status !== 'captured') {
+      const failure = atomicOutputFailure(outputCapture);
+      publishFailure(
+        { stage: 'prepare', error: failure.message, ...failure },
+        '',
+        '',
+        candidatePath,
+        snapshotPath,
+      );
+      return;
+    }
+    const beforeBuild = verifyAtomicOutput(outputCapture.snapshot);
+    if (beforeBuild.status !== 'match') {
+      const failure = atomicOutputFailure(beforeBuild);
+      publishFailure(
+        { stage: 'prepare', error: failure.message, ...failure },
+        '',
+        '',
+        candidatePath,
+        snapshotPath,
+      );
+      return;
+    }
     if (digest.bytes !== null) {
       try {
         fs.writeFileSync(snapshotPath, digest.bytes, { flag: 'wx', mode: 0o600 });
+        const metadata = fs.lstatSync(snapshotPath, { bigint: true });
+        if (metadata.isFile() && metadata.ino !== 0n) {
+          snapshotIdentity = { device: metadata.dev, inode: metadata.ino };
+        }
       } catch (error) {
         publishFailure(
           { stage: 'prepare', error: `Could not snapshot the observed input: ${error.message}` },
@@ -529,18 +808,44 @@ export async function startPreview(options) {
       const generationHash = activeHash;
       const stale = generationEpoch !== sourceEpoch;
       let supersededBy = null;
+      let candidateIdentity;
+      const deliverySidecars = captureOwnedDeliverySidecars(
+        candidatePath,
+        snapshotPath,
+        receipt,
+      );
       child = null;
       clearTimeout(stopGraceTimer);
       clearTimeout(stopKillTimer);
       stopGraceTimer = undefined;
       stopKillTimer = undefined;
       if (!stopping && !stale && code === 0 && receipt?.ok) {
-        ({ supersededBy } = commitCandidate(candidatePath, receipt, generationHash));
+        ({ supersededBy, candidateIdentity } = commitCandidate(
+          candidatePath,
+          receipt,
+          generationHash,
+          outputCapture,
+        ));
+      } else if (code === 0 && receipt?.ok) {
+        const abandonedCandidate = captureRegularFileBinding(candidatePath, {
+          subject: 'abandoned-preview-candidate',
+          expectedSha256: receipt.artifact?.sha256,
+          expectedBytes: receipt.artifact?.bytes,
+        });
+        if (abandonedCandidate.status === 'captured') {
+          candidateIdentity = abandonedCandidate.identity;
+          releaseRegularFileBinding(abandonedCandidate.binding);
+        }
       } else if (!stopping && !stale) {
         publishFailure(receipt, stdout, stderr, candidatePath, snapshotPath);
       }
-      try { fs.rmSync(candidatePath, { force: true }); } catch {}
-      try { fs.rmSync(snapshotPath, { force: true }); } catch {}
+      if (candidateIdentity) removeOwnedRegularFile(candidatePath, candidateIdentity);
+      if (snapshotIdentity) removeOwnedRegularFile(snapshotPath, snapshotIdentity, { subject: 'snapshot' });
+      for (const deliverySidecar of deliverySidecars) {
+        removeOwnedRegularFile(deliverySidecar.path, deliverySidecar.identity, {
+          subject: 'preview-delivery-sidecar',
+        });
+      }
 
       if (stopping) {
         finishStop();
@@ -589,8 +894,20 @@ export async function startPreview(options) {
 
   if (options.watch !== false) {
     try {
-      watcher = fs.watch(path.dirname(inputPath), (event, filename) => {
-        if (!filename || filename.toString() === path.basename(inputPath)) observeSource();
+      // `path.resolve` keeps Windows 8.3 names intact. Canonicalize short names
+      // and junctions before libuv opens the directory so its callback path has
+      // the same prefix as the watched path.
+      const watchedDirectory = fs.realpathSync.native(path.dirname(inputPath));
+      watcher = fs.watch(watchedDirectory, (event, filename) => {
+        // On Windows the watcher hands us just the basename; on POSIX it can be
+        // null. Resolve named events against the directory libuv actually opened
+        // so file-level case, 8.3, and hard-link aliases still identify the input.
+        if (
+          !filename
+          || sameLocation(path.join(watchedDirectory, filename.toString()), inputPath).status === 'match'
+        ) {
+          observeSource();
+        }
       });
       watcher.on('error', () => {
         const failedWatcher = watcher;
@@ -632,7 +949,7 @@ export async function runPreview(options) {
   console.log(`watching ${preview.input}`);
   console.log(`output ${preview.output}`);
   if (preview.opener && preview.opener.status !== 'opened') {
-    console.error(`Could not open the preview (${preview.opener.status}). Open it manually: ${preview.url}`);
+    console.error(`Could not open the preview (${preview.opener.status}). ${preview.opener.failure?.reason || 'Open it manually.'} Target: ${preview.url}`);
   }
 
   let signalCount = 0;