dsh-harbor-evolution 0.9.2 → 0.9.3

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/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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-harbor-evolution",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "DeepSeek Harness plugin and Skill for Harbor Candidate and Historical Session evaluation workflows.",
   "type": "module",
   "main": "index.js",

package/schemas/historical-generation-batch.schema.json

@@ -14,6 +14,7 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["cwd_digest"],
+      "description": "Output workspace identity; source projects are recorded per Generation Record.",
       "properties": { "cwd_digest": { "$ref": "#/$defs/digest" } }
     },
     "selection": {
@@ -21,12 +22,31 @@
       "additionalProperties": false,
       "required": ["scope", "order", "requested_limit", "selected_count", "current_session_excluded"],
       "properties": {
-        "scope": { "const": "exact-cwd" },
+        "scope": { "enum": ["exact-cwd", "dsh-history"] },
         "order": { "const": "last-activity-desc" },
         "requested_limit": { "type": "integer", "minimum": 1, "maximum": 10 },
         "selected_count": { "type": "integer", "minimum": 1, "maximum": 10 },
         "current_session_excluded": { "const": true },
-        "created_after": { "type": "string", "format": "date-time" }
+        "created_after": { "type": "string", "format": "date-time" },
+        "scan": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Discovery window metadata. Activity ordering only applies to records read within this window, not unscanned history.",
+          "required": ["scope", "listed_count", "candidate_count", "read_count", "unscanned_count", "partial", "window_order", "selection_order"],
+          "properties": {
+            "scope": { "enum": ["exact-cwd", "dsh-history"] },
+            "listed_count": { "type": "integer", "minimum": 0 },
+            "candidate_count": { "type": "integer", "minimum": 0 },
+            "read_count": { "type": "integer", "minimum": 0 },
+            "unscanned_count": { "type": "integer", "minimum": 0 },
+            "partial": { "type": "boolean" },
+            "window_order": { "enum": ["all-candidates", "created-at-desc"] },
+            "selection_order": { "const": "last-activity-desc" }
+          },
+          "if": { "properties": { "scope": { "const": "exact-cwd" } } },
+          "then": { "properties": { "window_order": { "const": "all-candidates" } } },
+          "else": { "properties": { "window_order": { "const": "created-at-desc" } } }
+        }
       }
     },
     "source": {
@@ -62,6 +82,7 @@
           "source_ref": { "$ref": "#/$defs/digest" },
           "captured_through_seq": { "type": "integer", "minimum": 0 },
           "source_digest": { "$ref": "#/$defs/digest" },
+          "source_project_digest": { "$ref": "#/$defs/digest", "description": "Digest of the source Session project, when known; never inferred from the output workspace." },
           "observation_digest": { "$ref": "#/$defs/digest" },
           "last_activity_at": { "type": "string", "format": "date-time" },
           "generator": { "type": "object" },