@try-works/dsh-recursive-mode 0.1.0

package/src/delegation.ts

@@ -0,0 +1,306 @@
+/**
+ * Plugin-driven delegation + report/reference validation + durable action
+ * records (Phase B R4/R6/R7, PROPOSAL 10.5/10.9). The ENFORCED path (distinct
+ * from the agent-driven subagent tool): the plugin calls ctx.subagents.start()
+ * with the full SubagentStartRequest (outputSchema/toolFilter/maxDepth) and
+ * validates the child's references before writing an action record.
+ *
+ * Workspace-scoped (run 03 R1) + fail-loud + optionality-preserving.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+import { contentSha256 } from './review.ts'
+
+/** Minimal host-realm contract for ctx.subagents (the seam we call). */
+export interface SubagentsRuntimeLike {
+  start(name: string, request: SubagentStartRequestLike): Promise<SubagentResultLike>
+  getProvider?(name: string): unknown
+  list?(): unknown
+}
+
+export interface SubagentStartRequestLike {
+  prompt: unknown[] // ContentBlock[]
+  label?: string
+  outputSchema?: Record<string, unknown>
+  toolFilter?: unknown
+  maxDepth?: number
+  persona?: string
+  parent?: unknown
+  signal?: unknown
+}
+
+export interface SubagentResultLike {
+  output?: string
+  structured?: unknown
+  stopReason?: string
+  success?: boolean
+}
+
+export interface DelegationError extends Error {
+  code?: string
+}
+
+export function delegationError(message: string, code: string): DelegationError {
+  const err = new Error(message) as DelegationError
+  err.code = code
+  return err
+}
+
+/** Object-rooted output schema for a delegated review. */
+export function reviewOutputSchema(): Record<string, unknown> {
+  return {
+    type: 'object',
+    properties: {
+      verdict: { type: 'string', enum: ['APPROVE', 'REJECT', 'REVISE'] },
+      findings: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            severity: { type: 'string', enum: ['INFO', 'LOW', 'MEDIUM', 'HIGH'] },
+            title: { type: 'string' },
+            detail: { type: 'string' },
+          },
+          required: ['severity', 'title', 'detail'],
+          additionalProperties: false,
+        },
+      },
+      references: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            lineRange: { type: 'string' },
+          },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ['verdict', 'findings', 'references'],
+    additionalProperties: false,
+  }
+}
+
+/** Default toolFilter for a delegated reviewer (run-relevant, workspace-scoped). */
+export function defaultReviewToolFilter(): unknown {
+  return { allow: ['fs_read', 'grep', 'glob'] }
+}
+
+/**
+ * Call ctx.subagents.start() with the full request. Fail loud on capability
+ * mismatch, missing provider, or unsupported schema (never silent).
+ */
+export async function delegate(input: {
+  subagents: SubagentsRuntimeLike
+  provider: string
+  request: SubagentStartRequestLike
+}): Promise<SubagentResultLike> {
+  const { subagents, provider, request } = input
+  if (!subagents || typeof subagents.start !== 'function') {
+    throw delegationError('ctx.subagents.start is not available (no subagent seam)', 'NO_PROVIDER')
+  }
+  if (!provider) {
+    throw delegationError('No provider named for delegation', 'NO_PROVIDER')
+  }
+  try {
+    return await subagents.start(provider, request)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    const code = (err as { code?: string })?.code
+    if (code === 'UNSUPPORTED_CAPABILITY' || message.includes('UNSUPPORTED_CAPABILITY') || message.includes('does not support')) {
+      throw delegationError(message, 'UNSUPPORTED_CAPABILITY')
+    }
+    throw delegationError(message, 'DELEGATION_FAILED')
+  }
+}
+
+export interface Reference {
+  path: string
+  lineRange?: string
+}
+
+export interface ReferenceCheck {
+  ok: boolean
+  failures: string[]
+  checked: { path: string; ok: boolean; reason?: string }[]
+}
+
+function norm(repoRelative: string): string {
+  return repoRelative.replace(/\\/g, '/').replace(/^\/+/, '')
+}
+
+function resolveUnderRoot(root: string, repoRelative: string): string {
+  const normalized = norm(repoRelative)
+  const rootAbs = resolve(root)
+  const abs = resolve(rootAbs, normalized)
+  const rootPrefix = rootAbs.endsWith(sep) ? rootAbs : rootAbs + sep
+  if (abs !== rootAbs && !abs.startsWith(rootPrefix)) {
+    throw new Error('Path escapes the workspace root: ' + repoRelative)
+  }
+  return abs
+}
+
+/**
+ * Validate every claimed reference: the path exists under root, and a line
+ * range (e.g. '10-20' or '10') is within the file's line count.
+ */
+export function validateReferences(root: string, references: Reference[]): ReferenceCheck {
+  const checked: ReferenceCheck['checked'] = []
+  const failures: string[] = []
+  for (const ref of references) {
+    const rel = norm(ref.path)
+    if (!rel) {
+      checked.push({ path: ref.path, ok: false, reason: 'empty path' })
+      failures.push('empty reference path')
+      continue
+    }
+    let abs: string
+    try {
+      abs = resolveUnderRoot(root, rel)
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err)
+      checked.push({ path: ref.path, ok: false, reason })
+      failures.push(rel + ': ' + reason)
+      continue
+    }
+    if (!existsSync(abs)) {
+      checked.push({ path: ref.path, ok: false, reason: 'path does not exist' })
+      failures.push(rel + ': path does not exist')
+      continue
+    }
+    if (ref.lineRange) {
+      const total = readFileSync(abs, 'utf8').replace(/\r\n/g, '\n').split('\n').length
+      const range = ref.lineRange.trim()
+      const single = /^\d+$/.test(range)
+      const pair = /^(\d+)-(\d+)$/.exec(range)
+      let start = 0
+      let end = 0
+      if (single) {
+        start = Number(range)
+        end = Number(range)
+      } else if (pair) {
+        start = Number(pair[1])
+        end = Number(pair[2])
+      } else {
+        checked.push({ path: ref.path, ok: false, reason: 'invalid lineRange ' + range })
+        failures.push(rel + ': invalid lineRange ' + range)
+        continue
+      }
+      if (start < 1 || end < start || end > total) {
+        const reason = 'lineRange ' + range + ' out of bounds (file has ' + total + ' lines)'
+        checked.push({ path: ref.path, ok: false, reason })
+        failures.push(rel + ': ' + reason)
+        continue
+      }
+    }
+    checked.push({ path: ref.path, ok: true })
+  }
+  return { ok: failures.length === 0, failures, checked }
+}
+
+export interface ActionRecordInput {
+  root: string
+  runId: string
+  subagentId: string
+  phase: string
+  purpose: string
+  executionMode: string
+  artifactPath?: string
+  upstreamArtifacts?: string[]
+  reviewBundle?: string
+  diffBasis?: string
+  codeRefs?: string[]
+  auditQuestions?: string[]
+  actionsTaken?: string[]
+  createdFiles?: string[]
+  modifiedFiles?: string[]
+  reviewedFiles?: string[]
+  findings?: string[]
+  success: boolean
+  stopReason?: string
+}
+
+function slugify(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'action'
+}
+
+/**
+ * Write a durable action record under subagents/ with the canonical sections
+ * (matches recursive-subagent-action.py). A success:false attempt is written
+ * with a failed status and is NOT accepted.
+ */
+export function writeActionRecord(input: ActionRecordInput): string {
+  const { root, runId } = input
+  const dir = resolveUnderRoot(root, '.recursive/run/' + runId + '/subagents')
+  mkdirSync(dir, { recursive: true })
+  const fileName = Date.now() + '-' + slugify(input.subagentId) + '-action.md'
+  const path = join(dir, fileName)
+
+  const list = (title: string, values: string[]) => {
+    const out: string[] = [title]
+    if (!values?.length) {
+      out.push('- none')
+      return out
+    }
+    for (const v of values) out.push('- ' + String.fromCharCode(96) + norm(v) + String.fromCharCode(96))
+    return out
+  }
+
+  const lines: string[] = [
+    '# Subagent action record: ' + input.subagentId,
+    '',
+    '## Metadata',
+    '- Subagent ID: ' + input.subagentId,
+    '- Phase: ' + input.phase,
+    '- Purpose: ' + input.purpose,
+    '- Execution Mode: ' + input.executionMode,
+    '- Status: ' + (input.success ? 'accepted' : 'failed'),
+    '- Stop Reason: ' + (input.stopReason ?? 'n/a'),
+    ...(input.artifactPath ? ['- Current Artifact: ' + String.fromCharCode(96) + norm(input.artifactPath) + String.fromCharCode(96)] : []),
+    ...(input.reviewBundle ? ['- Review Bundle: ' + String.fromCharCode(96) + norm(input.reviewBundle) + String.fromCharCode(96)] : []),
+    '',
+    '## Inputs Provided',
+    ...list('', input.upstreamArtifacts ?? []).slice(1),
+    '',
+    '## Routing',
+    ...(input.diffBasis ? ['- Diff Basis: ' + input.diffBasis] : ['- Diff Basis: n/a']),
+    '',
+    '## Claimed Actions Taken',
+    ...list('', input.actionsTaken ?? []).slice(1),
+    '',
+    '## Claimed File Impact',
+    ...(input.createdFiles?.length ? ['### Created', ...list('', input.createdFiles).slice(1)] : ['### Created', '- none']),
+    ...(input.modifiedFiles?.length ? ['### Modified', ...list('', input.modifiedFiles).slice(1)] : ['### Modified', '- none']),
+    ...(input.reviewedFiles?.length ? ['### Reviewed', ...list('', input.reviewedFiles).slice(1)] : ['### Reviewed', '- none']),
+    '',
+    '## Claimed Artifact Impact',
+    ...list('### Read', input.upstreamArtifacts ?? []).slice(1),
+    '',
+    '## Claimed Findings',
+    ...(input.findings?.length ? input.findings.map((f) => '- ' + f) : ['- none']),
+    '',
+    '## Verification Handoff',
+    '- Inspect first: ' + (input.artifactPath ? String.fromCharCode(96) + norm(input.artifactPath) + String.fromCharCode(96) : 'n/a'),
+    '- Notes: main agent must verify every claimed reference against actual files, actual recursive artifacts, and the actual diff before acceptance.',
+    '',
+  ]
+
+  writeFileSync(path, lines.join('\n'), 'utf8')
+  return path
+}
+
+/**
+ * Accept/reject a delegation result: a success:false or non-completed
+ * stopReason is a failed attempt (diagnostics preserved, NOT accepted).
+ */
+export function evaluateDelegationResult(result: SubagentResultLike): { accepted: boolean; reason: string } {
+  if (result.success === false) {
+    return { accepted: false, reason: 'delegation reported success:false' }
+  }
+  if (result.stopReason && result.stopReason !== 'completed') {
+    return { accepted: false, reason: 'delegation stopped with reason ' + result.stopReason }
+  }
+  return { accepted: true, reason: 'delegation completed' }
+}

