orizu 0.5.49 → 0.5.50

package/src/setup-and-skills-commands.ts

@@ -2,7 +2,6 @@
 
 import { createInterface } from 'readline/promises'
 import { stdin as input, stdout as output } from 'process'
-import { emitKeypressEvents } from 'readline'
 import { join, relative, resolve } from 'path'
 import { mkdirSync, writeFileSync } from 'fs'
 import { randomBytes } from 'crypto'
@@ -25,6 +24,7 @@ import {
   printJson,
   printBannerIfInteractive,
 } from './cli-console-output.js'
+import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
 import { sanitizeTerminalText } from './json-response.js'
 import {
   SKILL_INSTALL_AGENTS,
@@ -34,6 +34,8 @@ import {
   getTargetForAgent,
   getSkillInstallPath,
   SkillInstallMode,
+  SkillInstallOptions,
+  SkillInstallResult,
   isSkillInstallAgent,
   isSkillInstallTarget,
   installSkillTarget,
@@ -112,50 +114,18 @@ async function askText(question: string, defaultValue: string): Promise<string>
   }
 }
 
-type KeypressInfo = {
-  name?: string
-  sequence?: string
-  ctrl?: boolean
-}
-
-type RawInput = typeof input & {
-  setRawMode?: (mode: boolean) => void
-  isRaw?: boolean
-}
-
 async function waitForAnyKeyOrEscape(message: string): Promise<boolean> {
   if (!isInteractiveTerminal()) {
     throw new Error('Interactive terminal required.')
   }
 
   printLine(message)
-  const rawInput = input as RawInput
-  const wasRaw = Boolean(rawInput.isRaw)
-  emitKeypressEvents(input)
-
-  return new Promise((resolvePromise, rejectPromise) => {
-    function cleanup() {
-      input.off('keypress', onKeypress)
-      if (rawInput.setRawMode && !wasRaw) {
-        rawInput.setRawMode(false)
-      }
-      input.pause()
-      printLine('')
-    }
-
-    function onKeypress(_chunk: string, key: KeypressInfo) {
-      cleanup()
-      if (key.ctrl && key.name === 'c') {
-        rejectPromise(new Error('Setup cancelled.'))
-        return
-      }
-      resolvePromise(key.name !== 'escape')
-    }
-
-    input.on('keypress', onKeypress)
-    input.resume()
-    rawInput.setRawMode?.(true)
-  })
+  const { readKeys } = await import('./terminal-key-session.js')
+  try {
+    return await readKeys(key => ({ kind: 'done', value: key.name !== 'escape' }), { hideCursor: false })
+  } finally {
+    printLine('')
+  }
 }
 
 interface MultiSelectOptions {
@@ -190,9 +160,6 @@ async function promptKeyboardMultiSelect<T>(
       checked.add(index)
     }
   })
