@anionex/dsh-turn-rewind 0.1.2 → 0.2.0

package/src/engine.ts

@@ -49,6 +49,8 @@ import {
   type RestoreResult,
   type SnapshotEntry,
   type WorkspaceChange,
+  type WorkspaceOverview,
+  type WorkspacePurgeReport,
 } from './types.js'
 
 const DEFAULTS = {
@@ -67,7 +69,7 @@ const DEFAULTS = {
 
 /** Persistent workspace change-set engine, independent of the DSH tool adapter. */
 export class ChangeLedgerEngine {
-  readonly config: ResolvedChangeLedgerConfig
+  private readonly currentConfig: ResolvedChangeLedgerConfig
   readonly store: LedgerStore
   private readonly plans = new Map<string, RestorePlan>()
   private readonly activePlans = new Set<string>()
@@ -75,11 +77,28 @@ export class ChangeLedgerEngine {
 
   /** Build an engine and start crash-journal reconciliation. */
   constructor(config: ChangeLedgerConfig = {}) {
-    this.config = resolveConfig(config)
-    this.store = new LedgerStore(this.config)
+    this.currentConfig = resolveConfig(config)
+    this.store = new LedgerStore(this.currentConfig)
     this.ready = this.initializeStore()
   }
 
+  /** Currently resolved configuration; runtime-tunable fields update in place. */
+  get config(): ResolvedChangeLedgerConfig {
+    return this.currentConfig
+  }
+
+  /**
+   * Swap runtime-tunable configuration (limits, modes, timeouts, trust) in place.
+   * The storage root must never move once the engine owns locks and journals.
+   */
+  updateConfig(config: ChangeLedgerConfig): void {
+    const resolved = resolveConfig(config)
+    if (resolved.storageDir !== this.currentConfig.storageDir) {
+      throw new ChangeLedgerError('INVALID_CONFIG', 'storageDir cannot change while the engine is running')
+    }
+    Object.assign(this.currentConfig as WritableResolvedConfig, resolved)
+  }
+
   /** Wait for startup reconciliation and return the number of interrupted journals found. */
   async initialize(): Promise<number> {
     return this.ready
@@ -743,6 +762,135 @@ export class ChangeLedgerEngine {
     }
   }
 
+  /** Inventory every workspace this storage root has ever persisted state for. */
+  async listWorkspaces(options: { readonly signal?: AbortSignal } = {}): Promise<WorkspaceOverview[]> {
+    await this.ready
+    const groups = new Map<string, { restorePoints: RestorePointSummary[]; recoveryCount: number }>()
+    const groupOf = (workspace: string): { restorePoints: RestorePointSummary[]; recoveryCount: number } => {
+      const existing = groups.get(workspace)
+      if (existing !== undefined) return existing
+      const created = { restorePoints: [], recoveryCount: 0 }
+      groups.set(workspace, created)
+      return created
+    }
+    for (const workspaceDir of await this.store.listWorkspaceDirs(options.signal)) {
+      for (const manifest of await this.store.listManifestsInDir(workspaceDir, options.signal)) {
+        groupOf(manifest.workspace).restorePoints.push(summarize(manifest))
+      }
+      for (const operation of await this.store.listOperationsInDir(workspaceDir, options.signal)) {
+        if (operation.state === 'interrupted' || operation.state === 'recovery-required') {
+          groupOf(operation.workspace).recoveryCount += 1
+        }
+      }
+    }
+    return [...groups.entries()]
+      .map(([workspace, group]) => ({
+        workspace,
+        restorePoints: [...group.restorePoints].sort(
+          (left, right) => right.createdAt - left.createdAt || right.id.localeCompare(left.id),
+        ),
+        totalBytes: group.restorePoints.reduce((total, point) => total + point.totalBytes, 0),
+        recoveryCount: group.recoveryCount,
+      }))
+      .sort((left, right) => left.workspace.localeCompare(right.workspace))
+  }
+
+  /** Delete unprotected restore points recorded for one workspace and collect unused blobs. */
+  async purgeWorkspace(options: {
+    readonly workspace: string
+    /** Restrict the purge to these restore points; protection rules still apply. */
+    readonly restorePointIds?: readonly string[]
+    readonly signal?: AbortSignal
+  }): Promise<WorkspacePurgeReport> {
+    await this.ready
+    const restorePointIds = options.restorePointIds === undefined ? undefined : new Set(options.restorePointIds)
+    const targetDirs = new Set<string>()
+    for (const workspaceDir of await this.store.listWorkspaceDirs(options.signal)) {
+      for (const manifest of await this.store.listManifestsInDir(workspaceDir, options.signal)) {
+        if (manifest.workspace === options.workspace
+          && (restorePointIds === undefined || restorePointIds.has(manifest.id))) {
+          targetDirs.add(workspaceDir)
+        }
+      }
+      for (const operation of await this.store.listOperationsInDir(workspaceDir, options.signal)) {
+        if (operation.workspace === options.workspace) targetDirs.add(workspaceDir)
+      }
+    }
+    let deletedRestorePoints = 0
+    let retainedRestorePoints = 0
+    let deletedBlobs = 0
+    let retainedBlobs = 0
+    for (const workspaceDir of targetDirs) {
+      const result = await this.purgeWorkspaceDir(workspaceDir, options.workspace, restorePointIds, options.signal)
+      deletedRestorePoints += result.deletedRestorePoints
+      retainedRestorePoints += result.retainedRestorePoints
+      deletedBlobs += result.deletedBlobs
+      retainedBlobs += result.retainedBlobs
+    }
+    return { workspace: options.workspace, deletedRestorePoints, retainedRestorePoints, deletedBlobs, retainedBlobs }
+  }
+
+  private async purgeWorkspaceDir(
+    workspaceDir: string,
+    workspace: string,
+    restorePointIds: ReadonlySet<string> | undefined,
+    signal?: AbortSignal,
+  ): Promise<{ deletedRestorePoints: number; retainedRestorePoints: number; deletedBlobs: number; retainedBlobs: number }> {
+    // A live repository needs both its shared Git lock and durable directory lock.
+    // A missing path, or one now nested under a different repository, cannot expose
+    // its old Git namespace but still takes the durable lock before storage cleanup.
+    let liveRepository = false
+    let release: () => Promise<void>
+    try {
+      const root = await discoverRepositoryRoot(workspace, signal)
+      if (root === workspace) {
+        await this.assertStorageSeparated(root)
+        release = await this.acquireWorkspace(root, signal)
+        liveRepository = true
+      } else {
+        release = await this.store.acquireWorkspaceDir(workspaceDir, workspace, signal)
+      }
+    } catch (error) {
+      if (!(error instanceof ChangeLedgerError) || error.code !== 'WORKSPACE_NOT_FOUND') throw error
+      release = await this.store.acquireWorkspaceDir(workspaceDir, workspace, signal)
+    }
+    let deletedRestorePoints = 0
+    let retainedRestorePoints = 0
+    try {
+      const manifests = (await this.store.listManifestsInDir(workspaceDir, signal))
+        .filter((manifest) => manifest.workspace === workspace
+          && (restorePointIds === undefined || restorePointIds.has(manifest.id)))
+      const protectedIds = new Set<string>()
+      for (const operation of await this.store.listOperationsInDir(workspaceDir, signal)) {
+        if (operation.state === 'running' || operation.state === 'rollback-running'
+          || operation.state === 'interrupted' || operation.state === 'recovery-required') {
+          protectedIds.add(operation.restorePointId)
+          protectedIds.add(operation.rescuePointId)
+        }
+      }
+      for (const journal of await this.store.listGitCheckpointJournalsInDir(workspaceDir, signal)) {
+        protectedIds.add(journal.restorePointId)
+      }
+      for (const manifest of manifests) {
+        if (protectedIds.has(manifest.id)) {
+          retainedRestorePoints += 1
+          continue
+        }
+        if (liveRepository) {
+          await this.deleteManifestWithGit(manifest, signal)
+        } else {
+          await this.store.deleteManifestInDir(workspaceDir, manifest.id)
+        }
+        deletedRestorePoints += 1
+      }
+      if (restorePointIds === undefined) await this.store.clearTurnOutcomesInDir(workspaceDir)
+      const gc = await this.store.collectGarbageInDir(workspaceDir, signal)
+      return { deletedRestorePoints, retainedRestorePoints, ...gc }
+    } finally {
+      await release()
+    }
+  }
+
   private async createLocked(options: {
     readonly cwd: string
     readonly kind: RestorePointKind
@@ -943,6 +1091,9 @@ export class ChangeLedgerEngine {
   }
 }
 
+/** Mutable view used only by `updateConfig` to swap fields on the shared resolved object. */
+type WritableResolvedConfig = { -readonly [K in keyof ResolvedChangeLedgerConfig]: ResolvedChangeLedgerConfig[K] }
+
 /** Resolve and validate every deployment-varying configuration value. */
 export function resolveConfig(config: ChangeLedgerConfig): ResolvedChangeLedgerConfig {
   const home = homedir()

package/src/index.ts

@@ -4,12 +4,14 @@
  */
 import type { Context } from '@deepseek-ai/cordis'
 import { ChangeLedgerEngine } from './engine.js'
-import { installRewindHttp, TurnCheckpointCoordinator } from './rewind-host.js'
+import { installManageHttp, installRewindHttp, TurnCheckpointCoordinator } from './rewind-host.js'
+import { installTurnRewindSettings } from './settings.js'
 import type { ChangeLedgerConfig } from './types.js'
 
 export * from './engine.js'
 export * from './errors.js'
 export * from './rewind-host.js'
+export * from './settings.js'
 export * from './types.js'
 
 declare module '@deepseek-ai/cordis' {
@@ -30,7 +32,9 @@ export class ChangeLedgerService {
     ctx.inject(['agents'], (scope: Context) => { checkpoints.install(scope) })
     ctx.inject(['webServer', 'sessions', 'sessionQuery', 'apiProxy', 'agents'], (scope: Context) => {
       installRewindHttp(scope, this.engine, checkpoints)
+      installManageHttp(scope, this.engine)
     })
+    installTurnRewindSettings(ctx, config, this.engine)
     void this.engine.initialize().then((reconciled) => {
       if (reconciled > 0) {
         ctx.logger.warn(`[change-ledger] reconciled ${reconciled} interrupted durable operation(s)`)
@@ -95,6 +99,21 @@ export class ChangeLedgerService {
   listRecovery(options: Parameters<ChangeLedgerEngine['listRecovery']>[0]): ReturnType<ChangeLedgerEngine['listRecovery']> {
     return this.engine.listRecovery(options)
   }
+
+  /** Inventory every workspace this storage root has persisted state for. */
+  listWorkspaces(options?: Parameters<ChangeLedgerEngine['listWorkspaces']>[0]): ReturnType<ChangeLedgerEngine['listWorkspaces']> {
+    return this.engine.listWorkspaces(options)
+  }
+
+  /** Delete unprotected restore points recorded for one workspace. */
+  purgeWorkspace(options: Parameters<ChangeLedgerEngine['purgeWorkspace']>[0]): ReturnType<ChangeLedgerEngine['purgeWorkspace']> {
+    return this.engine.purgeWorkspace(options)
+  }
+
+  /** Swap runtime-tunable configuration; the storage root must stay fixed. */
+  updateConfig(config: ChangeLedgerConfig): void {
+    this.engine.updateConfig(config)
+  }
 }
 
 export default ChangeLedgerService

package/src/rewind-host.ts

@@ -4,6 +4,7 @@ import { createDeadline } from './deadline.js'
 import { ChangeLedgerError, errorMessage } from './errors.js'
 import type { ChangeLedgerEngine } from './engine.js'
 import { discoverRepositoryRoot } from './git.js'
+import type { WorkspacePurgeReport } from './types.js'
 
 interface SessionEventLike {
   readonly type: string
@@ -312,6 +313,101 @@ export function installRewindHttp(
   }), 'change-ledger.rewindHttp')
 }
 
+export const MANAGE_HTTP_PATH = '/turn-rewind/manage'
+
+/** Register the same-origin storage-management endpoint consumed by the settings card. */
+export function installManageHttp(ctx: Context, engine: ChangeLedgerEngine): void {
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: MANAGE_HTTP_PATH,
+    handler: createManageHttpHandler(engine),
+  }), 'change-ledger.manageHttp')
+}
+
+/** Build the storage-management route as a testable unit. */
+export function createManageHttpHandler(
+  engine: ChangeLedgerEngine,
+): (request: HttpRequestLike, response: HttpResponseLike) => Promise<void> {
+  return async (request, response) => {
+    try {
+      if (request.method === 'GET') {
+        const workspaces = await engine.listWorkspaces()
+        json(response, 200, {
+          storageDir: engine.config.storageDir,
+          totalBytes: workspaces.reduce((total, workspace) => total + workspace.totalBytes, 0),
+          workspaces: workspaces.map((workspace) => ({
+            workspace: workspace.workspace,
+            totalBytes: workspace.totalBytes,
+            recoveryCount: workspace.recoveryCount,
+            restorePoints: workspace.restorePoints.map((point) => ({
+              id: point.id,
+              kind: point.kind,
+              format: point.format,
+              createdAt: point.createdAt,
+              totalBytes: point.totalBytes,
+              fileCount: point.fileCount,
+              ...(point.sessionId === undefined ? {} : { sessionId: point.sessionId }),
+              ...(point.turn === undefined ? {} : { turn: point.turn }),
+              ...(point.label === undefined ? {} : { label: point.label }),
+            })),
+          })),
+        })
+        return
+      }
+      if (request.method === 'POST') {
+        const body = objectBody(await readBody(request))
+        const action = requiredText(body.action, 'action')
+        if (action === 'delete') {
+          const workspace = requiredText(body.workspace, 'workspace')
+          const restorePointId = requiredText(body.restorePointId, 'restorePointId')
+          const report = await engine.purgeWorkspace({ workspace, restorePointIds: [restorePointId] })
+          if (report.deletedRestorePoints === 0) {
+            throw new ChangeLedgerError(
+              report.retainedRestorePoints > 0 ? 'RECOVERY_REFERENCE' : 'RESTORE_POINT_NOT_FOUND',
+              report.retainedRestorePoints > 0
+                ? 'restore point is required by an incomplete recovery journal'
+                : `restore point ${restorePointId} does not exist`,
+            )
+          }
+          json(response, 200, { status: 'completed', action, ...report })
+          return
+        }
+        if (action === 'clear-workspace') {
+          const workspace = requiredText(body.workspace, 'workspace')
+          json(response, 200, { status: 'completed', action, ...await engine.purgeWorkspace({ workspace }) })
+          return
+        }
+        if (action === 'clear-all') {
+          const reports: WorkspacePurgeReport[] = []
+          const failures: { readonly workspace: string; readonly error: string }[] = []
+          for (const overview of await engine.listWorkspaces()) {
+            try {
+              reports.push(await engine.purgeWorkspace({ workspace: overview.workspace }))
+            } catch (error) {
+              failures.push({ workspace: overview.workspace, error: errorMessage(error) })
+            }
+          }
+          json(response, 200, {
+            status: failures.length > 0 ? 'partial' : 'completed',
+            action,
+            reports,
+            ...(failures.length > 0 ? { failures } : {}),
+          })
+          return
+        }
+        throw new ChangeLedgerError('INVALID_ARGUMENTS', 'action must be "delete", "clear-workspace", or "clear-all"')
+      }
+      json(response, 405, { error: 'method not allowed' })
+    } catch (error) {
+      const status = error instanceof ChangeLedgerError && error.code === 'RESTORE_POINT_NOT_FOUND' ? 404 : 409
+      json(response, status, {
+        error: errorMessage(error),
+        code: error instanceof ChangeLedgerError ? error.code : 'MANAGE_FAILED',
+      })
+    }
+  }
+}
+
 /** Build the exact-route handler as a testable unit. */
 export function createRewindHttpHandler(
   ctx: Pick<Context, 'sessions' | 'sessionQuery' | 'apiProxy'> & { readonly agents?: AgentsLike },
@@ -327,7 +423,16 @@ export function createRewindHttpHandler(
         const detailsOnly = url.searchParams.get('details') === '1'
         const offset = nonNegativeInteger(url.searchParams.get('offset') ?? '0', 'offset')
         const limit = pageSize(url.searchParams.get('limit'), detailsOnly ? MAX_CHANGE_PAGE_SIZE : INITIAL_CHANGE_PREVIEW_LIMIT)
-        const { target, checkpoint } = await resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq)
+        const { session, target } = await resolveMessageTarget(ctx, sessionId, messageSeq)
+        let checkpoint: MessageCheckpoint | undefined
+        try {
+          checkpoint = await resolveMessageCheckpoint(ctx, engine, sessionId, session, target)
+        } catch (error) {
+          // File-checkpoint discovery is allowed to fail independently: the dialog
+          // must still expose message-only rewind for a valid Session boundary.
+          json(response, 200, { status: 'failed', error: errorMessage(error) })
+          return
+        }
         if (checkpoint === undefined) {
           const durableSkip = await engine.findTurnCheckpointSkip({
             cwd: target.cwd,
@@ -383,11 +488,20 @@ export function createRewindHttpHandler(
       if (request.method === 'POST') {
         const body = objectBody(await readBody(request))
         const mode = body.mode
-        if (mode !== 'code' && mode !== 'both') {
-          throw new ChangeLedgerError('INVALID_ARGUMENTS', 'mode must be "code" or "both"')
+        if (mode !== 'code' && mode !== 'both' && mode !== 'messages') {
+          throw new ChangeLedgerError('INVALID_ARGUMENTS', 'mode must be "code", "both", or "messages"')
         }
         const sessionId = requiredText(body.sessionId, 'sessionId')
         const messageSeq = nonNegativeInteger(body.messageSeq, 'messageSeq')
+        if (mode === 'messages') {
+          // Message-only rewind never mutates project files, so no checkpoint, no
+          // restore plan, and no shared-workspace gate apply; the conversation
+          // restart revalidates the message boundary itself.
+          const { target } = await resolveMessageTarget(ctx, sessionId, messageSeq)
+          const fork = await createConversationRestart(ctx, sessionId, target)
+          json(response, 200, { status: 'completed', mode, sessionId: fork.sessionId })
+          return
+        }
         const checkpointId = requiredText(body.checkpointId, 'checkpointId')
         const checkpoint = await checkpointForRequest(ctx, engine, sessionId, messageSeq, checkpointId)
         const activeSessionIds = await sharedWorkspaceSessions(ctx.agents, checkpoint.cwd)
@@ -465,20 +579,29 @@ interface MessageCheckpoint extends MessageTarget {
   readonly id: string
 }
 
+async function resolveMessageTarget(
+  ctx: Pick<Context, 'sessions' | 'sessionQuery'>,
+  sessionId: string,
+  messageSeq: number,
+): Promise<{ readonly session: SessionLike; readonly target: MessageTarget }> {
+  const session = await readSession(ctx, sessionId)
+  return { session, target: messageTarget(session, messageSeq) }
+}
+
 async function resolveMessageCheckpoint(
   ctx: Pick<Context, 'sessions' | 'sessionQuery'>,
   engine: ChangeLedgerEngine,
   sessionId: string,
-  messageSeq: number,
-): Promise<{ readonly target: MessageTarget; readonly checkpoint?: MessageCheckpoint }> {
-  let current = await readSession(ctx, sessionId)
-  const target = messageTarget(current, messageSeq)
+  source: SessionLike,
+  target: MessageTarget,
+): Promise<MessageCheckpoint | undefined> {
+  let current = source
   const direct = await engine.findTurnCheckpoint({ cwd: target.cwd, sessionId, turn: target.turn })
   if (direct !== undefined) {
     if (direct.turnStartSeq !== target.turnStartSeq) {
       throw new ChangeLedgerError('PLAN_STALE', 'the message checkpoint no longer matches its turn start')
     }
-    return { target, checkpoint: { ...target, id: direct.id } }
+    return { ...target, id: direct.id }
   }
 
   const seen = new Set<string>([sessionId])
@@ -490,7 +613,7 @@ async function resolveMessageCheckpoint(
     }
     if (parentId === undefined || seedLength === undefined
       || target.messageSeq >= seedLength || target.turnStartSeq >= seedLength) {
-      return { target }
+      return undefined
     }
     if (seen.has(parentId)) {
       throw new ChangeLedgerError('PLAN_STALE', 'session fork lineage contains a cycle')
@@ -501,7 +624,7 @@ async function resolveMessageCheckpoint(
     } catch (error) {
       throw new ChangeLedgerError('PLAN_STALE', `parent session ${parentId} is unavailable`, { cause: error })
     }
-    const parentTarget = messageTarget(current, messageSeq)
+    const parentTarget = messageTarget(current, target.messageSeq)
     if (parentTarget.turn !== target.turn
       || parentTarget.turnStartSeq !== target.turnStartSeq
       || parentTarget.previousTurnEndSeq !== target.previousTurnEndSeq) {
@@ -512,7 +635,7 @@ async function resolveMessageCheckpoint(
     if (inherited.turnStartSeq !== target.turnStartSeq) {
       throw new ChangeLedgerError('PLAN_STALE', 'the inherited message checkpoint no longer matches the fork boundary')
     }
-    return { target, checkpoint: { ...target, id: inherited.id } }
+    return { ...target, id: inherited.id }
   }
 }
 
@@ -523,7 +646,8 @@ async function checkpointForRequest(
   messageSeq: number,
   requestedId: string,
 ): Promise<MessageCheckpoint> {
-  const { target, checkpoint } = await resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq)
+  const { session, target } = await resolveMessageTarget(ctx, sessionId, messageSeq)
+  const checkpoint = await resolveMessageCheckpoint(ctx, engine, sessionId, session, target)
   if (checkpoint === undefined) {
     throw new ChangeLedgerError('RESTORE_POINT_NOT_FOUND', `message ${String(target.messageSeq)} has no rewind checkpoint`)
   }
@@ -536,23 +660,23 @@ async function checkpointForRequest(
 async function createConversationRestart(
   ctx: Pick<Context, 'sessions' | 'sessionQuery' | 'apiProxy'>,
   sourceId: string,
-  checkpoint: MessageCheckpoint,
+  target: MessageTarget,
 ): Promise<{ readonly sessionId: string }> {
   const source = await readSession(ctx, sourceId)
-  const current = messageTarget(source, checkpoint.messageSeq)
-  if (current.turn !== checkpoint.turn
-    || current.turnStartSeq !== checkpoint.turnStartSeq
-    || current.previousTurnEndSeq !== checkpoint.previousTurnEndSeq) {
+  const current = messageTarget(source, target.messageSeq)
+  if (current.turn !== target.turn
+    || current.turnStartSeq !== target.turnStartSeq
+    || current.previousTurnEndSeq !== target.previousTurnEndSeq) {
     throw new ChangeLedgerError('PLAN_STALE', 'the session no longer contains the selected message boundary')
   }
-  const response = checkpoint.previousTurnEndSeq === undefined
+  const response = target.previousTurnEndSeq === undefined
     ? await ctx.apiProxy.sessions.create({
         rpcId: randomUUID(),
-        payload: { cwd: checkpoint.cwd },
+        payload: { cwd: target.cwd },
       })
     : await ctx.apiProxy.sessions.fork({
         rpcId: randomUUID(),
-        payload: { sessionId: sourceId, atSeq: checkpoint.previousTurnEndSeq },
+        payload: { sessionId: sourceId, atSeq: target.previousTurnEndSeq },
       })
   if (!response.result.ok) {
     throw new ChangeLedgerError('CONVERSATION_REWIND_FAILED', response.result.error.message)

package/src/settings.ts

@@ -0,0 +1,93 @@
+/**
+ * Runtime settings surface for Turn Rewind on the DSH web settings page.
+ * @module @anionex/dsh-turn-rewind
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import z from '@deepseek-ai/schemastery'
+import { resolveConfig, type ChangeLedgerEngine } from './engine.js'
+import type { ChangeLedgerConfig, ResolvedChangeLedgerConfig } from './types.js'
+
+/** Namespace join key shared by the host section and the browser settings card. */
+export const TURN_REWIND_SETTINGS_NAMESPACE = settingsNamespace('turn-rewind')
+
+/** Every runtime-tunable field of {@link ChangeLedgerConfig}; `storageDir` stays config-layer only. */
+export interface TurnRewindSettings {
+  /** Maximum user and rescue restore points retained per workspace. */
+  maxRestorePoints: number
+  /** Maximum automatic turn checkpoints retained per session. */
+  maxTurnCheckpointsPerSession: number
+  /** Maximum number of files in one restore point. */
+  maxFiles: number
+  /** Maximum bytes read from one regular file. */
+  maxFileBytes: number
+  /** Maximum aggregate regular-file bytes in one restore point. */
+  maxSnapshotBytes: number
+  /** Restore-plan lifetime in milliseconds. */
+  planTtlMs: number
+  /** Age after which a lock whose owner is gone may be reclaimed. */
+  staleLockMs: number
+  /** Automatic turn-checkpoint implementation; `off` records durable skips instead. */
+  turnCheckpointMode: 'off' | 'git-native' | 'legacy'
+  /** Maximum time one automatic checkpoint may block the first Agent step. */
+  turnCheckpointTimeoutMs: number
+  /** Maximum uncached worktree bytes read by one automatic Git-native checkpoint. */
+  turnCheckpointMaxNewBytes: number
+  /** Fast trusts fenced Git/stat metadata; strict rereads every eligible path. */
+  turnCheckpointTrust: 'fast' | 'strict'
+}
+
+/** Schemastery schema for the `turn-rewind` settings namespace. */
+export const TurnRewindSettingsSchema: z<TurnRewindSettings> = (() => {
+  const defaults = tunableSettings(resolveConfig({}))
+  return z.object({
+    maxRestorePoints: z.number().step(1).min(1).default(defaults.maxRestorePoints),
+    maxTurnCheckpointsPerSession: z.number().step(1).min(1).default(defaults.maxTurnCheckpointsPerSession),
+    maxFiles: z.number().step(1).min(1).default(defaults.maxFiles),
+    maxFileBytes: z.number().step(1).min(1).default(defaults.maxFileBytes),
+    maxSnapshotBytes: z.number().step(1).min(1).default(defaults.maxSnapshotBytes),
+    planTtlMs: z.number().step(1).min(1).default(defaults.planTtlMs),
+    staleLockMs: z.number().step(1).min(1).default(defaults.staleLockMs),
+    turnCheckpointMode: z.union(['off', 'git-native', 'legacy']).default(defaults.turnCheckpointMode),
+    turnCheckpointTimeoutMs: z.number().step(1).min(1).default(defaults.turnCheckpointTimeoutMs),
+    turnCheckpointMaxNewBytes: z.number().step(1).min(1).default(defaults.turnCheckpointMaxNewBytes),
+    turnCheckpointTrust: z.union(['fast', 'strict']).default(defaults.turnCheckpointTrust),
+  })
+})()
+
+/** Project one resolved configuration onto the settings namespace subset. */
+function tunableSettings(resolved: ResolvedChangeLedgerConfig): TurnRewindSettings {
+  return {
+    maxRestorePoints: resolved.maxRestorePoints,
+    maxTurnCheckpointsPerSession: resolved.maxTurnCheckpointsPerSession,
+    maxFiles: resolved.maxFiles,
+    maxFileBytes: resolved.maxFileBytes,
+    maxSnapshotBytes: resolved.maxSnapshotBytes,
+    planTtlMs: resolved.planTtlMs,
+    staleLockMs: resolved.staleLockMs,
+    turnCheckpointMode: resolved.turnCheckpointMode,
+    turnCheckpointTimeoutMs: resolved.turnCheckpointTimeoutMs,
+    turnCheckpointMaxNewBytes: resolved.turnCheckpointMaxNewBytes,
+    turnCheckpointTrust: resolved.turnCheckpointTrust,
+  }
+}
+
+/**
+ * Register the `turn-rewind` settings namespace and apply its resolved value to the
+ * running engine. The composition entry (from `cordis.patch.yml`) is the base layer;
+ * the user layer persists through the DSH settings provider. `storageDir` is never
+ * carried by the namespace: the storage root must not move while the engine runs.
+ */
+export function installTurnRewindSettings(ctx: Context, config: ChangeLedgerConfig, engine: ChangeLedgerEngine): void {
+  let source: () => TurnRewindSettings = () => tunableSettings(resolveConfig(config))
+  installSettingsSection(ctx, TURN_REWIND_SETTINGS_NAMESPACE, TurnRewindSettingsSchema, source(), {
+    setSource: (current) => { source = current },
+    onChange: () => {
+      try {
+        engine.updateConfig({ ...config, ...source() })
+      } catch (error) {
+        ctx.logger.warn(`[turn-rewind] could not apply settings update: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    },
+  })
+}