package/src/enforcement.ts

@@ -0,0 +1,180 @@
+/**
+ * Enforcement config + pre-step gate + tool guards + tamper detection
+ * (Phase C R3/R4/R7/R8, PROPOSAL 8.4/8.6/13.5).
+ *
+ * Layers 1 and 2 are CALLERS of the lifecycle transition set - they never
+ * reimplement the predicates. Configurable strict|advisory per gate
+ * (default advisory).
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join, isAbsolute, resolve, sep } from 'node:path'
+import { getLockStatus, getPrerequisiteBlockers } from './lock.ts'
+import { getMdFieldValue } from './status.ts'
+import { validateTransition, type PhaseTransitionIntent, type SessionEventLike, detectTransitionIntent } from './lifecycle.ts'
+
+export type EnforcementMode = 'strict' | 'advisory'
+
+export interface EnforcementConfig {
+  preStep: EnforcementMode
+  toolGuards: EnforcementMode
+  tamper: EnforcementMode
+}
+
+/** Validate the enforcement config shape (unknown keys fail at plugin load). */
+export function resolveEnforcementConfig(config: unknown): EnforcementConfig {
+  const raw = (config ?? {}) as Record<string, unknown>
+  const unknown = Object.keys(raw).filter((k) => !['preStep', 'toolGuards', 'tamper'].includes(k))
+  if (unknown.length > 0) {
+    throw new Error('EnforcementConfig has unknown key(s) ' + unknown.join(', ') + ' - config is { preStep, toolGuards, tamper }')
+  }
+  const mode = (value: unknown): EnforcementMode => (value === 'strict' ? 'strict' : 'advisory')
+  return {
+    preStep: mode(raw.preStep),
+    toolGuards: mode(raw.toolGuards),
+    tamper: mode(raw.tamper),
+  }
+}
+
+export const DEFAULT_ENFORCEMENT: EnforcementConfig = { preStep: 'advisory', toolGuards: 'advisory', tamper: 'advisory' }
+
+/**
+ * Layer 1 - agent/pre-step phase-transition gate decision.
+ * Reads on TRANSITION INTENT ONLY (13.5): no transition intent means the step
+ * passes through untouched. On a transition intent whose gates fail:
+ *  - strict  -> reject (turn ends blocked, no model call spent)
+ *  - advisory -> enter (warn only; a recursive/gate-blocked event is emitted)
+ */
+export interface PreStepGateDecision {
+  kind: 'reject' | 'enter'
+  gateBlocked: boolean
+  failures: string[]
+}
+
+export function evaluatePreStepGate(
+  events: readonly SessionEventLike[],
+  mode: EnforcementMode = 'advisory',
+): PreStepGateDecision {
+  const intent = detectTransitionIntent(events)
+  if (!intent || intent.worktreeRoot === '' || intent.runId === '') {
+    return { kind: 'enter', gateBlocked: false, failures: [] }
+  }
+  const check = validateTransition(intent)
+  if (check.passed) return { kind: 'enter', gateBlocked: false, failures: [] }
+  return { kind: mode === 'strict' ? 'reject' : 'enter', gateBlocked: true, failures: check.failures }
+}
+
+/** Tool names the locked-artifact write guard treats as write operations. */
+const WRITE_TOOL_NAMES = new Set(['write', 'edit', 'fs_write', 'fs-write', 'pwsh', 'shell', 'bash', 'run_code'])
+
+/** Tool names the monotonic lock-order guard treats as lock operations. */
+const LOCK_TOOL_NAMES = new Set(['recursive_lock', 'recursive_lock_phase'])
+
+/**
+ * Layer 2 - tools/pre-execute guard decision.
+ * Pure predicate: inspects the pending tool execution (name + args) against
+ * the run tree under the given worktree root.
+ */
+export type ToolGuardDecision = { kind: 'allow' } | { kind: 'deny'; reason: string } | { kind: 'ask'; reason?: string }
+
+export interface ToolExecLike {
+  name: string
+  arguments?: unknown
+  agent?: unknown
+}
+
+export function evaluateToolGuard(
+  exec: ToolExecLike,
+  worktreeRoot: string,
+  activeRunId: string,
+  mode: EnforcementMode = 'advisory',
+): ToolGuardDecision {
+  const name = exec.name
+  const args = (exec.arguments ?? {}) as Record<string, unknown>
+  const runDir = join(worktreeRoot, '.recursive', 'run', activeRunId)
+
+  // Monotonic lock-order denial (recursive_lock out of order).
+  if (LOCK_TOOL_NAMES.has(name)) {
+    const artifact = String(args.artifact ?? '')
+    if (artifact) {
+      const blockers = getPrerequisiteBlockers(runDir, artifact)
+      if (blockers.length > 0) {
+        const reason = 'monotonic lock-order: ' + blockers.map((b) => b.artifact + ' (' + b.status + ')').join(', ')
+        return mode === 'strict' ? { kind: 'deny', reason } : { kind: 'ask', reason }
+      }
+      // TDD evidence gating on Phase 3 lock.
+      if (artifact === '03-implementation-summary.md') {
+        const artifactPath = join(runDir, artifact)
+        const content = existsSync(artifactPath) ? readFileSync(artifactPath, 'utf8') : ''
+        const tddMode = getMdFieldValue(content, 'TDD Mode') ?? ''
+        if (tddMode === 'strict') {
+          const hasRed = /RED|red evidence/i.test(content)
+          const hasGreen = /GREEN|green evidence/i.test(content)
+          if (!hasRed || !hasGreen) {
+            const reason = 'TDD Mode: strict requires RED + GREEN evidence before locking Phase 3'
+            return mode === 'strict' ? { kind: 'deny', reason } : { kind: 'ask', reason }
+          }
+        }
+      }
+    }
+  }
+
+  // Locked-artifact write denial.
+  if (WRITE_TOOL_NAMES.has(name)) {
+    const target = firstTargetPath(args)
+    if (target) {
+      const normalized = target.replace(/\\/g, '/')
+      if (normalized.endsWith('.md') && normalized.includes('/.recursive/run/')) {
+        const abs = resolveTargetPath(normalized, worktreeRoot)
+        if (abs && getLockStatus(abs) === 'LOCKED') {
+          const reason = 'locked-artifact write denial: ' + normalized + ' carries Status: LOCKED (reopen explicitly to edit)'
+          return mode === 'strict' ? { kind: 'deny', reason } : { kind: 'ask', reason }
+        }
+      }
+    }
+  }
+
+  return { kind: 'allow' }
+}
+
+/** Resolve a tool-target path to an absolute path under the worktree root. */
+function resolveTargetPath(target: string, worktreeRoot: string): string | null {
+  const normalized = target.replace(/\\/g, '/')
+  if (isAbsolute(normalized)) {
+    const abs = resolve(normalized)
+    const rootAbs = resolve(worktreeRoot)
+    const rootPrefix = rootAbs.endsWith(sep) ? rootAbs : rootAbs + sep
+    if (abs !== rootAbs && !abs.startsWith(rootPrefix)) return null
+    return abs
+  }
+  return resolve(worktreeRoot, normalized.replace(/^\.?\/?/, ''))
+}
+
+/** Extract the first candidate target path from a tool's arguments. */
+function firstTargetPath(args: Record<string, unknown>): string | null {
+  for (const key of ['file_path', 'path', 'command', 'target', 'filePath']) {
+    const value = args[key]
+    if (typeof value === 'string' && value.trim() !== '') return value.trim()
+  }
+  return null
+}
+
+/**
+ * Layer 8 - fs/observed lock-tamper detection.
+ * A locked *.md whose observed version differs from the stored LockHash is
+ * a tamper. Returns a tamper reason (or null when clean/not-applicable).
+ */
+export function detectTamper(
+  targetPath: string,
+  worktreeRoot: string,
+  activeRunId: string,
+): { runId: string; path: string; reason: string } | null {
+  const normalized = targetPath.replace(/\\/g, '/')
+  if (!normalized.endsWith('.md') || !normalized.includes('/.recursive/run/')) return null
+  const abs = resolveTargetPath(normalized, worktreeRoot)
+  if (!abs || !existsSync(abs)) return null
+  const status = getLockStatus(abs)
+  if (status === 'STALE_LOCK') {
+    return { runId: activeRunId, path: normalized, reason: 'locked artifact hash mismatch (tampered): ' + normalized }
+  }
+  return null
+}