-  const rawInput = input as RawInput
-  const wasRaw = Boolean(rawInput.isRaw)
-  emitKeypressEvents(input)
 
   function render() {
     if (rendered) {
@@ -208,60 +175,31 @@ async function promptKeyboardMultiSelect<T>(
   }
 
   render()
-  output.write('\x1b[?25l')
-
-  return new Promise((resolvePromise, rejectPromise) => {
-    function cleanup() {
-      input.off('keypress', onKeypress)
-      if (rawInput.setRawMode && !wasRaw) {
-        rawInput.setRawMode(false)
-      }
-      input.pause()
-      output.write('\x1b[?25h')
-      printLine('')
-    }
-
-    function onKeypress(_chunk: string, key: KeypressInfo) {
-      if (key.ctrl && key.name === 'c') {
-        cleanup()
-        rejectPromise(new Error('Setup cancelled.'))
-        return
-      }
+  const { readKeys } = await import('./terminal-key-session.js')
+  try {
+    return await readKeys<T[]>(key => {
       if (key.name === 'escape') {
-        cleanup()
-        resolvePromise(options.escapeKeepsDefaults ? items.filter((item, index) => defaultSelected(item, index)) : [])
-        return
+        return { kind: 'done', value: options.escapeKeepsDefaults ? items.filter((item, index) => defaultSelected(item, index)) : [] }
       }
-      if (key.name === 'up') {
-        selected = (selected - 1 + items.length) % items.length
+      if (key.name === 'up' || key.name === 'down') {
+        selected = (selected + (key.name === 'up' ? -1 : 1) + items.length) % items.length
         render()
-        return
-      }
-      if (key.name === 'down') {
-        selected = (selected + 1) % items.length
-        render()
-        return
+        return { kind: 'wait' }
       }
       if (key.name === 'space') {
-        if (checked.has(selected)) {
-          checked.delete(selected)
-        } else {
-          checked.add(selected)
-        }
+        if (checked.has(selected)) checked.delete(selected)
+        else checked.add(selected)
         render()
-        return
+        return { kind: 'wait' }
       }
       if (key.name === 'return' || key.name === 'enter') {
-        const selectedItems = items.filter((_item, index) => checked.has(index))
-        cleanup()
-        resolvePromise(selectedItems)
+        return { kind: 'done', value: items.filter((_item, index) => checked.has(index)) }
       }
-    }
-
-    input.on('keypress', onKeypress)
-    input.resume()
-    rawInput.setRawMode?.(true)
-  })
+      return { kind: 'wait' }
+    }, { hideCursor: true })
+  } finally {
+    printLine('')
+  }
 }
 
 function formatFindingCount(count: number, label: string): string {
@@ -461,6 +399,10 @@ interface SkillInstallOutcome {
   action: 'created' | 'updated' | 'skipped' | 'failed'
   mode: 'link' | 'copy' | 'section' | null
   error?: string
+  /** Where a person's own folder was moved before it was replaced. */
+  backup?: string
+  /** Why a person's folder, or part of it, is still beside the skill. */
+  warning?: string
 }
 
 async function applySkillInstallTargets(
@@ -477,7 +419,7 @@ async function applySkillInstallTargets(
 ): Promise<SkillInstallOutcome[]> {
   const cliVersion = getCliVersion()
   const jsonMode = hasJsonFlag()
-  const planned = targets.map(target =>
+  const planned = await Promise.all(targets.map(target =>
     installSkillTarget(target, {
       cwd: options.cwd,
       homeDir: options.homeDir,
@@ -485,7 +427,7 @@ async function applySkillInstallTargets(
       mode: options.mode,
       cliVersion,
     })
-  )
+  ))
   const showPlan = options.showPlan ?? true
   const printResults = options.printResults ?? true
 
@@ -528,7 +470,7 @@ async function applySkillInstallTargets(
     }
 
     try {
-      const result = installSkillTarget(target, {
+      const result = await installSkillTarget(target, {
         cwd: options.cwd,
         homeDir: options.homeDir,
         overwrite,
@@ -537,13 +479,16 @@ async function applySkillInstallTargets(
       })
       if (printResults && !jsonMode) {
         const suffix = result.mode === 'link' ? ' (symlink)' : ''
-        printLine(`${formatSkillInstallAction(result.action)} ${result.path}${suffix}`)
+        printLine(`${formatSkillInstallAction(result.action)} ${result.path}${suffix}${describeBackup(result.backup)}`)
+        if (result.warning) printLine(sanitizeSetupHumanInlineText(`Warning: ${result.warning}`))
       }
       outcomes.push({
         target,
         path: result.path,
         action: result.action as 'created' | 'updated',
         mode: result.mode,
+        ...(result.backup ? { backup: result.backup } : {}),
+        ...(result.warning ? { warning: result.warning } : {}),
       })
     } catch (error: unknown) {
       const message = getErrorMessage(error)
@@ -557,6 +502,10 @@ async function applySkillInstallTargets(
   return outcomes
 }
 
+function describeBackup(backup: string | undefined): string {
+  return backup ? `; moved your earlier folder to ${backup}` : ''
+}
+
 async function installSkillCommand() {
   const skipConfirm = hasArg('--yes')
   const dryRun = hasArg('--dry-run')
@@ -578,15 +527,15 @@ async function installSkillCommand() {
   }
 
   const outcomes = await applySkillInstallTargets(targets, { mode, skipConfirm, dryRun })
+  if (outcomes.some(outcome => outcome.action === 'failed')) {
+    process.exitCode = 1
+  }
   const failedCopy = outcomes.some(outcome =>
     outcome.action === 'failed' && (PROJECT_SKILL_COPY_TARGETS as readonly string[]).includes(outcome.target))
-  if (failedCopy) {
-    process.exitCode = 1
-    if (!hasJsonFlag()) {
-      printLine('The two project copies were not both written. Fix the error above and run the command again.')
-    }
+  if (failedCopy && !hasJsonFlag()) {
+    printLine('The two project copies were not both written. Fix the error above and run the command again.')
   }
-  const legacy = replaceLegacySkillInstalls({
+  const legacy = await replaceLegacySkillInstalls({
     ...legacyScopeAfterInstall(targets, outcomes, dryRun),
     mode,
     dryRun,
@@ -753,8 +702,18 @@ function skillsStatusCommand() {
 async function skillsUpdateCommand() {
   const dryRun = hasArg('--dry-run')
   const cliVersion = getCliVersion()
-  const updates: Array<{ target: SkillInstallTarget, path: string, action: string }> = []
-  const legacy = replaceLegacySkillInstalls({ dryRun, cliVersion })
+  const updates: Array<{ target: SkillInstallTarget, path: string, action: string, error?: string, backup?: string, warning?: string }> = []
+  // A failed target is reported with its reason; the old install there stays whole.
+  const refresh = async (target: SkillInstallTarget, path: string, options: SkillInstallOptions, action: (result: SkillInstallResult) => string) => {
+    try {
+      const result = await installSkillTarget(target, options)
+      updates.push({ target, path, action: action(result), ...(result.backup ? { backup: result.backup } : {}), ...(result.warning ? { warning: result.warning } : {}) })
+    } catch (error: unknown) {
+      process.exitCode = 1
+      updates.push({ target, path, action: 'failed', error: getErrorMessage(error) })
+    }
+  }
+  const legacy = await replaceLegacySkillInstalls({ dryRun, cliVersion })
   // Two project copies that differ are both rewritten from the installed CLI
   // skill, including a hand-made copy the loop below would leave alone.
   const projectCopies = compareProjectSkillCopies()
@@ -766,8 +725,7 @@ async function skillsUpdateCommand() {
         updates.push({ target, path, action: 'would-rewrite' })
         continue
       }
-      installSkillTarget(target, { overwrite: true, mode: 'copy', cliVersion })
-      updates.push({ target, path, action: 'rewrote' })
+      await refresh(target, path, { overwrite: true, mode: 'copy', cliVersion }, () => 'rewrote')
     }
   }
 
@@ -791,16 +749,8 @@ async function skillsUpdateCommand() {
     }
 
     const refreshMode: SkillInstallMode = status.mode === 'link' ? 'auto' : 'copy'
-    const result = installSkillTarget(target, {
-      overwrite: true,
-      mode: refreshMode,
-      cliVersion,
-    })
-    updates.push({
-      target,
-      path: status.path,
-      action: status.state === 'broken-link' ? 'relinked' : result.action,
-    })
+    await refresh(target, status.path, { overwrite: true, mode: refreshMode, cliVersion },
+      result => status.state === 'broken-link' ? 'relinked' : result.action)
   }
 
   if (hasJsonFlag()) {
@@ -816,23 +766,38 @@ async function skillsUpdateCommand() {
   }
 
   if (rewriteProjectCopies) {
-    const verb = dryRun ? 'Would rewrite' : 'Rewrote'
-    printLine(`${verb} both project copies from the installed CLI skill: ${projectCopies.paths.join(' and ')}`)
+    const rewrote = updates.filter(update => update.action === 'rewrote')
+    if (dryRun) {
+      printLine(`Would rewrite both project copies from the installed CLI skill: ${projectCopies.paths.join(' and ')}`)
+    } else if (rewrote.length === PROJECT_SKILL_COPY_TARGETS.length) {
+      printLine(`Rewrote both project copies from the installed CLI skill: ${projectCopies.paths.join(' and ')}`)
+    }
   }
 
   for (const update of updates) {
-    if (update.action === 'rewrote' || update.action === 'would-rewrite') {
+    if (update.action === 'failed') {
+      printLine(sanitizeSetupHumanInlineText(`Failed ${update.path}: ${update.error}`))
       continue
     }
-    if (update.action === 'already-current') {
+    if (update.action === 'would-rewrite') {
+      continue
+    }
+    if (update.action === 'rewrote') {
+      // With both rewritten, the line above names them; otherwise each says so here.
+      const bothRewritten = updates.filter(other => other.action === 'rewrote').length === PROJECT_SKILL_COPY_TARGETS.length
+      if (!bothRewritten || update.backup) {
+        printLine(sanitizeSetupHumanInlineText(`Rewrote ${update.path} from the installed CLI skill${describeBackup(update.backup)}`))
+      }
+    } else if (update.action === 'already-current') {
       printLine(`Current ${update.path}`)
     } else if (update.action === 'would-update') {
       printLine(`Would update ${update.path}`)
     } else if (update.action === 'relinked') {
       printLine(`Relinked ${update.path}`)
     } else {
-      printLine(`Updated ${update.path}`)
+      printLine(sanitizeSetupHumanInlineText(`Updated ${update.path}${describeBackup(update.backup)}`))
     }
+    if (update.warning) printLine(sanitizeSetupHumanInlineText(`Warning: ${update.warning}`))
   }
 }
 
@@ -878,7 +843,7 @@ async function resolveSetupTeam(
     if (!name) throw new Error('--create-team requires a non-empty team name.')
     return await createSetupTeam(name, request)
   }
-  const teams = await fetchTeams(request)
+  const teams = await fetchTeams(request, datasetTransferTimeoutMs())
   const normalizedTeamSlug = teamSlugArg ? normalizeSlugInput(teamSlugArg) : null
   if (normalizedTeamSlug) {
     const team = teams.find(candidate => candidate.slug === normalizedTeamSlug)
@@ -945,7 +910,7 @@ async function resolveSetupProjects(
   if (createProjectName && !canCreateProject) {
     throw new Error(`Only team admins can create projects in '${team.slug}'. Choose an existing project or ask a team admin to create one.`)
   }
-  const projects = await fetchProjects(team.slug, request)
+  const projects = await fetchProjects(team.slug, request, datasetTransferTimeoutMs())
   if (createProjectName) {
     if (dryRun) {
       throw new Error('--create-project cannot be used with --dry-run because setup cannot preview a server-generated project slug.')
@@ -1154,7 +1119,7 @@ async function setupCommand() {
       throw new Error(`This directory is already an Orizu workspace for team '${workspaceTeamSlug}'. Run setup in another directory to set up team '${setupTeam.slug}'.`)
     }
     if (fix) {
-      setupProjects = await fetchProjects(setupTeam.slug, setupRequest)
+      setupProjects = await fetchProjects(setupTeam.slug, setupRequest, datasetTransferTimeoutMs())
       if (setupProjects.length === 0) throw new Error(`Team '${setupTeam.slug}' has no projects to restore.`)
     } else {
       const selection = await resolveSetupProjects(setupTeam, projectArg, createProjectArg, noInput, dryRun, setupRequest)
@@ -1277,7 +1242,7 @@ async function setupCommand() {
       if (dryRun) {
         printLine('Dry run: no skill files were changed.')
       }
-      const legacy = replaceLegacySkillInstalls({
+      const legacy = await replaceLegacySkillInstalls({
         ...legacyScopeAfterInstall(targets, installOutcomes, dryRun),
         mode: installMode,
         dryRun,
@@ -1293,7 +1258,8 @@ async function setupCommand() {
         } else if (outcome.action === 'skipped') {
           printLine(`${label} skipped`)
         } else {
-          printLine(`${label} installed`)
+          printLine(sanitizeSetupHumanInlineText(`${label} installed${describeBackup(outcome.backup)}`))
+          if (outcome.warning) printLine(sanitizeSetupHumanInlineText(`Warning: ${outcome.warning}`))
         }
       }
     }
@@ -1388,6 +1354,8 @@ async function setupCommand() {
         action: outcome.action,
         mode: outcome.mode,
         error: outcome.error,
+        ...(outcome.backup ? { backup: outcome.backup } : {}),
+        ...(outcome.warning ? { warning: outcome.warning } : {}),
       })),
       skill: {
         root: source.root,

package/src/skill-install-workflow.ts

@@ -0,0 +1,215 @@
+// Reads the skill source and the install target it is given.
+// @tia-reads: skills/orizu
+// Replaces one skill folder without ever leaving a half-written one, and never
+// deletes a person's files: they are moved to a backup first. Loaded only
+// through `await import(...)`, so `orizu skills path` never loads Effect.
+import { cp, lstat, mkdir, readdir, readlink, readFile, rename, rm, symlink, unlink, copyFile } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+
+import { Context, Effect, Exit, Option, Schema } from 'effect'
+
+import { computeSkillContentHash, SKILL_META_FILENAME, shouldCopySkillPath } from './skill-installer.js'
+
+export interface ReplaceSkillFolderInput {
+  sourceRoot: string
+  targetPath: string
+  mode: 'link' | 'copy'
+  /** Where a person's own folder is moved; no agent looks for skills there. */
+  backupPath: string
+  /** Writes Orizu's marker into the new copy before it is put in place. */
+  writeMarker: (dir: string) => void
+}
+
+export interface ReplaceSkillFolderResult {
+  /** Where a person's own folder was moved, when there was one. */
+  backup: string | null
+  /** Why a person's folder, or part of it, is still beside the skill. */
+  warning?: string
+}
+
+/** Every rename the replacement makes. Tests swap it to make one rename fail. */
+const SkillFolderRename = Context.Reference<(from: string, to: string) => Promise<void>>('orizu/SkillFolderRename', {
+  defaultValue: () => rename,
+})
+
+const renameEntry = (from: string, to: string) => Effect.gen(function*() {
+  const move = yield* SkillFolderRename
+  yield* attempt(() => move(from, to))
+})
+
+const SkillMarker = Schema.Struct({ skillHash: Schema.String })
+
+type Existing = 'missing' | 'link' | 'orizu' | 'person'
+
+const attempt = <A>(run: () => Promise<A>) =>
+  // One file step at a time: an interruption lands between steps, never during one.
+  Effect.uninterruptible(Effect.tryPromise({ try: run, catch: cause => cause instanceof Error ? cause : new Error(String(cause)) }))
+
+const exists = (path: string) => attempt(() => lstat(path).then(() => true, () => false))
+
+// Orizu's own install is a link, or a copy whose files still match its marker
+// or the skill being installed. Anything else may hold a person's work.
+function classify(targetPath: string, sourceRoot: string): Effect.Effect<Existing, Error> {
+  return Effect.gen(function*() {
+    const stats = yield* attempt(() => lstat(targetPath).then(found => found, () => null))
+    if (!stats) return 'missing'
+    if (stats.isSymbolicLink()) return 'link'
+    if (!stats.isDirectory()) return 'person'
+    const marker = yield* attempt(() => readFile(join(targetPath, SKILL_META_FILENAME), 'utf8').then(text => JSON.parse(text) as unknown, () => null))
+    const installedHash = computeSkillContentHash(targetPath)
+    const recorded = Schema.decodeUnknownOption(SkillMarker)(marker)
+    if (Option.isSome(recorded) && recorded.value.skillHash === installedHash) return 'orizu'
+    return installedHash === computeSkillContentHash(sourceRoot) ? 'orizu' : 'person'
+  })
+}
+
+function copyTree(root: string, from: string, to: string): Effect.Effect<void, Error> {
+  return Effect.gen(function*() {
+    yield* attempt(() => mkdir(to, { recursive: true }))
+    const entries = yield* attempt(() => readdir(from, { withFileTypes: true }))
+    for (const entry of entries) {
+      const source = join(from, entry.name)
+      const target = join(to, entry.name)
+      if (!shouldCopySkillPath(root, source)) continue
+      if (entry.isDirectory()) yield* copyTree(root, source, target)
+      else if (entry.isFile()) yield* attempt(() => copyFile(source, target))
+      else if (entry.isSymbolicLink()) yield* attempt(async () => symlink(await readlink(source), target))
+      else yield* Effect.fail(new Error(`${source} is not a file or folder, so the skill can't be copied.`))
+    }
+  })
+}
+
+// Links are removed as links, never by following them.
+const removeEntry = (path: string) => attempt(async () => {
+  const stats = await lstat(path).catch(() => null)
+  if (!stats) return
+  if (stats.isSymbolicLink()) await unlink(path)
+  else await rm(path, { recursive: true, force: true })
+})
+
+
+/**
+ * Moves a person's folder to the backup. Once the copy is whole, the backup
+ * is reported even when the original cannot be removed; if nothing could be
+ * moved, the folder stays where it is and the warning says why.
+ */
+function moveToBackup(from: string, to: string): Effect.Effect<ReplaceSkillFolderResult> {
+  const stayed = (cause: Error): ReplaceSkillFolderResult => ({
+    backup: resolve(from),
+    warning: `Could not move your earlier folder to ${to}: ${cause.message}. It is still at ${from}, where agents may load it as a second skill; move it somewhere else.`,
+  })
+  return Effect.gen(function*() {
+    yield* attempt(() => mkdir(dirname(to), { recursive: true }))
+    // A project on another disk cannot be renamed into the home folder, so it is copied.
+    const renamed = yield* renameEntry(from, to).pipe(Effect.as(true), Effect.catch(error =>
+      (error as { code?: string }).code === 'EXDEV' ? Effect.succeed(false) : Effect.fail(error)))
+    if (renamed) return { backup: resolve(to) }
+    // Our own half-made copy is removed; the person's folder is untouched.
+    yield* attempt(() => cp(from, to, { recursive: true, verbatimSymlinks: true })).pipe(
+      Effect.tapError(() => removeEntry(to).pipe(Effect.ignore)))
+    return yield* attempt(() => rm(from, { recursive: true })).pipe(
+      Effect.as<ReplaceSkillFolderResult>({ backup: resolve(to) }),
+      Effect.catch(cause => Effect.succeed<ReplaceSkillFolderResult>({
+        backup: resolve(to),
+        warning: `Copied your earlier folder to ${to}, but could not remove it from ${from}: ${cause.message}. Agents may load it there as a second skill; remove it once you have checked the copy.`,
+      })),
+    )
+  }).pipe(Effect.catch(cause => Effect.succeed(stayed(cause))))
+}
+
+/**
+ * Stage the new skill beside the target, move the old folder aside, rename the
+ * staged one into place, then drop Orizu's old copy or back up a person's.
+ * On a failure or an interruption, staging is removed and the old folder is
+ * put back.
+ */
+function replaceSkillFolder(input: ReplaceSkillFolderInput): Effect.Effect<ReplaceSkillFolderResult, Error> {
+  const { sourceRoot, targetPath, mode } = input
+  const id = `${process.pid}-${Date.now().toString(36)}`
+  const name = basename(targetPath)
+  const staging = join(dirname(targetPath), `${name}.orizu-staging-${id}`)
+  const aside = join(dirname(targetPath), `${name}.orizu-previous-${id}`)
+
+  // Set when the old folder could not be put back after a failure.
+  let strandedAt: string | null = null
+
+  // Only the copy into staging can be interrupted. Once the old folder moves
+  // aside, the swap and the clean-up after it always finish, so Ctrl-C can
+  // never skip putting the old folder back or moving a person's folder out.
+  return Effect.uninterruptibleMask(restore => Effect.gen(function*() {
+    const existing = yield* classify(targetPath, sourceRoot)
+    yield* attempt(() => mkdir(dirname(targetPath), { recursive: true }))
+
+    const swapped = yield* Effect.scoped(Effect.gen(function*() {
+      // Registered before staging starts, so a copy that stops part way is removed too.
+      // Gone already once it has been renamed into place.
+      yield* Effect.addFinalizer(() => removeEntry(staging).pipe(Effect.ignore))
+      yield* restore(mode === 'link'
+        ? attempt(() => symlink(sourceRoot, staging, 'dir'))
+        : copyTree(sourceRoot, sourceRoot, staging).pipe(
+          Effect.andThen(Effect.try({ try: () => input.writeMarker(staging), catch: cause => cause instanceof Error ? cause : new Error(String(cause)) }))))
+      if (existing !== 'missing') {
+        yield* Effect.acquireRelease(
+          renameEntry(targetPath, aside),
+          (_, exit) => Exit.isSuccess(exit)
+            ? Effect.void
+            // Put the old folder back unless something already holds its place.
+            : exists(targetPath).pipe(
+              Effect.flatMap(taken => taken ? Effect.fail(new Error(`${targetPath} is taken`)) : renameEntry(aside, targetPath)),
+              Effect.catch(() => Effect.sync(() => { strandedAt = aside })),
+            ),
+        )
+      }
+      yield* renameEntry(staging, targetPath)
+      return existing
+    })).pipe(Effect.mapError(error => strandedAt
+      ? new Error(`${error.message} Your earlier folder could not be put back at ${targetPath}; it is at ${strandedAt}.`)
+      : error))
+
+    if (swapped === 'missing') return { backup: null }
+    if (swapped !== 'person') {
+      yield* removeEntry(aside).pipe(Effect.mapError(cause => new Error(`Installed ${targetPath}, but could not remove the earlier copy at ${aside}: ${cause.message}`)))
+      return { backup: null }
+    }
+    // The person's folder is safe beside the target; move it out of agents' sight.
+    return yield* moveToBackup(aside, input.backupPath)
+  }))
+}
+
+/** One replacement whose renames go through `move`, so a test can make one fail. */
+export async function replaceSkillFolderUsing(move: (from: string, to: string) => Promise<void>, input: ReplaceSkillFolderInput): Promise<ReplaceSkillFolderResult> {
+  return await Effect.runPromise(replaceSkillFolder(input).pipe(Effect.provideService(SkillFolderRename, move)))
+}
+
+const STOP_SIGNALS = ['SIGINT', 'SIGTERM'] as const
+
+/** Ends the process by the signal that stopped it, once its handlers are gone. */
+async function endBy(signal: NodeJS.Signals, handlers: ReadonlyArray<readonly [NodeJS.Signals, () => void]>): Promise<never> {
+  for (const [name, handler] of handlers) process.removeListener(name, handler)
+  process.kill(process.pid, signal)
+  // The signal ends the process; if another listener holds it, exit as a shell would.
+  setTimeout(() => process.exit(signal === 'SIGINT' ? 130 : 143), 1_000)
+  return await new Promise<never>(() => {})
+}
+
+/**
+ * Runs one replacement. Ctrl-C or SIGTERM interrupts it; once staging is
+ * removed and the old folder is back, the process ends by that same signal.
+ */
+export async function runSkillFolderReplacement(input: ReplaceSkillFolderInput): Promise<ReplaceSkillFolderResult> {
+  const controller = new AbortController()
+  const stop: { by: NodeJS.Signals | null } = { by: null }
+  const handlers = STOP_SIGNALS.map(signal => [signal, () => { stop.by = signal; controller.abort() }] as const)
+  for (const [signal, handler] of handlers) process.once(signal, handler)
+  try {
+    const result = await Effect.runPromise(replaceSkillFolder(input), { signal: controller.signal })
+    // A stop that arrived as the replacement finished still stops the command.
+    if (stop.by) return await endBy(stop.by, handlers)
+    return result
+  } catch (error: unknown) {
+    if (!stop.by) throw error
+    return await endBy(stop.by, handlers)
+  } finally {
+    for (const [signal, handler] of handlers) process.removeListener(signal, handler)
+  }
+}