@linxin666/dsh-client-ui-task-board 0.3.6 → 0.3.9

package/src/core/freeze-snapshot.ts

@@ -0,0 +1,213 @@
+/**
+ * Freeze-request parser and security gate: parses the system-prompt-agreed
+ * freeze format into a structured context snapshot (goal / progress / next),
+ * redacts sensitive patterns to markers, rejects slash-prefixed DSH command
+ * lines, and enforces the 8 KiB per-field byte limit.
+ * Pure functions only: no session, network, or filesystem access.
+ */
+
+/** Hard per-field limit: 8 KiB measured in UTF-8 bytes. */
+export const FREEZE_FIELD_BYTE_LIMIT = 8 * 1024
+
+/** Marker replacing every sensitive match. */
+export const REDACTED_MARKER = '[REDACTED]'
+
+/** Structured context snapshot carried by a continuation card. */
+export interface FreezeSnapshot {
+  goal: string
+  progress: string
+  next: string
+}
+
+/** Non-fatal notices produced by the security gate. */
+export type FreezeWarning = 'redacted'
+
+export type FreezeResult =
+  | { ok: true; snapshot: FreezeSnapshot; warnings: FreezeWarning[] }
+  | { ok: false; error: { code: string; message: string } }
+
+const BEGIN = '<<<FREEZE'
+const END = '>>>FREEZE'
+
+const SECTION_KEYS: ReadonlyMap<string, SectionKey> = new Map([
+  ['目标:', 'goal'],
+  ['进度:', 'progress'],
+  ['下一步:', 'next'],
+])
+
+type SectionKey = 'goal' | 'progress' | 'next'
+
+const SECTION_ORDER: readonly SectionKey[] = ['goal', 'progress', 'next']
+
+const SECTION_NAMES: Record<SectionKey, string> = {
+  goal: '目标',
+  progress: '进度',
+  next: '下一步',
+}
+
+/**
+ * Sensitive patterns, each matched globally over every field body:
+ * PEM private key blocks (whole block collapses to one marker), Bearer
+ * credentials, OpenAI sk-, GitHub ghp_, GitLab glpat-, Slack xox* tokens,
+ * and AWS access key ids.
+ */
+const SENSITIVE_PATTERNS: RegExp[] = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /Bearer\s+[A-Za-z0-9._~+\/=:-]{8,}/gi,
+  /sk-[A-Za-z0-9_-]{8,}/g,
+  /ghp_[A-Za-z0-9]{20,}/g,
+  /glpat-[A-Za-z0-9_-]{15,}/g,
+  /xox[bpars]-[A-Za-z0-9-]{10,}/g,
+  /AKIA[0-9A-Z]{16}/g,
+]
+
+function fail(code: string, message: string): FreezeResult {
+  return { ok: false, error: { code, message } }
+}
+
+function utf8Bytes(text: string): number {
+  return new TextEncoder().encode(text).length
+}
+
+/** Redact sensitive patterns to the marker; reports whether any hit occurred. */
+export function redactSensitive(text: string): { text: string; redacted: boolean } {
+  let out = text
+  let redacted = false
+  for (const pattern of SENSITIVE_PATTERNS) {
+    if (pattern.test(out)) {
+      redacted = true
+      out = out.replace(pattern, REDACTED_MARKER)
+    }
+    pattern.lastIndex = 0
+  }
+  return { text: out, redacted }
+}
+
+/**
+ * True when any line of the text starts with "/" (a DSH command line).
+ * Leading horizontal whitespace before the slash counts too: a frozen
+ * body line like `  /kill` is still a command, not prose.
+ */
+export function hasSlashCommandLines(text: string): boolean {
+  return text.split(/\r?\n/).some(line => /^[ \t]+\//.test(line) || line.startsWith('/'))
+}
+
+/**
+ * Sanitize a structured freeze snapshot (the create/update action payload):
+ * shape check, slash-command taint rejection, sensitive redaction, and the
+ * per-field byte cap - the same gate parseFreezeRequest applies to
+ * free-text freeze requests, exposed for the action data plane (issue #4).
+ * @param value - the freeze object carried by an action or read back from disk.
+ * @param extraKeys - keys allowed alongside goal/progress/next (e.g. the
+ *   protocol redacted flag, the ledger frozenAt stamp) and preserved verbatim
+ *   when present; their validation stays with the caller.
+ */
+export function sanitizeFreezeSnapshot(
+  value: unknown,
+  extraKeys: readonly string[] = [],
+): { ok: true; snapshot: FreezeSnapshot; redacted: boolean; extras: Record<string, unknown> } | { ok: false; error: { code: string; message: string } } {
+  const bad = (code: string, message: string) => ({ ok: false as const, error: { code, message } })
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return bad('invalid-freeze', '冻结快照必须是 goal/progress/next 字符串对象')
+  }
+  const record = value as Record<string, unknown>
+  const allowed = ['goal', 'progress', 'next', ...extraKeys]
+  if (!Object.keys(record).every(key => allowed.includes(key))) {
+    return bad('invalid-freeze', '冻结快照包含未知字段')
+  }
+  for (const key of SECTION_ORDER) {
+    if (typeof record[key] !== 'string') {
+      return bad('invalid-freeze', '冻结快照字段 ' + SECTION_NAMES[key] + ' 必须是字符串')
+    }
+  }
+  for (const key of SECTION_ORDER) {
+    if (hasSlashCommandLines(record[key] as string)) {
+      return bad('dsh-command-line', '冻结文本的' + SECTION_NAMES[key] + '包含以 / 开头的命令行，整体拒绝')
+    }
+  }
+  let redacted = false
+  const snapshot: Record<SectionKey, string> = { goal: '', progress: '', next: '' }
+  for (const key of SECTION_ORDER) {
+    const result = redactSensitive(record[key] as string)
+    snapshot[key] = result.text
+    redacted = redacted || result.redacted
+  }
+  for (const key of SECTION_ORDER) {
+    if (utf8Bytes(snapshot[key]) > FREEZE_FIELD_BYTE_LIMIT) {
+      return bad('field-too-large', '冻结快照字段 ' + SECTION_NAMES[key] + ' 超过 8 KiB 上限')
+    }
+  }
+  const extras: Record<string, unknown> = {}
+  for (const key of extraKeys) if (key in record) extras[key] = record[key]
+  return { ok: true, snapshot: { goal: snapshot.goal, progress: snapshot.progress, next: snapshot.next }, redacted, extras }
+}
+
+/**
+ * Parse the freeze-request format: a <<<FREEZE ... >>>FREEZE block whose body
+ * is 目标: / 进度: / 下一步: section headers, each followed by body lines.
+ * The gate applies before returning: slash-command taint rejects the whole
+ * request, sensitive patterns are redacted to markers, and each field is
+ * capped at FREEZE_FIELD_BYTE_LIMIT UTF-8 bytes.
+ */
+export function parseFreezeRequest(input: string): FreezeResult {
+  const beginIndex = input.indexOf(BEGIN)
+  if (beginIndex === -1) {
+    return fail('missing-block', '未找到冻结请求块（需要 <<<FREEZE ... >>>FREEZE）')
+  }
+  const bodyStart = beginIndex + BEGIN.length
+  const endIndex = input.indexOf(END, bodyStart)
+  if (endIndex === -1) {
+    return fail('unterminated-block', '冻结请求块未闭合（缺少 >>>FREEZE）')
+  }
+  const block = input.slice(bodyStart, endIndex)
+
+  const raw = new Map<SectionKey, string[]>()
+  let current: SectionKey | undefined
+  for (const line of block.split(/\r?\n/)) {
+    const key = SECTION_KEYS.get(line)
+    if (key !== undefined) {
+      if (raw.has(key)) {
+        return fail('duplicate-section', `重复的段落标题：${SECTION_NAMES[key]}`)
+      }
+      raw.set(key, [])
+      current = key
+    } else if (current !== undefined) {
+      raw.get(current)!.push(line)
+    }
+  }
+
+  const snapshot: Record<SectionKey, string> = { goal: '', progress: '', next: '' }
+  for (const key of SECTION_ORDER) {
+    if (!raw.has(key)) {
+      return fail('missing-section', `冻结请求缺少段落：${SECTION_NAMES[key]}`)
+    }
+    const lines = raw.get(key)!
+    while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop()
+    snapshot[key] = lines.join('\n')
+  }
+
+  for (const key of SECTION_ORDER) {
+    if (hasSlashCommandLines(snapshot[key])) {
+      return fail('dsh-command-line', `冻结文本的${SECTION_NAMES[key]}包含以 / 开头的命令行，整体拒绝`)
+    }
+  }
+
+  let redacted = false
+  for (const key of SECTION_ORDER) {
+    const result = redactSensitive(snapshot[key])
+    snapshot[key] = result.text
+    redacted = redacted || result.redacted
+  }
+
+  for (const key of SECTION_ORDER) {
+    if (utf8Bytes(snapshot[key]) > FREEZE_FIELD_BYTE_LIMIT) {
+      return fail('field-too-large', `冻结快照字段 ${SECTION_NAMES[key]} 超过 8 KiB 上限`)
+    }
+  }
+
+  return {
+    ok: true,
+    snapshot: { goal: snapshot.goal, progress: snapshot.progress, next: snapshot.next },
+    warnings: redacted ? ['redacted'] : [],
+  }
+}