package/src/events.ts

@@ -0,0 +1,173 @@
+/**
+ * recursive/* session events (Phase D R1, PROPOSAL 11.2/11.6): the complete
+ * durable event vocabulary the projection folds, the board renders, and the
+ * conversation node correlates. Every payload carries a non-empty
+ * { runId, worktreeRoot } so the whole plane is worktree-aware and the
+ * projection can group runs by their control-plane root (binding
+ * workspace-scoping invariant, run 03 R1).
+ *
+ * Events are LOG-ONLY (no live mirror): the projection unit (projection.ts)
+ * is the only derived view. Payloads are plain JSON and declared on the
+ * SessionEventMap merge via @deepseek-ai/dsh-session/types.
+ *
+ * The pure constructor helpers below enforce the runId + non-empty
+ * worktreeRoot invariant at emit time, so a malformed event fails loud at
+ * the emit site instead of silently landing cross-workspace.
+ */
+import type { RecursiveRunState } from './types.ts'
+
+/** Declare the recursive/* event family on the session event map (merge-extensible). */
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * A transition the lifecycle driver is ABOUT to validate/commit (logged
+     * before any file write). The pre-step gate reads this as the caller of the
+     * transition set — never a projection event (log-only internal signal).
+     */
+    'recursive/phase-intent': {
+      runId: string
+      worktreeRoot: string
+      targetArtifact: string
+      kind: 'lock' | 'reopen' | 'advance'
+      evidence?: Record<string, unknown>
+    }
+    /** A run was created/bootstrapped in this workspace. */
+    'recursive/run-created': {
+      runId: string
+      worktreeRoot: string
+      template?: string
+      repo?: string
+    }
+    /** A phase transition committed (validate -> commit -> flush -> emit). */
+    'recursive/phase': {
+      runId: string
+      worktreeRoot: string
+      phase: string
+      status: string
+    }
+    /** A phase artifact was locked (lock hash + timestamp recorded). */
+    'recursive/phase-locked': {
+      runId: string
+      worktreeRoot: string
+      phase: string
+      lockedAt: string
+      lockHash: string
+    }
+    /** A transition's gate predicate failed (rejected in strict, warned in advisory). */
+    'recursive/gate-blocked': {
+      runId: string
+      worktreeRoot: string
+      phase: string
+      failures: string[]
+      kind: string
+    }
+    /** fs/observed detected a change to a locked artifact outside a tool call. */
+    'recursive/tamper': {
+      runId: string
+      worktreeRoot: string
+      path: string
+      reason: string
+    }
+    /** A run was merged back to the repo root (conversation history re-keys). */
+    'recursive/run-merged': {
+      runId: string
+      worktreeRoot: string
+      repoRoot: string
+    }
+    /** Run-level lifecycle flag (active/paused/blocked/complete + reason). */
+    'recursive/run-state': {
+      runId: string
+      worktreeRoot: string
+      state: RecursiveRunState
+      reason?: string
+    }
+    /** A subagent started for this run. */
+    'recursive/subagent-start': {
+      runId: string
+      worktreeRoot: string
+      childId: string
+      role: string
+      provider: string
+    }
+    /** A subagent finished for this run. */
+    'recursive/subagent-end': {
+      runId: string
+      worktreeRoot: string
+      childId: string
+      role: string
+      provider: string
+      status: 'running' | 'done' | 'failed'
+    }
+  }
+}
+
+/** Enforce the runId + non-empty worktreeRoot invariant at emit time. */
+export function requireRunKey(runId: string, worktreeRoot: string): void {
+  if (typeof runId !== 'string' || runId.trim() === '') {
+    throw new Error('recursive event requires a non-empty runId')
+  }
+  if (typeof worktreeRoot !== 'string' || worktreeRoot.trim() === '') {
+    throw new Error('recursive event requires a non-empty worktreeRoot')
+  }
+}
+
+export interface PhaseIntentInput { runId: string; worktreeRoot: string; targetArtifact: string; kind: 'lock' | 'reopen' | 'advance'; evidence?: Record<string, unknown> }
+export interface RunCreatedInput { runId: string; worktreeRoot: string; template?: string; repo?: string }
+export interface PhaseInput { runId: string; worktreeRoot: string; phase: string; status: string }
+export interface PhaseLockedInput { runId: string; worktreeRoot: string; phase: string; lockedAt: string; lockHash: string }
+export interface GateBlockedInput { runId: string; worktreeRoot: string; phase: string; failures: string[]; kind: string }
+export interface TamperInput { runId: string; worktreeRoot: string; path: string; reason: string }
+export interface RunMergedInput { runId: string; worktreeRoot: string; repoRoot: string }
+export interface RunStateInput { runId: string; worktreeRoot: string; state: RecursiveRunState; reason?: string }
+export interface SubagentInput { runId: string; worktreeRoot: string; childId: string; role: string; provider: string }
+export interface SubagentEndInput extends SubagentInput { status: 'running' | 'done' | 'failed' }
+
+export function phaseIntent(data: PhaseIntentInput): PhaseIntentInput {
+  requireRunKey(data.runId, data.worktreeRoot)
+  return { runId: data.runId, worktreeRoot: data.worktreeRoot, targetArtifact: data.targetArtifact, kind: data.kind, ...(data.evidence === undefined ? {} : { evidence: data.evidence }) }
+}
+
+export function runCreated(data: RunCreatedInput): RunCreatedInput {
+  requireRunKey(data.runId, data.worktreeRoot)
+  return { runId: data.runId, worktreeRoot: data.worktreeRoot, ...(data.template === undefined ? {} : { template: data.template }), ...(data.repo === undefined ? {} : { repo: data.repo }) }
+}
+
+export function phase(data: PhaseInput): PhaseInput {
+  requireRunKey(data.runId, data.worktreeRoot)
+  return { runId: data.runId, worktreeRoot: data.worktreeRoot, phase: data.phase, status: data.status }
+}
+
+export function phaseLocked(data: PhaseLockedInput): PhaseLockedInput {
+  requireRunKey(data.runId, data.worktreeRoot)
+  return { runId: data.runId, worktreeRoot: data.worktreeRoot, phase: data.phase, lockedAt: data.lockedAt, lockHash: data.lockHash }
+}
+
+export function gateBlocked(data: GateBlockedInput): GateBlockedInput {
+  requireRunKey(data.runId, data.worktreeRoot)
+  return { runId: data.runId, worktreeRoot: data.worktreeRoot, phase: data.phase, failures: data.failures, kind: data.kind }
+}
+
+export function tamper(data: TamperInput): TamperInput {
+  requireRunKey(data.runId, data.worktreeRoot)
+  return { runId: data.runId, worktreeRoot: data.worktreeRoot, path: data.path, reason: data.reason }
+}
+
+export function runMerged(data: RunMergedInput): RunMergedInput {
+  requireRunKey(data.runId, data.worktreeRoot)
+  return { runId: data.runId, worktreeRoot: data.worktreeRoot, repoRoot: data.repoRoot }
+}
+
+export function runState(data: RunStateInput): RunStateInput {
+  requireRunKey(data.runId, data.worktreeRoot)
+  return { runId: data.runId, worktreeRoot: data.worktreeRoot, state: data.state, ...(data.reason === undefined ? {} : { reason: data.reason }) }
+}
+
+export function subagentStart(data: SubagentInput): SubagentInput {
+  requireRunKey(data.runId, data.worktreeRoot)
+  return { runId: data.runId, worktreeRoot: data.worktreeRoot, childId: data.childId, role: data.role, provider: data.provider }
+}
+
+export function subagentEnd(data: SubagentEndInput): SubagentEndInput {
+  requireRunKey(data.runId, data.worktreeRoot)
+  return { runId: data.runId, worktreeRoot: data.worktreeRoot, childId: data.childId, role: data.role, provider: data.provider, status: data.status }
+}