dsh-harbor-evolution 0.9.2 → 0.9.4

package/lib/context-snapshots.js

@@ -0,0 +1,83 @@
+import { constants } from 'node:fs'
+import { lstat, mkdir, open, link, unlink } from 'node:fs/promises'
+import { createHash, randomUUID } from 'node:crypto'
+import path from 'node:path'
+
+const MAX_BYTES = 1024 * 1024
+const ID = /^(?:hctx_[A-Za-z0-9_-]{20,80}|hsel_[A-Za-z0-9_-]{24})$/
+const failure = () => new Error('HARBOR_CONTEXT_STORAGE_UNAVAILABLE: Page context could not be safely saved or read. Keep the draft and retry.')
+
+async function directory(projectRoot, sessionId, create) {
+  if (typeof sessionId !== 'string' || !sessionId || sessionId.length > 240) throw failure()
+  let current = path.resolve(projectRoot)
+  const sessionKey = createHash('sha256').update(sessionId).digest('hex')
+  for (const segment of ['.harbor', 'private', 'page-contexts', sessionKey]) {
+    current = path.join(current, segment)
+    if (create) await mkdir(current, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error })
+    const details = await lstat(current)
+    if (!details.isDirectory() || details.isSymbolicLink()) throw failure()
+    if (process.platform !== 'win32' && ((typeof process.getuid === 'function' && details.uid !== process.getuid()) || (details.mode & (segment === '.harbor' ? 0o022 : 0o077)))) throw failure()
+  }
+  return current
+}
+
+/** Read one immutable Session-owned record; absence never selects a replacement. */
+export async function readContextSnapshot(projectRoot, sessionId, id) {
+  if (!ID.test(id ?? '')) throw failure()
+  let handle
+  try {
+    const root = await directory(projectRoot, sessionId, false)
+    handle = await open(path.join(root, `${id}.json`), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+    const details = await handle.stat()
+    if (!details.isFile() || details.size > MAX_BYTES) throw failure()
+    if (process.platform !== 'win32' && ((typeof process.getuid === 'function' && details.uid !== process.getuid()) || (details.mode & 0o077))) throw failure()
+    const record = JSON.parse(await handle.readFile('utf8'))
+    if (record.schema !== 'harbor-context-snapshot/v1' || record.sessionId !== sessionId || record.id !== id || record.projectRoot !== path.resolve(projectRoot)) throw failure()
+    return record.value
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined
+    throw failure()
+  } finally { await handle?.close() }
+}
+
+async function publishImmutable(file, text) {
+  const temporary = path.join(path.dirname(file), `.context-${randomUUID()}.tmp`)
+  let handle
+  try {
+    handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+    await handle.writeFile(text)
+    await handle.sync()
+    await handle.close(); handle = undefined
+    try { await link(temporary, file); return true }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error
+      return false
+    }
+  } catch { throw failure() }
+  finally {
+    await handle?.close()
+    await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error })
+  }
+}
+
+/** Persist only validated identity/revision data, never artifact bodies or credentials. */
+export async function writeContextSnapshot(projectRoot, sessionId, id, value) {
+  if (!ID.test(id ?? '')) throw failure()
+  const text = JSON.stringify({ schema: 'harbor-context-snapshot/v1', sessionId, projectRoot: path.resolve(projectRoot), id, value })
+  if (Buffer.byteLength(text) > MAX_BYTES) throw failure()
+  const root = await directory(projectRoot, sessionId, true)
+  const ignore = path.join(root, '..', '.gitignore')
+  await publishImmutable(ignore, '*\n!.gitignore\n')
+  let ignoreHandle
+  try {
+    ignoreHandle = await open(ignore, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+    const details = await ignoreHandle.stat()
+    if (!details.isFile() || details.size > 1024 || (process.platform !== 'win32' && ((typeof process.getuid === 'function' && details.uid !== process.getuid()) || (details.mode & 0o077)))) throw failure()
+    if (await ignoreHandle.readFile('utf8') !== '*\n!.gitignore\n') throw failure()
+  } catch { throw failure() }
+  finally { await ignoreHandle?.close() }
+  if (!await publishImmutable(path.join(root, `${id}.json`), text)) {
+    const existing = await readContextSnapshot(projectRoot, sessionId, id)
+    if (JSON.stringify(existing) !== JSON.stringify(value)) throw failure()
+  }
+}

package/lib/historical-web.js

@@ -97,10 +97,10 @@ export class HistoricalWebController {
       ownerSessionId: `web-historical:${ownerSessionId}:${this.randomId()}`,
     }
     const preview = await this.sessionDiagnostic.previewWithIdentity({
-      limit: args.limit === undefined ? 10 : args.limit,
+      limit: args.limit === undefined ? 3 : args.limit,
       createdAfter: args.createdAfter,
       includeFeedback: args.includeFeedback !== false,
-    }, identity, { config: resolved.config })
+    }, identity, { config: resolved.config, currentSessionId: ownerSessionId, scope: 'dsh-history' })
     const { selectionToken, ...visible } = preview
     this.previews.set(previewId, {
       previewId,

package/lib/service.js

@@ -4,7 +4,8 @@ import path from 'node:path'
 
 import { loadModelBinding } from './candidate.js'
 import { LOCAL_OBJECT_KINDS, interactionObjectCatalog, resolveCatalogSelection } from './interaction-objects.js'
-import { TrialSelectionRegistry, MAX_SELECTED_TRIALS } from './trial-selection.js'
+import { TrialSelectionRegistry, MAX_SELECTED_TRIALS, frozenTrialSelection, resolveFrozenTrialSelection } from './trial-selection.js'
+import { readContextSnapshot, writeContextSnapshot } from './context-snapshots.js'
 import { ActionDraftController } from './action-drafts.js'
 import { DiagnosticRunner } from './diagnostic-runner.js'
 import { prepareEvaluatorSaveHistory, readEvaluatorSave, recordEvaluatorSave } from './evaluator-saves.js'
@@ -1202,7 +1203,8 @@ export class EvolutionService {
       if (!job) throw new Error('HARBOR_CONTEXT_INVALID: a Trial context requires a Job')
       trialState = await readTrialDetail(config, { job, trial })
     }
-    const objectState = await interactionObjectState(config, normalized, job, jobState, trialState, await this._selectionEntries(normalized, config))
+    const selections = await this._selectionEntries(normalized, config)
+    const objectState = await interactionObjectState(config, normalized, job, jobState, trialState, selections)
     validateInteractionFocus(normalized, trialState)
     validateInteractionObjects(normalized, job, jobState, trialState, objectState)
     // artifactRevision is Host-owned. A browser-supplied value is only an
@@ -1213,11 +1215,14 @@ export class EvolutionService {
       flags: interactionContextSummary(normalized, job, jobState, trialState, objectState).flags,
       artifactRevision: interactionRevision(jobState, trialState, objectState),
     }
-    return this.uiContexts.issue({
+    const issued = this.uiContexts.issue({
       sessionId,
       context,
       projectRoot: config.projectRoot,
     })
+    const entry = this.uiContexts.resolve({ contextSnapshotId: issued.contextSnapshotId, sessionId, projectRoot: config.projectRoot })
+    await writeContextSnapshot(config.projectRoot, sessionId, issued.contextSnapshotId, entry)
+    return { ...issued, durable: true, selectedTrials: selections.flatMap(entry => entry.value.members.map(member => member.id)) }
   }
 
   async resolveUiContext(args, owner) {
@@ -1229,7 +1234,7 @@ export class EvolutionService {
   }
 
   async _resolveUiContext(args, owner) {
-    const entry = this.uiContexts.resolve({
+    const entry = await this._pageContextEntry({
       contextSnapshotId: args?.contextSnapshotId,
       sessionId: owner.sessionId,
       projectRoot: owner.projectRoot,
@@ -1309,6 +1314,19 @@ export class EvolutionService {
     }
   }
 
+  async _pageContextEntry(args) {
+    try { return this.uiContexts.resolve(args) }
+    catch (error) {
+      if (error.code !== 'HARBOR_CONTEXT_EXPIRED') throw error
+    }
+    const saved = await readContextSnapshot(args.projectRoot, String(args.sessionId), args.contextSnapshotId)
+    if (!saved) throw new Error('HARBOR_CONTEXT_EXPIRED: The original page snapshot is unavailable. Open the intended page and send again.')
+    const context = normalizeHarborUiContext(saved.context, String(args.sessionId))
+    const contextDigest = `sha256:${createHash('sha256').update(JSON.stringify(context)).digest('hex')}`
+    if (saved.token !== args.contextSnapshotId || saved.sessionId !== String(args.sessionId) || saved.projectRoot !== path.resolve(args.projectRoot) || saved.digest !== contextDigest) throw new Error('HARBOR_CONTEXT_INVALID: Saved page context failed identity verification.')
+    return { ...saved, context }
+  }
+
   async resolveBrowserUiContext(args = {}) {
     const sessionId = String(args.sessionId ?? '').trim()
     if (!sessionId) throw new Error('HARBOR_CONTEXT_SESSION_MISMATCH: sessionId is required')
@@ -1537,7 +1555,18 @@ export class EvolutionService {
     if (!Array.isArray(ids) || new Set(ids).size !== ids.length || ids.some(id => typeof id !== 'string')) throw new Error('HARBOR_SELECTION_INVALID: Fixed Trial IDs are required.')
     const selected = trials.filter(trial => ids.includes(trial.id))
     if (selected.length !== ids.length) throw new Error('HARBOR_SELECTION_DENIED: A selected Trial is missing or outside this Job/filter.')
-    return this.trialSelections.issue({ sessionId, projectRoot: path.resolve(config.projectRoot), workspace: config.workspaceId, job: args.job, mode: args.mode, filters, trials: selected })
+    const owner = { sessionId, projectRoot: path.resolve(config.projectRoot), workspace: config.workspaceId }
+    const issued = this.trialSelections.issue({ ...owner, job: args.job, mode: args.mode, filters, trials: selected })
+    await writeContextSnapshot(owner.projectRoot, String(sessionId), issued.ref.id, this.trialSelections.owned(issued.ref, owner))
+    return { ...issued, durable: true }
+  }
+
+  async _ownedTrialSelection(ref, owner) {
+    try { return this.trialSelections.owned(ref, owner) }
+    catch (error) { if (!error.message.startsWith('HARBOR_SELECTION_EXPIRED:')) throw error }
+    const saved = await readContextSnapshot(owner.projectRoot, String(owner.sessionId), ref.id)
+    if (!saved) throw new Error('HARBOR_SELECTION_EXPIRED: The original Trial selection is unavailable. Select the intended Trials and send again.')
+    return frozenTrialSelection(saved, ref, owner)
   }
 
   async _selectionEntries(context, config) {
@@ -1545,9 +1574,10 @@ export class EvolutionService {
     if (!refs.length) return []
     const owner = { sessionId: context.sessionId, projectRoot: path.resolve(config.projectRoot), workspace: context.workspace }
     return Promise.all(refs.map(async ref => {
-      const trialIds = this.trialSelections.memberIds(ref, owner)
+      const entry = await this._ownedTrialSelection(ref, owner)
+      const trialIds = entry.members.map(member => member.id)
       const trials = await this._allSelectionTrials(config, { job: context.route.params.job, trialIds })
-      return this.trialSelections.resolve(ref, owner, trials)
+      return resolveFrozenTrialSelection(entry, ref, owner, trials)
     }))
   }
 
@@ -1557,8 +1587,9 @@ export class EvolutionService {
     if (owner.projectRoot !== path.resolve(config.projectRoot)) throw new Error('HARBOR_SELECTION_DENIED: Session project changed.')
     const ref = { kind: 'trial-set', id: args.id, job: args.job, stage: 'judge', sourceDigest: args.sourceDigest, selectionCount: Number(args.selectionCount) }
     const selectionOwner = { ...owner, workspace: config.workspaceId }
-    const trialIds = this.trialSelections.memberIds(ref, selectionOwner)
-    const value = this.trialSelections.resolve(ref, selectionOwner, await this._allSelectionTrials(config, { job: args.job, trialIds }))
+    const entry = await this._ownedTrialSelection(ref, selectionOwner)
+    const trialIds = entry.members.map(member => member.id)
+    const value = resolveFrozenTrialSelection(entry, ref, selectionOwner, await this._allSelectionTrials(config, { job: args.job, trialIds }))
     return { ref: value.ref, count: value.value.count, mode: value.value.mode, members: value.value.members }
   }
 
@@ -1606,7 +1637,7 @@ export class EvolutionService {
     try {
       // The bounded model-facing evidence reader is NOT execution authority.
       // Resolve the Host-owned token and every frozen member independently.
-      const { context } = this.uiContexts.resolve({ contextSnapshotId: draft.contextSnapshotId, ...owner })
+      const { context } = await this._pageContextEntry({ contextSnapshotId: draft.contextSnapshotId, ...owner })
       const { config } = await this._webContext({ workspace: context.workspace, sessionId: owner.sessionId })
       if (path.resolve(config.projectRoot) !== owner.projectRoot) throw new Error('HARBOR_ACTION_DENIED: Session project changed.')
       const job = context.route.params.job ?? context.object?.job

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,8 +224,9 @@ export class SessionDiagnosticService {
       schema_version: 1,
       capability: 'historical-generation-evaluation',
       jobKind: 'historical-generation-evaluation',
-      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,
@@ -269,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')
     }
@@ -303,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-selection.js

@@ -34,12 +34,25 @@ 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) {
@@ -97,6 +110,7 @@ export async function selectRecentSessions({
   sessionQuery,
   projectRoot,
   currentSessionId,
+  scope = 'exact-cwd',
   limit = 10,
   maxSessionReads = 100,
   concurrency = 4,
@@ -109,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,
@@ -131,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
@@ -153,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(
@@ -214,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,
@@ -223,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)