package/src/core/handover.ts

@@ -0,0 +1,117 @@
+/**
+ * Handover bundle (issue #5, ADR 0001): the resource reference set a
+ * continuation card carries — the pinned execution triplet (workspace /
+ * agent preset / permission) plus doc/script references — so a picking-up
+ * session can start with zero context.
+ *
+ * Security gate (adversarial scenario b): a bundle whose effective
+ * permission is HIGHER than the session default is an unconfirmed binding.
+ * It enters the pending-confirmation state (the card stores the binding
+ * without a permissionConfirmedAt stamp); manual execution refuses, cron
+ * refuses to schedule, and the human confirm-permission action resolves the
+ * transaction by stamping the confirmation. Any later permission or
+ * handover change re-arms the gate (the confirmation binds the exact
+ * permission value, blocking confirm-then-swap escalation).
+ */
+import { isTaskPermission, type TaskPermission, type TaskRecord } from './tasks.ts'
+
+export type { TaskPermission }
+
+/** Wire shape of a handover bundle (before bundledAt is stamped). */
+export interface TaskHandoverInput {
+  workspaceId?: string
+  mode?: string
+  permission?: TaskPermission
+  references: string[]
+}
+
+/** Persisted handover bundle on a task record. */
+export interface TaskHandover extends TaskHandoverInput {
+  /** When the bundle was attached/replaced (ms epoch, stamped by the use case). */
+  bundledAt: number
+}
+
+/** Most references a bundle may carry. */
+export const HANDOVER_MAX_REFERENCES = 32
+/** Per-reference UTF-8 byte cap. */
+export const HANDOVER_MAX_REFERENCE_BYTES = 512
+/** Total references UTF-8 byte cap. */
+export const HANDOVER_MAX_TOTAL_BYTES = 8 * 1024
+/** Per target-id (workspace/preset) byte cap. */
+export const HANDOVER_MAX_TARGET_BYTES = 256
+
+/** The board's notion of the deployment session-default permission (fail-safe default). */
+export const DEFAULT_SESSION_PERMISSION: TaskPermission = 'read-only'
+
+/** Permission elevation rank (higher = more authority). */
+export const PERMISSION_RANK: ReadonlyMap<TaskPermission, number> = new Map([
+  ['read-only', 0],
+  ['workspace-write', 1],
+  ['danger-full-access', 2],
+])
+
+function byteLength(value: string): number {
+  return new TextEncoder().encode(value).length
+}
+
+/**
+ * Gate a handover bundle from the wire or disk: exact keys, string targets
+ * under the byte cap, a known permission, and a bounded string reference
+ * list. Returns the sanitized bundle, or undefined when rejected.
+ */
+export function sanitizeHandover(value: unknown): TaskHandoverInput | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  const bundle = value as Record<string, unknown>
+  const keys = Object.keys(bundle)
+  if (!keys.every(key => ['workspaceId', 'mode', 'permission', 'references'].includes(key))) return undefined
+  if (!Array.isArray(bundle.references)) return undefined
+  if (bundle.references.length > HANDOVER_MAX_REFERENCES) return undefined
+  let total = 0
+  for (const reference of bundle.references) {
+    if (typeof reference !== 'string' || reference === '') return undefined
+    const size = byteLength(reference)
+    if (size > HANDOVER_MAX_REFERENCE_BYTES) return undefined
+    total += size
+    if (total > HANDOVER_MAX_TOTAL_BYTES) return undefined
+  }
+  for (const key of ['workspaceId', 'mode'] as const) {
+    const target: unknown = bundle[key]
+    if (target !== undefined && (typeof target !== 'string' || byteLength(target) > HANDOVER_MAX_TARGET_BYTES)) return undefined
+  }
+  if (bundle.permission !== undefined && !isTaskPermission(bundle.permission)) return undefined
+  const workspaceId = bundle.workspaceId
+  const mode = bundle.mode
+  return {
+    ...(typeof workspaceId === 'string' ? { workspaceId } : {}),
+    ...(typeof mode === 'string' ? { mode } : {}),
+    ...(bundle.permission === undefined ? {} : { permission: bundle.permission as TaskPermission }),
+    references: [...bundle.references as string[]],
+  }
+}
+
+/** Build the persisted bundle from a sanitized input, stamping bundledAt. */
+export function handoverOf(input: TaskHandoverInput, now: number): TaskHandover {
+  return { ...input, bundledAt: now }
+}
+
+/** The permission an execution session would actually run under. */
+export function effectivePermission(task: Pick<TaskRecord, 'permission' | 'handover'>): TaskPermission | undefined {
+  return task.handover?.permission ?? task.permission
+}
+
+/** Whether a binding's permission is elevated above the session default. */
+export function exceedsSessionDefault(permission: TaskPermission | undefined, sessionDefault: TaskPermission): boolean {
+  if (permission === undefined) return false
+  return (PERMISSION_RANK.get(permission) ?? -1) > (PERMISSION_RANK.get(sessionDefault) ?? -1)
+}
+
+/**
+ * The confirmation-gate predicate: an elevated permission without a human
+ * confirmation stamp. Manual run/rerun and cron must refuse such a card.
+ */
+export function requiresPermissionConfirmation(
+  task: Pick<TaskRecord, 'permission' | 'handover' | 'permissionConfirmedAt'>,
+  sessionDefault: TaskPermission = DEFAULT_SESSION_PERMISSION,
+): boolean {
+  return exceedsSessionDefault(effectivePermission(task), sessionDefault) && task.permissionConfirmedAt === undefined
+}

