dsh-harbor-evolution 0.8.3 → 0.9.3

package/lib/session-diagnostic.js

@@ -157,10 +157,12 @@ export class SessionDiagnosticService {
   }
 
   async preview(args = {}, exec) {
-    return this.previewWithIdentity(args, executionIdentity(exec), { signal: exec?.signal })
+    // Tool argument schemas may allow undeclared fields. Never let model-supplied
+    // arguments widen the public tool's exact-workspace history boundary.
+    return this.previewWithIdentity(args, executionIdentity(exec), { signal: exec?.signal, scope: 'exact-cwd' })
   }
 
-  async previewWithIdentity(args = {}, requestedIdentity, { signal, config = this.config } = {}) {
+  async previewWithIdentity(args = {}, requestedIdentity, { signal, config = this.config, currentSessionId, scope = 'exact-cwd' } = {}) {
     const identity = normalizedIdentity(requestedIdentity)
     const sessionQuery = capability(this.ctx, 'sessionQuery')
     const limit = args.limit ?? 10
@@ -168,7 +170,8 @@ export class SessionDiagnosticService {
     const result = await selectRecentSessions({
       sessionQuery,
       projectRoot: identity.projectRoot,
-      currentSessionId: identity.ownerSessionId,
+      currentSessionId: currentSessionId ?? identity.ownerSessionId,
+      scope,
       limit,
       maxSessionReads: config.sessionMaxReads ?? 100,
       concurrency: config.sessionReadConcurrency ?? 4,
@@ -176,7 +179,13 @@ export class SessionDiagnosticService {
       signal,
     })
     if (!result.selected.length) {
-      throw new Error('NO_ELIGIBLE_SESSIONS: no completed top-level DSH Sessions with direct human input and assistant output were found in this workspace')
+      if (result.excludedCounts.unreadable > 0 || result.excludedCounts.invalidHeader > 0) {
+        throw new Error('SESSION_HISTORY_READ_FAILED: historical conversations could not be read; retry without changing the working directory')
+      }
+      if (result.scan?.partial) {
+        throw new Error('SESSION_HISTORY_WINDOW_EXHAUSTED: no completed conversations were available in the recent sample; older history was not evaluated')
+      }
+      throw new Error('NO_ELIGIBLE_SESSIONS: no completed conversations with direct human input and assistant output were available in the selected history')
     }
     const judgeBinding = await resolveJudge(this.modelRuntime, args)
     const includeFeedback = args.includeFeedback !== false
@@ -204,7 +213,7 @@ export class SessionDiagnosticService {
       feedbackSnapshots,
       judgeBinding,
       evaluation,
-      parameters: { limit, includeFeedback, createdAfter, scope: 'exact-cwd', order: 'last-activity-desc' },
+      parameters: { limit, includeFeedback, createdAfter, scope, order: 'last-activity-desc', ...(result.scan ? { scan: result.scan } : {}) },
     })
     const warnings = [...result.warnings]
     if (feedbackObservations.some(item => item.failed)) {
@@ -215,9 +224,9 @@ export class SessionDiagnosticService {
       schema_version: 1,
       capability: 'historical-generation-evaluation',
       jobKind: 'historical-generation-evaluation',
-      projectRoot: identity.projectRoot,
-      scope: 'exact-cwd',
+      scope,
       order: 'last-activity-desc',
+      ...(result.scan ? { scan: result.scan } : {}),
       ...(createdAfter === undefined ? {} : { createdAfter: new Date(createdAfter).toISOString() }),
       executionMode: 'observe-existing',
       promotionEligible: false,
@@ -270,7 +279,10 @@ export class SessionDiagnosticService {
     }
     const snapshots = reads.map(item => item.value)
     if (snapshots.some((snapshot, index) => (
-      !verifySessionSnapshot(selectedState.selection[index], snapshot, identity.projectRoot)
+      !verifySessionSnapshot(selectedState.selection[index], snapshot,
+        selectedState.parameters.scope === 'dsh-history'
+          ? selectedState.selection[index].header.cwd
+          : identity.projectRoot)
     ))) {
       throw new Error('SESSION_SAMPLE_CHANGED: at least one selected Session changed after Preview; no Batch was written, preview again')
     }
@@ -304,6 +316,8 @@ export class SessionDiagnosticService {
       observations,
       limit: selectedState.parameters.limit,
       createdAfter: selectedState.parameters.createdAfter,
+      scope: selectedState.parameters.scope,
+      scan: selectedState.parameters.scan,
       now: this.now(),
     })
     const written = await writePrivateHistoricalBatch({

package/lib/session-materializer.js

@@ -12,7 +12,40 @@ function routeName(route) {
   return `${route.provider}/${route.model}`
 }
 
-export function buildHistoricalGenerationBatch({ projectRoot, selections, observations, limit = 10, createdAfter, now = new Date() }) {
+function materializeScan(scan, scope) {
+  if (scan === undefined) return undefined
+  if (
+    !scan || scan.scope !== scope
+    || ![scan.listedCount, scan.candidateCount, scan.readCount, scan.unscannedCount]
+      .every(value => Number.isSafeInteger(value) && value >= 0)
+    || scan.candidateCount > scan.listedCount
+    || scan.readCount + scan.unscannedCount !== scan.candidateCount
+    || scan.partial !== (scan.unscannedCount > 0)
+    || scan.windowOrder !== (scope === 'exact-cwd' ? 'all-candidates' : 'created-at-desc')
+    || scan.selectionOrder !== 'last-activity-desc'
+  ) {
+    throw new Error('HISTORICAL_BATCH_SCAN_INVALID')
+  }
+  return {
+    scope,
+    listed_count: scan.listedCount,
+    candidate_count: scan.candidateCount,
+    read_count: scan.readCount,
+    unscanned_count: scan.unscannedCount,
+    partial: scan.partial,
+    window_order: scan.windowOrder,
+    selection_order: scan.selectionOrder,
+  }
+}
+
+export function buildHistoricalGenerationBatch({
+  projectRoot, selections, observations, limit = 10, createdAfter,
+  scope = 'exact-cwd', scan, now = new Date(),
+}) {
+  if (!['exact-cwd', 'dsh-history'].includes(scope)) {
+    throw new Error('HISTORICAL_BATCH_SCOPE_INVALID')
+  }
+  const selectionScan = materializeScan(scan, scope)
   if (!Array.isArray(selections) || !selections.length || selections.length > 10) {
     throw new Error('HISTORICAL_BATCH_SIZE_INVALID: a batch requires 1 to 10 Session observations')
   }
@@ -35,6 +68,11 @@ export function buildHistoricalGenerationBatch({ projectRoot, selections, observ
       source_ref: selection.sourceRef,
       captured_through_seq: selection.capturedThroughSeq,
       source_digest: selection.sourceDigest,
+      ...(typeof selection.header?.cwd === 'string' && path.isAbsolute(selection.header.cwd)
+        ? { source_project_digest: canonicalDigest(
+            { cwd: path.resolve(selection.header.cwd) }, 'harbor-dsh-project-cwd-v1',
+          ) }
+        : {}),
       observation_digest: observation.digest,
       last_activity_at: observation.source.last_activity_at,
       generator: {
@@ -60,15 +98,17 @@ export function buildHistoricalGenerationBatch({ projectRoot, selections, observ
     batch_id: batchId,
     created_at: now.toISOString(),
     project: {
+      // This identifies the output workspace, not the projects the sessions came from.
       cwd_digest: canonicalDigest({ cwd: path.resolve(projectRoot) }, 'harbor-dsh-project-cwd-v1'),
     },
     selection: {
-      scope: 'exact-cwd',
+      scope,
       order: 'last-activity-desc',
       requested_limit: limit,
       selected_count: records.length,
       current_session_excluded: true,
       ...(createdAfter === undefined ? {} : { created_after: new Date(createdAfter).toISOString() }),
+      ...(selectionScan === undefined ? {} : { scan: selectionScan }),
     },
     source: {
       kind: 'dsh-session',

package/lib/session-redaction.js

@@ -1,20 +1,17 @@
 import { canonicalDigest } from './session-selection.js'
+import {
+  containsCredentialText,
+  containsLocalPath,
+  containsOpaqueSecretText,
+  redactCredentialTextWithCount,
+  redactLocalPathsWithCount,
+  redactOpaqueSecretTextWithCount,
+} from './credential-redaction.js'
 
 const MAX_MESSAGE_CHARS = 4_000
 const MAX_TRANSCRIPT_MESSAGES = 80
 const MAX_OBSERVATION_BYTES = 512 * 1024
 
-const SECRET_PATTERNS = [
-  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gi,
-  /\b(?:authorization\s*[:=]\s*(?:bearer\s+)?|bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi,
-  /\b(?:api[_-]?key|access[_-]?token|refresh[_-]?token|secret|password|passwd)\s*[:=]\s*["']?[^\s,"'}\]]{4,}/gi,
-  /\b(?:sk|rk|pk)-[A-Za-z0-9_-]{12,}\b/g,
-  /\bgh[opusr]_[A-Za-z0-9]{20,}\b/g,
-  /\bAKIA[0-9A-Z]{16}\b/g,
-]
-
-const ABSOLUTE_PATH = /(?:[A-Za-z]:\\(?:[^\s<>:"|?*]+\\)+[^\s<>:"|?*]*|\/(?:Users|home|private|tmp|var|etc|opt|Volumes|workspace)(?:\/[A-Za-z0-9._ @+-]+)+)/g
-
 function replaceCanaries(value, canaries) {
   let text = value
   let replacements = 0
@@ -29,20 +26,13 @@ function replaceCanaries(value, canaries) {
 
 function replaceSecrets(value, canaries = []) {
   const canaryResult = replaceCanaries(value, canaries)
-  value = canaryResult.text
-  let text = value
-  let replacements = canaryResult.replacements
-  for (const pattern of SECRET_PATTERNS) {
-    text = text.replace(pattern, () => {
-      replacements += 1
-      return '[REDACTED_SECRET]'
-    })
+  const credentials = redactCredentialTextWithCount(canaryResult.text, '[REDACTED_SECRET]', false)
+  const opaque = redactOpaqueSecretTextWithCount(credentials.text, '[REDACTED_SECRET]')
+  const paths = redactLocalPathsWithCount(opaque.text, '[REDACTED_PATH]')
+  return {
+    text: paths.text,
+    replacements: canaryResult.replacements + credentials.replacements + opaque.replacements + paths.replacements,
   }
-  text = text.replace(ABSOLUTE_PATH, () => {
-    replacements += 1
-    return '[REDACTED_PATH]'
-  })
-  return { text, replacements }
 }
 
 function sanitizeText(value, maxChars = MAX_MESSAGE_CHARS, canaries = []) {
@@ -181,14 +171,10 @@ function assertNoSecret(value, canaries = []) {
       throw new Error('SESSION_REDACTION_FAILED: a raw Session id survived the redaction pipeline')
     }
   }
-  for (const pattern of SECRET_PATTERNS) {
-    pattern.lastIndex = 0
-    if (pattern.test(serialized)) {
-      throw new Error('SESSION_REDACTION_FAILED: a credential-shaped value survived the redaction pipeline')
-    }
+  if (containsCredentialText(serialized) || containsOpaqueSecretText(serialized)) {
+    throw new Error('SESSION_REDACTION_FAILED: a credential-shaped value survived the redaction pipeline')
   }
-  ABSOLUTE_PATH.lastIndex = 0
-  if (ABSOLUTE_PATH.test(serialized)) {
+  if (containsLocalPath(serialized)) {
     throw new Error('SESSION_REDACTION_FAILED: an absolute local path survived the redaction pipeline')
   }
   if (Buffer.byteLength(serialized) > MAX_OBSERVATION_BYTES) {

package/lib/session-selection.js

@@ -1,6 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto'
 import path from 'node:path'
 
+import { containsCredentialText, containsLocalPath, containsOpaqueSecretText } from './credential-redaction.js'
 import { foldSessionDiagnosticIndex } from './session-projection.js'
 
 function canonicalize(value) {
@@ -33,21 +34,35 @@ function sessionHeaderIdentity(header, effectiveAgentPreset) {
 }
 
 function sameProjectRoot(value, projectRoot) {
-  if (typeof value !== 'string' || !path.isAbsolute(value)) return false
+  if (!validSourceRoot(value) || !validSourceRoot(projectRoot)) return false
   return path.resolve(value) === path.resolve(projectRoot)
 }
 
+function validSourceRoot(value) {
+  return typeof value === 'string' && !value.includes('\0') && path.isAbsolute(value)
+}
+
+function validTimestamp(value) {
+  return Number.isSafeInteger(value) && value >= 0 && value <= 8_640_000_000_000_000
+}
+
+function validSourceHeader(header) {
+  return typeof header?.id === 'string' && header.id.trim().length > 0
+    && validSourceRoot(header.cwd) && validTimestamp(header.createdAt)
+}
+
 function isoTime(value) {
-  return Number.isSafeInteger(value) && value > 0 ? new Date(value).toISOString() : null
+  return validTimestamp(value) && value > 0 ? new Date(value).toISOString() : null
 }
 
 function safeIdentity(value, rawSessionId) {
   const text = typeof value === 'string' ? value : ''
   if (rawSessionId && text.includes(rawSessionId)) return '[redacted-identity]'
   if (
-    /(?:api[_-]?key|token|secret|password|authorization|bearer\s+)/i.test(text)
-    || /(?:^|[\\/])(?:Users|home|private|tmp|var|etc|opt|Volumes)(?:[\\/]|$)/.test(text)
-    || /\b(?:sk|rk|pk)-[A-Za-z0-9_-]{12,}\b/.test(text)
+    containsCredentialText(text)
+    || containsOpaqueSecretText(text)
+    || containsLocalPath(text)
+    || /(?:api[_-]?key|token|secret|password|authorization)/i.test(text)
   ) return '[redacted-identity]'
   return text.slice(0, 160)
 }
@@ -95,6 +110,7 @@ export async function selectRecentSessions({
   sessionQuery,
   projectRoot,
   currentSessionId,
+  scope = 'exact-cwd',
   limit = 10,
   maxSessionReads = 100,
   concurrency = 4,
@@ -107,15 +123,29 @@ export async function selectRecentSessions({
   if (!Number.isInteger(limit) || limit < 1 || limit > 10) {
     throw new Error('SESSION_LIMIT_INVALID: limit must be an integer from 1 to 10')
   }
-  if (createdAfter !== undefined && (!Number.isSafeInteger(createdAfter) || createdAfter < 0)) {
+  if (scope !== 'exact-cwd' && scope !== 'dsh-history') {
+    throw new Error('SESSION_SELECTION_SCOPE_INVALID: scope must be exact-cwd or dsh-history')
+  }
+  if (!Number.isSafeInteger(maxSessionReads) || maxSessionReads < 1) {
+    throw new Error('SESSION_READ_BUDGET_INVALID: maxSessionReads must be a positive integer')
+  }
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+    throw new Error('SESSION_READ_CONCURRENCY_INVALID: concurrency must be a positive integer')
+  }
+  if (createdAfter !== undefined && !validTimestamp(createdAfter)) {
     throw new Error('SESSION_CREATED_AFTER_INVALID: createdAfter must be a valid timestamp')
   }
+  signal?.throwIfAborted()
   const listed = typeof sessionQuery.filterSessions === 'function'
     ? await sessionQuery.filterSessions([
-        { kind: 'cwd', values: [projectRoot] },
+        ...(scope === 'exact-cwd' ? [{ kind: 'cwd', values: [projectRoot] }] : []),
         ...(createdAfter === undefined ? [] : [{ kind: 'created-at', from: createdAfter }]),
       ], signal)
     : await sessionQuery.listSessions(signal)
+  signal?.throwIfAborted()
+  if (!Array.isArray(listed)) {
+    throw new Error('DSH_SESSION_QUERY_INVALID: Session Query returned an invalid Session list')
+  }
   const excludedCounts = {
     outsideWorkspace: 0,
     beforeCreatedAfter: 0,
@@ -129,11 +159,23 @@ export async function selectRecentSessions({
     harborInternal: 0,
     empty: 0,
     unreadable: 0,
+    invalidHeader: 0,
+    duplicate: 0,
   }
   const candidates = []
-  for (const record of Array.isArray(listed) ? listed : []) {
+  const seenSessionIds = new Set()
+  for (const record of listed) {
     const header = record?.header ?? {}
-    if (!sameProjectRoot(header.cwd, projectRoot)) {
+    if (!validSourceHeader(header)) {
+      excludedCounts.invalidHeader += 1
+      continue
+    }
+    if (seenSessionIds.has(header.id)) {
+      excludedCounts.duplicate += 1
+      continue
+    }
+    seenSessionIds.add(header.id)
+    if (scope === 'exact-cwd' && !sameProjectRoot(header.cwd, projectRoot)) {
       excludedCounts.outsideWorkspace += 1
     } else if (header.id === currentSessionId) {
       excludedCounts.currentSession += 1
@@ -151,57 +193,43 @@ export async function selectRecentSessions({
       candidates.push(record)
     }
   }
-  if (candidates.length > maxSessionReads) {
+  if (scope === 'exact-cwd' && candidates.length > maxSessionReads) {
     throw new Error(
       `SESSION_SELECTION_TOO_EXPENSIVE: ${candidates.length} exact Session reads exceed maxSessionReads=${maxSessionReads}; preview again with createdAfter to narrow the scan`,
     )
   }
 
-  const snapshots = await mapConcurrent(candidates, concurrency, async record => {
+  // SessionRecord exposes creation time, not last activity. Bound quick-start
+  // reads by the newest-created candidate window, then rank the exact snapshots
+  // by activity. Explicit scan metadata prevents claiming a global activity rank.
+  if (scope === 'dsh-history') {
+    candidates.sort((left, right) => (
+      right.header.createdAt - left.header.createdAt
+      || left.header.id.localeCompare(right.header.id)
+    ))
+  }
+  const inspectRecord = async record => {
+    signal?.throwIfAborted()
     const snapshot = await sessionQuery.readSession(record.header.id)
-    if (snapshot?.session?.id !== record.header.id) {
+    signal?.throwIfAborted()
+    if (!validSourceHeader(snapshot?.session) || !Array.isArray(snapshot?.events)) {
+      throw new Error('Session Query returned an invalid Session snapshot')
+    }
+    if (JSON.stringify(canonicalize(sessionHeaderIdentity(snapshot.session)))
+      !== JSON.stringify(canonicalize(sessionHeaderIdentity(record.header)))) {
       throw new Error('Session Query returned a mismatched Session header')
     }
-    if (!sameProjectRoot(snapshot.session.cwd, projectRoot)) {
+    if (scope === 'exact-cwd' && !sameProjectRoot(snapshot.session.cwd, projectRoot)) {
       throw new Error('Session Query changed the Session workspace boundary')
     }
-    return snapshot
-  })
-  const eligible = []
-  for (const outcome of snapshots) {
-    if (outcome.status === 'rejected') {
-      excludedCounts.unreadable += 1
-      continue
-    }
-    const snapshot = outcome.value
     const index = foldSessionDiagnosticIndex(snapshot.events, snapshot.session)
-    if (index.lastSeq === null) {
-      excludedCounts.empty += 1
-      continue
-    }
-    if (index.openTurn) {
-      excludedCounts.openTurn += 1
-      continue
-    }
-    if (index.lastTurnReason === 'aborted') {
-      excludedCounts.userAborted += 1
-      continue
-    }
-    if (index.humanMessageCount < 1) {
-      excludedCounts.noDirectHumanInput += 1
-      continue
-    }
-    if (index.assistantMessageCount < 1) {
-      excludedCounts.noAssistantOutput += 1
-      continue
-    }
-    if (index.hasHarborToolCall) {
-      excludedCounts.harborInternal += 1
-      continue
-    }
-    if (/harbor/i.test(String(index.effectiveAgentPreset ?? ''))) {
-      excludedCounts.harborInternal += 1
-      continue
+    if (index.lastSeq === null) return { excluded: 'empty' }
+    if (index.openTurn) return { excluded: 'openTurn' }
+    if (index.lastTurnReason === 'aborted') return { excluded: 'userAborted' }
+    if (index.humanMessageCount < 1) return { excluded: 'noDirectHumanInput' }
+    if (index.assistantMessageCount < 1) return { excluded: 'noAssistantOutput' }
+    if (index.hasHarborToolCall || /harbor/i.test(String(index.effectiveAgentPreset ?? ''))) {
+      return { excluded: 'harborInternal' }
     }
     const header = sessionHeaderIdentity(snapshot.session, index.effectiveAgentPreset)
     const sourceDigest = canonicalDigest(
@@ -212,7 +240,7 @@ export async function selectRecentSessions({
       { id: snapshot.session.id, header },
       'harbor-dsh-session-source-ref-v1',
     )
-    eligible.push({
+    return { selected: {
       rawSessionId: snapshot.session.id,
       header,
       events: snapshot.events,
@@ -221,25 +249,62 @@ export async function selectRecentSessions({
       sourceRef,
       capturedThroughSeq: index.lastSeq,
       trialId: `session-${sourceRef.slice('sha256:'.length, 'sha256:'.length + 12)}`,
-    })
+    } }
+  }
+  const eligible = []
+  const readBudget = Math.min(candidates.length, maxSessionReads)
+  let readCount = 0
+  // Quick experience needs a few useful examples, not every transcript. Stop
+  // after a small concurrent batch supplies enough, without losing the cap.
+  while (readCount < readBudget) {
+    const batch = candidates.slice(readCount, Math.min(readCount + concurrency, readBudget))
+    const snapshots = await mapConcurrent(batch, concurrency, inspectRecord)
+    readCount += batch.length
+    signal?.throwIfAborted()
+    for (const outcome of snapshots) {
+      if (outcome.status === 'rejected') excludedCounts.unreadable += 1
+      else if (outcome.value.excluded) excludedCounts[outcome.value.excluded] += 1
+      else eligible.push(outcome.value.selected)
+    }
+    if (scope === 'dsh-history' && eligible.length >= limit) break
+  }
+  const scan = {
+    scope,
+    listedCount: listed.length,
+    candidateCount: candidates.length,
+    readCount,
+    unscannedCount: candidates.length - readCount,
+    partial: candidates.length > readCount,
+    windowOrder: scope === 'dsh-history' ? 'created-at-desc' : 'all-candidates',
+    selectionOrder: 'last-activity-desc',
   }
   eligible.sort((left, right) => (
     right.index.lastActivityAt - left.index.lastActivityAt
     || left.sourceRef.localeCompare(right.sourceRef)
   ))
   const selected = eligible.slice(0, limit)
+  const warnings = []
+  if (excludedCounts.unreadable) {
+    warnings.push(`${excludedCounts.unreadable} Session(s) could not be read and were excluded.`)
+  }
+  if (excludedCounts.invalidHeader) {
+    warnings.push(`${excludedCounts.invalidHeader} Session record(s) had invalid metadata and were excluded.`)
+  }
+  if (scan.partial) {
+    warnings.push(`Only the ${scan.readCount} most recently created eligible Session candidates were checked; ${scan.unscannedCount} older candidate(s) were not read. Results are ranked by activity within this window, not across all DSH history.`)
+  }
   return {
     selected,
     publicSelected: selected.map(publicSelection),
     excludedCounts,
-    warnings: excludedCounts.unreadable
-      ? [`${excludedCounts.unreadable} Session(s) could not be read and were excluded.`]
-      : [],
+    scan,
+    warnings,
   }
 }
 
 export function verifySessionSnapshot(expected, snapshot, projectRoot) {
-  if (snapshot?.session?.id !== expected.rawSessionId || !sameProjectRoot(snapshot?.session?.cwd, projectRoot)) {
+  if (!validSourceHeader(snapshot?.session) || !Array.isArray(snapshot?.events)
+    || snapshot.session.id !== expected.rawSessionId || !sameProjectRoot(snapshot.session.cwd, projectRoot)) {
     return false
   }
   const index = foldSessionDiagnosticIndex(snapshot.events, snapshot.session)

package/lib/trial-selection.js

@@ -0,0 +1,46 @@
+import { randomBytes } from 'node:crypto'
+import { localObjectDigest } from './interaction-objects.js'
+
+export const MAX_SELECTED_TRIALS = 1000
+
+/** Server-owned, frozen IDs/revisions; a query can never silently expand later. */
+export class TrialSelectionRegistry {
+  constructor({ now = Date.now, ttlMs = 15 * 60_000, maxEntries = 256 } = {}) {
+    this.now = now
+    this.ttlMs = ttlMs
+    this.maxEntries = maxEntries
+    this.entries = new Map()
+  }
+  issue({ sessionId, projectRoot, workspace, job, mode, filters, trials }) {
+    for (const [id, entry] of this.entries) if (entry.expiresAtMs <= this.now()) this.entries.delete(id)
+    if (!['explicit', 'query-snapshot'].includes(mode) || !trials?.length || trials.length > MAX_SELECTED_TRIALS) throw new Error('HARBOR_SELECTION_INVALID: Select 1–1000 Trials.')
+    if (this.entries.size >= this.maxEntries) throw new Error('HARBOR_SELECTION_LIMIT: Too many selections; wait for old selections to expire.')
+    const members = trials.map(trial => ({ id: trial.id, revision: localObjectDigest(trial) }))
+    if (new Set(members.map(item => item.id)).size !== members.length || members.some(item => !item.id)) throw new Error('HARBOR_SELECTION_INVALID: Trial identities must be unique.')
+    const filterDigest = localObjectDigest(filters ?? {})
+    const sourceDigest = localObjectDigest({ mode, filterDigest, members })
+    const id = `hsel_${randomBytes(18).toString('base64url')}`
+    const ref = { kind: 'trial-set', id, job, stage: 'judge', sourceDigest, selectionCount: members.length }
+    const entry = { ref, sessionId: String(sessionId), projectRoot, workspace, job, mode, filterDigest, members, expiresAtMs: this.now() + this.ttlMs }
+    this.entries.set(id, structuredClone(entry))
+    return { ref, count: members.length, mode, filterDigest, expiresAt: new Date(entry.expiresAtMs).toISOString() }
+  }
+  owned(ref, owner) {
+    const entry = this.entries.get(ref.id)
+    if (!entry || entry.expiresAtMs <= this.now()) throw new Error('HARBOR_SELECTION_EXPIRED: Select the Trial set again.')
+    if (entry.sessionId !== String(owner.sessionId) || entry.projectRoot !== owner.projectRoot || entry.workspace !== owner.workspace || entry.job !== ref.job || entry.ref.sourceDigest !== ref.sourceDigest || entry.ref.selectionCount !== ref.selectionCount) throw new Error('HARBOR_SELECTION_DENIED: Selection does not belong to this Session and Job.')
+    return entry
+  }
+  memberIds(ref, owner) {
+    return this.owned(ref, owner).members.map(member => member.id)
+  }
+  resolve(ref, owner, currentTrials) {
+    const entry = this.owned(ref, owner)
+    const byId = new Map(currentTrials.map(trial => [trial.id, trial]))
+    for (const member of entry.members) {
+      const current = byId.get(member.id)
+      if (!current || localObjectDigest(current) !== member.revision) throw new Error('HARBOR_CONTEXT_STALE_SELECTION: Selected Trials changed. Reselect before continuing.')
+    }
+    return { ref: { ...entry.ref }, value: { mode: entry.mode, filterDigest: entry.filterDigest, count: entry.members.length, members: entry.members, trials: entry.members.map(member => byId.get(member.id)) } }
+  }
+}