package/src/core/store.ts

@@ -10,7 +10,10 @@
  * localStorage backend.
  */
 import { isValidCron } from './schedule.ts'
-import { isTaskPermission, isTaskStatus, normalizeTargetId, type ScheduleRule, type TaskRecord, type TaskPermission, type TaskStatus } from './tasks.ts'
+import { isTaskPermission, isTaskStatus, normalizeTargetId, type ScheduleRule, type TaskFreeze, type TaskRecord, type TaskPermission, type TaskStatus } from './tasks.ts'
+import type { TaskHandover } from './handover.ts'
+import { sanitizeFreezeSnapshot } from './freeze-snapshot.ts'
+import { sanitizeHandover } from './handover.ts'
 
 /** Persistence seam for the task ledger. */
 export interface TaskStore {
@@ -72,6 +75,9 @@ function isTaskRecordShape(value: unknown): value is Omit<TaskRecord, 'status'>
     if (entry.endedAt !== undefined && typeof entry.endedAt !== 'number') return false
     if (entry.result !== undefined && entry.result !== 'succeeded' && entry.result !== 'failed' && entry.result !== 'cancelled') return false
     if (entry.error !== undefined && typeof entry.error !== 'string') return false
+    if (entry.initiatedBy !== undefined && typeof entry.initiatedBy !== 'string') return false
+    if (entry.frozenBy !== undefined && typeof entry.frozenBy !== 'string') return false
+    if (entry.frozenAt !== undefined && typeof entry.frozenAt !== 'number') return false
   }
   return true
 }
@@ -107,6 +113,44 @@ function normalizeSchedule(schedule: unknown): ScheduleRule | undefined {
   }
 }
 
+/**
+ * Repair a persisted freeze snapshot: shape + gate re-check (slash taint,
+ * redaction idempotence, byte cap); a malformed or tainted snapshot is
+ * dropped (undefined) rather than dropping the whole task row, mirroring
+ * the schedule repair policy.
+ */
+function normalizeFreeze(value: unknown): TaskFreeze | undefined {
+  const result = sanitizeFreezeSnapshot(value, ['frozenAt', 'redacted', 'frozenBy'])
+  if (!result.ok) return undefined
+  const frozenAt = result.extras.frozenAt
+  if (typeof frozenAt !== 'number' || !Number.isFinite(frozenAt)) return undefined
+  if (result.extras.redacted !== undefined && result.extras.redacted !== true) return undefined
+  const frozenBy = result.extras.frozenBy
+  if (frozenBy !== undefined && (typeof frozenBy !== 'string' || frozenBy === '')) return undefined
+  return {
+    goal: result.snapshot.goal,
+    progress: result.snapshot.progress,
+    next: result.snapshot.next,
+    frozenAt,
+    ...(result.redacted || result.extras.redacted === true ? { redacted: true } : {}),
+    ...(frozenBy === undefined ? {} : { frozenBy }),
+  }
+}
+
+/**
+ * Repair a persisted handover bundle: shape re-check through the same gate
+ * as the wire path; a malformed bundle is dropped rather than dropping the
+ * task row (mirroring the schedule/freeze repair policy).
+ */
+function normalizeHandover(value: unknown): TaskHandover | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const { bundledAt, ...rest } = value as Record<string, unknown> & { bundledAt: unknown }
+  const bundle = sanitizeHandover(rest)
+  if (bundle === undefined) return undefined
+  if (typeof bundledAt !== 'number' || !Number.isFinite(bundledAt)) return undefined
+  return { ...bundle, bundledAt }
+}
+
 /** Parse + validate a persisted ledger document; invalid rows are dropped. */
 export function parseLedger(raw: string | null): TaskRecord[] {
   if (raw === null) return []
@@ -141,6 +185,9 @@ export function parseLedger(raw: string | null): TaskRecord[] {
     task.mode = normalizeTargetId(row.mode)
     task.archivedAt = typeof row.archivedAt === 'number' && Number.isFinite(row.archivedAt) ? row.archivedAt : undefined
     task.permission = isTaskPermission(row.permission) ? row.permission as TaskPermission : undefined
+    task.freeze = normalizeFreeze(row.freeze)
+    task.handover = normalizeHandover(row.handover)
+    task.permissionConfirmedAt = typeof row.permissionConfirmedAt === 'number' && Number.isFinite(row.permissionConfirmedAt) ? row.permissionConfirmedAt : undefined
     tasks.push(task)
   }
   return tasks

package/src/core/tasks.ts

@@ -4,6 +4,8 @@
  * Framework-free (no cordis, no runtime imports) so the state machine is
  * unit-testable in isolation.
  */
+import type { FreezeSnapshot } from './freeze-snapshot.ts'
+import type { TaskHandover, TaskHandoverInput } from './handover.ts'
 
 /** Task lifecycle status, one per kanban column. */
 export type TaskStatus = 'backlog' | 'todo' | 'running' | 'done' | 'failed'
@@ -26,6 +28,16 @@ export interface ExecutionRecord {
   result: 'succeeded' | 'failed' | 'cancelled' | undefined
   /** Human failure text when the run failed (prompt rejection or agent error). */
   error: string | undefined
+  /**
+   * Session id of the DSH session that issued the run/rerun action (issue #6
+   * audit origin). Client-asserted, not a trust boundary; absent when the run
+   * was triggered by cron (source unknown).
+   */
+  initiatedBy?: string
+  /** Freeze instant captured from the card snapshot when the run opened. */
+  frozenAt?: number
+  /** Freeze source session captured from the card snapshot when the run opened. */
+  frozenBy?: string
 }
 
 /**
@@ -64,6 +76,24 @@ export interface ScheduleRule {
   lastTriggeredAt: number | undefined
 }
 
+/**
+ * Frozen context snapshot carried by a continuation card (issue #4): the
+ * goal/progress/next text (already sanitized by the freeze gates) plus the
+ * freeze instant and the redaction warning flag.
+ */
+export interface TaskFreeze extends FreezeSnapshot {
+  /** When the snapshot was frozen (ms epoch, stamped by the create/update use case). */
+  frozenAt: number
+  /** True when the freeze gates redacted sensitive patterns out of the text. */
+  redacted?: boolean
+  /**
+   * Session id of the DSH session that authored the frozen snapshot (issue #6
+   * provenance): stamped by the Host ledger from the create/update action's
+   * initiator, or kept from the wire payload when no initiator was asserted.
+   */
+  frozenBy?: string
+}
+
 /** One task on the board. */
 export interface TaskRecord {
   /** Stable task id (uuid). */
@@ -102,6 +132,25 @@ export interface TaskRecord {
    * `/permission <id>` slash command; absent leaves the session default.
    */
   permission?: TaskPermission
+  /**
+   * Frozen context snapshot for a continuation card; absent on plain tasks.
+   * Sanitized before it enters the ledger (redaction, slash-command taint,
+   * 8 KiB per-field cap) by the protocol gate and re-normalized on load.
+   */
+  freeze?: TaskFreeze
+  /**
+   * Handover bundle carried by a continuation card (issue #5): the pinned
+   * execution triplet plus doc/script references. Sanitized before it
+   * enters the ledger by the protocol gate and re-normalized on load; the
+   * bundle's triplet overrides the legacy pin fields at execution time.
+   */
+  handover?: TaskHandover
+  /**
+   * Human confirmation stamp for an above-default effective permission
+   * (ms epoch). Absent while the binding awaits confirmation; any permission
+   * or handover change re-arms the gate by clearing it.
+   */
+  permissionConfirmedAt?: number
   /**
    * When the task was archived (ms epoch). Archived tasks keep their status
    * and execution history, leave the main board, and cannot run until restored;
@@ -142,6 +191,16 @@ export interface NewTaskInput {
    * case arms it only when enabled and the expression is valid.
    */
   schedule?: { enabled: boolean; cron: string }
+  /**
+   * Optional frozen context snapshot (goal/progress/next, sanitized by the
+   * protocol gate) turning the new task into a continuation card.
+   */
+  freeze?: FreezeSnapshot & { redacted?: boolean; frozenBy?: string }
+  /**
+   * Optional handover bundle (pinned triplet + doc/script references,
+   * sanitized by the protocol gate) attached at creation.
+   */
+  handover?: TaskHandoverInput
 }
 
 /** The five kanban columns, in display order. */
@@ -180,6 +239,24 @@ export function normalizeTargetId(value: string | undefined): string | undefined
   return trimmed === undefined || trimmed === '' ? undefined : trimmed
 }
 
+/**
+ * Build the persisted freeze snapshot from a sanitized input, stamping the
+ * freeze instant (shared by the create and update use cases).
+ */
+export function freezeOf(
+  input: FreezeSnapshot & { redacted?: boolean; frozenBy?: string },
+  now: number,
+): TaskFreeze {
+  return {
+    goal: input.goal,
+    progress: input.progress,
+    next: input.next,
+    frozenAt: now,
+    ...(input.redacted === true ? { redacted: true } : {}),
+    ...(input.frozenBy === undefined || input.frozenBy === '' ? {} : { frozenBy: input.frozenBy }),
+  }
+}
+
 /** Create a task from user input. */
 export function createTask(input: NewTaskInput, now: number, id: string): TaskRecord {
   return {
@@ -194,6 +271,8 @@ export function createTask(input: NewTaskInput, now: number, id: string): TaskRe
     workspaceId: normalizeTargetId(input.workspaceId),
     mode: normalizeTargetId(input.mode),
     permission: isTaskPermission(input.permission) ? input.permission : undefined,
+    ...(input.freeze === undefined ? {} : { freeze: freezeOf(input.freeze, now) }),
+    ...(input.handover === undefined ? {} : { handover: { ...input.handover, bundledAt: now } }),
   }
 }
 
@@ -235,6 +314,7 @@ export function startExecution(
   task: TaskRecord,
   now: number,
   executionId: string,
+  initiatedBy?: string,
 ): { task: TaskRecord; execution: ExecutionRecord } {
   const execution: ExecutionRecord = {
     id: executionId,
@@ -243,6 +323,13 @@ export function startExecution(
     endedAt: undefined,
     result: undefined,
     error: undefined,
+    ...(initiatedBy === undefined || initiatedBy === '' ? {} : { initiatedBy }),
+    // Capture the card's freeze provenance on the execution record so the
+    // audit trail stays queryable even if the snapshot is replaced later.
+    ...(task.freeze === undefined ? {} : {
+      frozenAt: task.freeze.frozenAt,
+      ...(task.freeze.frozenBy === undefined ? {} : { frozenBy: task.freeze.frozenBy }),
+    }),
   }
   return {
     task: {

package/src/core/use-cases/task-update.ts

@@ -4,18 +4,25 @@
  * fresh updatedAt. Pure ledger transition (no persistence or notify — the
  * controller orchestrates those).
  *
- * An explicit `undefined` in the patch clears an execution-target field
- * (the task falls back to the runtime default); content fields are trimmed
- * and never cleared. An unknown permission string is ignored so stale UI
- * can never persist a value the execution service rejects.
+ * An explicit `undefined` in the patch clears the field (the task falls
+ * back to the runtime default); an unknown permission string is ignored so
+ * stale UI can never persist a value the execution service rejects.
  */
-import { isTaskPermission, normalizeTargetId, type TaskRecord, type TaskPermission } from '../tasks.ts'
-
-/** Editable fields on a task (the update patch surface). */
-export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt' | 'workspaceId' | 'mode' | 'permission'>>
+import { freezeOf, isTaskPermission, normalizeTargetId, type TaskRecord, type TaskPermission } from '../tasks.ts'
+import type { FreezeSnapshot } from '../freeze-snapshot.ts'
+import type { TaskHandoverInput } from '../handover.ts'
 
 /**
- * The fields that edit the task's content (what the user reads and what the
+ * Editable fields on a task (the update patch surface). `freeze` replaces the
+ * continuation-card snapshot (restamping frozenAt); an explicit null clears it.
+ */
+export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt' | 'workspaceId' | 'mode' | 'permission'>> & {
+  freeze?: FreezeSnapshot & { redacted?: boolean } | null
+  /** Replaces the handover bundle (restamping bundledAt); an explicit null clears it. */
+  handover?: TaskHandoverInput | null
+}
+
+/** The fields that edit the task's content (what the user reads and what the
  * next execution sends). Unlike the execution targets they stay editable only
  * while the task has never started executing — after the first run the
  * recorded prompt is the record of what actually ran, so it becomes read-only.
@@ -61,10 +68,11 @@ export function applyUpdateTask(
 ): readonly TaskRecord[] {
   return tasks.map(task => {
     if (task.id !== id) return task
+    const { freeze: freezePatch, handover: handoverPatch, ...rest } = patch
     const workspaceId = 'workspaceId' in patch ? normalizeTargetId(patch.workspaceId) : undefined
     const mode = 'mode' in patch ? normalizeTargetId(patch.mode) : undefined
     const permission = 'permission' in patch ? normalizePermission(task.permission, patch.permission) : undefined
-    const next: TaskRecord = { ...task, ...patch, updatedAt: now }
+    const next: TaskRecord = { ...task, ...rest, updatedAt: now }
     // Content fields normalize like creation does (trimmed); an explicit
     // undefined keeps the current value — content cannot be cleared.
     for (const field of TASK_CONTENT_FIELDS) {
@@ -72,6 +80,18 @@ export function applyUpdateTask(
       const value = patch[field]
       next[field] = value === undefined ? task[field] : value.trim()
     }
+    // null (or a vanished key value) clears the snapshot; a present object
+    // replaces it with a fresh frozenAt stamp.
+    next.freeze = freezePatch == null ? undefined : freezeOf(freezePatch, now)
+    // Handover follows the same null-clears convention, restamping bundledAt.
+    next.handover = handoverPatch == null ? undefined : { ...handoverPatch, bundledAt: now }
+    // The permission confirmation binds the exact permission value: a change
+    // of the pinned permission or of the handover bundle re-arms the gate
+    // (blocking confirm-then-swap escalation). handover was destructured out
+    // of rest above, so the stamp survives only when explicitly kept.
+    if (('permission' in patch && patch.permission !== undefined && patch.permission !== task.permission) || 'handover' in patch) {
+      next.permissionConfirmedAt = undefined
+    }
     if (workspaceId !== undefined || 'workspaceId' in patch) next.workspaceId = workspaceId
     if (mode !== undefined || 'mode' in patch) next.mode = mode
     if (permission !== undefined || 'permission' in patch) next.permission = permission

package/src/dsh-home.ts

@@ -39,4 +39,4 @@ export function resolveDshHome(env: NodeJS.ProcessEnv = process.env, home: strin
 /** Resolve the DSH home directory from the live environment. */
 export function dshHome(): string {
   return resolveDshHome()
-}
+}