@pellux/goodvibes-agent 1.2.0 → 1.4.1

package/src/tools/agent-harness-research-workflow.ts

@@ -11,6 +11,12 @@ import {
   type AgentResearchSourceRecord,
 } from '../agent/research-source-registry.ts';
 import { browserControlPosture } from './agent-harness-browser-control.ts';
+import {
+  isCertifiedResearchLiveRecord,
+  researchLiveReadModelSnapshot,
+  type ResearchBrowserRunnerRecord,
+  type ResearchVisualReportRecord,
+} from './agent-harness-research-live-read-models.ts';
 import { previewHarnessText } from './agent-harness-text.ts';
 
 interface AgentHarnessResearchWorkflowArgs {
@@ -91,6 +97,41 @@ function relatedSources(
   ));
 }
 
+function liveRunnerSearchText(record: ResearchBrowserRunnerRecord): string {
+  return [
+    record.id,
+    record.runId ?? '',
+    record.status,
+    record.phase ?? '',
+    record.question ?? '',
+    record.currentUrl ?? '',
+    record.reportDraftId ?? '',
+    record.reportArtifactId ?? '',
+    ...record.sourceReceiptIds,
+  ].join('\n').toLowerCase();
+}
+
+function matchingLiveRunners(
+  records: readonly ResearchBrowserRunnerRecord[],
+  run: AgentResearchRunRecord | null,
+  question: string,
+): readonly ResearchBrowserRunnerRecord[] {
+  const normalized = question.toLowerCase();
+  return records.filter((record) => (
+    (!!run && record.runId === run.id)
+    || (!!run?.reportArtifactId && record.reportArtifactId === run.reportArtifactId)
+    || (!!normalized && liveRunnerSearchText(record).includes(normalized))
+  ));
+}
+
+function matchingVisualReports(
+  records: readonly ResearchVisualReportRecord[],
+  run: AgentResearchRunRecord | null,
+): readonly ResearchVisualReportRecord[] {
+  if (!run?.reportArtifactId) return records;
+  return records.filter((record) => record.reportArtifactId === run.reportArtifactId);
+}
+
 function runSummary(run: AgentResearchRunRecord, includeParameters: boolean): Record<string, unknown> {
   return {
     runId: run.id,
@@ -128,14 +169,21 @@ function sourceSummary(source: AgentResearchSourceRecord): Record<string, unknow
   };
 }
 
-function browserRunnerContract(browser: ReturnType<typeof browserControlPosture>): Record<string, unknown> {
+function browserRunnerContract(
+  browser: ReturnType<typeof browserControlPosture>,
+  liveRecords: readonly ResearchBrowserRunnerRecord[],
+): Record<string, unknown> {
+  const certified = liveRecords.filter(isCertifiedResearchLiveRecord);
   return {
-    status: browser.configured ? 'ready-with-confirmation' : 'setup-contract-needed',
+    status: certified.length > 0 ? 'certified-live-runner' : browser.configured ? 'ready-with-confirmation' : 'setup-contract-needed',
     userOutcome: 'Run browser-backed research only when live browser state, authenticated pages, or interactive source discovery are necessary.',
-    currentState: browser.configured
+    currentState: certified.length > 0
+      ? 'The SDK/daemon published certified browser-backed research run records with visible controls, source/page receipts, bounded logs, and exact inspect routes.'
+      : browser.configured
       ? 'A reviewed browser/desktop route is configured; use it only after the user accepts the browser-backed research scope.'
       : 'No reviewed browser-backed research runner is configured, so public web_search/fetch stays the current safe route.',
     requiredContracts: [
+      'Certified schema/version/publication/publisher/provenance/freshness-cursor/receipt metadata for every live browser-backed research run.',
       'Trusted browser or desktop-control route with setup posture status ready.',
       'Visible run id, phase/progress, current URL/task scope, checkpoint route, and pause/resume/cancel controls for every browser-backed research run.',
       'Source-capture receipt for each accepted source with URL/title/publisher/summary/provenance.',
@@ -144,14 +192,17 @@ function browserRunnerContract(browser: ReturnType<typeof browserControlPosture>
       'No credential or page-content leakage outside bounded redacted source summaries.',
     ],
     setupRoutes: [
+      ...certified.slice(0, 3).map((record) => record.modelRoute),
       'computer action:"control" includeParameters:true',
       'computer action:"setup" includeParameters:true',
       browser.setupRoute,
       ...browser.fallbackRoutes,
     ],
-    recommendedRoute: browser.recommendedRoute,
+    recommendedRoute: certified[0]?.modelRoute ?? browser.recommendedRoute,
     fallbackRoutes: browser.fallbackRoutes,
-    policy: 'Browser-backed research is not started by this workflow plan. Use bounded public web/fetch routes until the browser runner contract is ready and the user explicitly confirms the scope.',
+    liveRecords: liveRecords.slice(0, 5),
+    certifiedLiveRecords: certified.slice(0, 5),
+    policy: 'Browser-backed research is not started by this workflow plan. Use certified live SDK/daemon records only as read-only evidence, and use returned confirmed routes before any browser/PWA, source-save, report-save, or Knowledge-ingest effect.',
   };
 }
 
@@ -160,12 +211,16 @@ function visualReportContract(options: {
   readonly reportRoute: string;
   readonly bundleRoute: string;
   readonly question: string;
+  readonly liveRecords: readonly ResearchVisualReportRecord[];
 }): Record<string, unknown> {
+  const certified = options.liveRecords.filter(isCertifiedResearchLiveRecord);
   return {
-    status: options.reviewedSources > 0 ? 'visual-report-packet-ready' : 'waiting-for-reviewed-sources',
+    status: certified.length > 0 ? 'certified-live-renderer' : options.reviewedSources > 0 ? 'visual-report-packet-ready' : 'waiting-for-reviewed-sources',
     userOutcome: 'Produce an inspectable research report with source-backed findings, citations, caveats, and handoff/export routes.',
-    currentRoute: options.reviewedSources > 0 ? options.reportRoute : options.bundleRoute,
-    currentState: options.reviewedSources > 0
+    currentRoute: certified[0]?.modelRoute ?? (options.reviewedSources > 0 ? options.reportRoute : options.bundleRoute),
+    currentState: certified.length > 0
+      ? 'The SDK/daemon published a certified browser/PWA visual report render over the same reviewed report artifact, with source-map and citation-coverage evidence.'
+      : options.reviewedSources > 0
       ? 'Agent can save a citation-covered markdown report artifact with a visual report packet now; browser/PWA rendering remains an optional view over the same artifact.'
       : 'Review at least one source before saving a report or visual packet.',
     requiredSections: [
@@ -184,12 +239,14 @@ function visualReportContract(options: {
       'Every material claim maps to a reviewed source line or an explicit caveat.',
       'The report artifact includes citation coverage metadata and repair hints.',
       'The visual report packet is generated by research action:"report" visualReport:true over the same saved report/source artifacts, not a separate uncited answer.',
+      'Connected-host visual rendering counts only when the SDK/daemon publishes certified render route, source-map, citation coverage, section, publication, and receipt evidence.',
       'Knowledge ingest remains a separate confirmed action after report review.',
     ],
     routes: {
       reviewedSourceBundle: options.bundleRoute,
       saveVisualReport: options.reportRoute,
       saveMarkdownReport: options.reportRoute,
+      ...(certified[0] ? { openRenderedReport: certified[0].renderRoute } : {}),
       reviewPacketWizard: 'agent_harness mode:"document_ops_lane" laneId:"review_packet_wizard"',
       archiveArtifacts: 'agent_artifacts mode:"archive" artifactIds:["..."] destinationPath:"exports/research-report.zip" confirm:true explicitUserRequest:"..."',
     },
@@ -199,6 +256,8 @@ function visualReportContract(options: {
       'agent_harness mode:"document_ops_lane" laneId:"review_packet_wizard"',
       'agent_artifacts mode:"archive" artifactIds:["..."] destinationPath:"exports/research-report.zip" confirm:true explicitUserRequest:"..."',
     ],
+    liveRecords: options.liveRecords.slice(0, 5),
+    certifiedRendererRecords: certified.slice(0, 5),
     policy: `This contract is read-only planning for ${previewHarnessText(options.question, 96)}; saving reports, exports, packages, shares, or Knowledge ingest stay on separate confirmed routes.`,
   };
 }
@@ -216,6 +275,11 @@ export function researchWorkflowSummary(context: CommandContext, args: AgentHarn
   const reviewedSources = matchedSources.filter((source) => source.status === 'reviewed' || source.status === 'used');
   const candidateSources = matchedSources.filter((source) => source.status === 'candidate');
   const browser = browserControlPosture(context);
+  const liveResearch = researchLiveReadModelSnapshot(context);
+  const liveRunnerRecords = matchingLiveRunners(liveResearch.browserRunnerRecords, run, question);
+  const certifiedRunnerRecords = liveRunnerRecords.filter(isCertifiedResearchLiveRecord);
+  const liveVisualRecords = matchingVisualReports(liveResearch.visualReportRecords, run);
+  const certifiedVisualRecords = liveVisualRecords.filter(isCertifiedResearchLiveRecord);
   const status = !shellPaths
     ? 'unavailable'
     : run?.status === 'completed'
@@ -251,20 +315,25 @@ export function researchWorkflowSummary(context: CommandContext, args: AgentHarn
       candidateSources: candidateSources.slice(0, includeParameters ? 8 : 3).map(sourceSummary),
     },
     browserBackedResearch: {
-      status: browser.status,
-      configured: browser.configured,
-      recommendedRoute: browser.recommendedRoute,
+      status: certifiedRunnerRecords.length > 0 ? 'certified-live-runner' : browser.status,
+      configured: browser.configured || certifiedRunnerRecords.length > 0,
+      recommendedRoute: certifiedRunnerRecords[0]?.modelRoute ?? browser.recommendedRoute,
       fallbackRoutes: browser.fallbackRoutes,
       next: browser.configured
         ? 'Use reviewed browser/desktop tooling only when live browser state or authenticated pages are necessary.'
-        : 'Use bounded public web_search/fetch routes now; inspect setup before browser-backed execution.',
+        : certifiedRunnerRecords.length > 0
+          ? 'Inspect the certified live research runner record, then use confirmed routes for follow-up source, report, or browser effects.'
+          : 'Use bounded public web_search/fetch routes now; inspect setup before browser-backed execution.',
+      liveRunnerRecords: liveRunnerRecords.slice(0, includeParameters ? 8 : 3),
+      certifiedLiveRunnerCount: certifiedRunnerRecords.length,
     },
-    browserRunnerContract: browserRunnerContract(browser),
+    browserRunnerContract: browserRunnerContract(browser, liveRunnerRecords),
     visualReportContract: visualReportContract({
       reviewedSources: reviewedSources.length,
       reportRoute,
       bundleRoute,
       question,
+      liveRecords: liveVisualRecords,
     }),
     workflow: [
       {
@@ -276,11 +345,13 @@ export function researchWorkflowSummary(context: CommandContext, args: AgentHarn
       },
       {
         id: 'collect-sources',
-        status: reviewedSources.length > 0 || candidateSources.length > 0 ? 'started' : 'needed',
-        next: browser.configured
+        status: certifiedRunnerRecords.length > 0 ? 'ready' : reviewedSources.length > 0 || candidateSources.length > 0 ? 'started' : 'needed',
+        next: certifiedRunnerRecords.length > 0
+          ? 'Use the certified live runner record to inspect source receipts, then review captured sources before report generation.'
+          : browser.configured
           ? 'Collect bounded sources, preferring primary/current sources, then capture each useful source in the queue.'
           : 'Use web_search/fetch for public sources and capture each useful source in the queue.',
-        route: 'web_search query:"..." verbosity:"evidence" maxResults:10 evidenceTopN:3 or fetch urls:[...]',
+        route: certifiedRunnerRecords[0]?.modelRoute ?? 'web_search query:"..." verbosity:"evidence" maxResults:10 evidenceTopN:3 or fetch urls:[...]',
         captureRoute: `research action:"add_source" question:${quote(question)} title:"..." url:"..." summary:"..." credibility:"unreviewed" tags:["research"] confirm:true explicitUserRequest:"..."`,
       },
       {
@@ -292,9 +363,9 @@ export function researchWorkflowSummary(context: CommandContext, args: AgentHarn
       },
       {
         id: 'save-report',
-        status: reviewedSources.length > 0 ? 'ready' : 'waiting',
-        next: reviewedSources.length > 0 ? 'Use the reviewed-source bundle and save a citation-covered visual report packet artifact.' : 'Save the report only after reviewed or used sources exist.',
-        route: reviewedSources.length > 0 ? bundleRoute : `research action:"sources" query:${quote(sourceQuery)}`,
+        status: certifiedVisualRecords.length > 0 || reviewedSources.length > 0 ? 'ready' : 'waiting',
+        next: certifiedVisualRecords.length > 0 ? 'Inspect the certified browser/PWA report render, then export, archive, or promote only after review.' : reviewedSources.length > 0 ? 'Use the reviewed-source bundle and save a citation-covered visual report packet artifact.' : 'Save the report only after reviewed or used sources exist.',
+        route: certifiedVisualRecords[0]?.modelRoute ?? (reviewedSources.length > 0 ? bundleRoute : `research action:"sources" query:${quote(sourceQuery)}`),
         reportRoute,
       },
       {
@@ -312,6 +383,8 @@ export function researchWorkflowSummary(context: CommandContext, args: AgentHarn
       inspectSources: `research action:"sources" query:${quote(sourceQuery)}`,
       bundleSources: bundleRoute,
       saveReport: reportRoute,
+      ...(certifiedRunnerRecords[0] ? { liveRunner: certifiedRunnerRecords[0].modelRoute } : {}),
+      ...(certifiedVisualRecords[0] ? { liveVisualReport: certifiedVisualRecords[0].modelRoute } : {}),
       ...(run ? {
         checkpointRun: `research action:"checkpoint" id:${quote(run.id)} phase:"reading" progress:${Math.max(run.progress, 25)} note:"..." sourceIds:["..."] confirm:true explicitUserRequest:"..."`,
         completeRun: `research action:"complete" id:${quote(run.id)} reportArtifactId:"..." confirm:true explicitUserRequest:"..."`,

package/src/tools/agent-harness-setup-model-helpers.ts

@@ -11,6 +11,7 @@ export function browserControlSignals(posture: BrowserControlPosture): readonly
       `mcp:${server.name} ${server.connected ? 'connected' : 'disconnected'} ${server.readiness} role=${server.role} trust=${server.trustMode} schema=${server.schemaFreshness}`
     )));
   }
+  if (posture.certifiedRuntimeRecords.length > 0) signals.push(`certified runtime receipts: ${posture.certifiedRuntimeRecords.length}`);
   if (signals.length === 0) signals.push('No browser, desktop, computer-use, screenshot, or screen-recording tool is configured.');
   return signals;
 }

package/src/tools/agent-harness-setup-posture.ts

@@ -30,7 +30,7 @@ export async function setupPostureCatalogStatus(context: CommandContext): Promis
     autonomyBlockers: plan.filter((item) => item.blocksAutonomy && item.status !== 'ready').length,
     nextSetupHandoffs: nextSetupHandoffSummaries(plan, 5),
     setupWizard,
-    setupCloseout: setupWizard.closeout,
+    setupCloseout: setupWizard._diagnostic.closeout,
     collectionIssues: snapshot.collectionIssues.length,
     setupMarkerExists: setupCompletionMarkerExists(context),
     setupSmokeEvidence,
@@ -81,7 +81,7 @@ export async function setupRepairSummary(context: CommandContext, args: AgentHar
       status: setupWizard.status,
       currentStepId: setupWizard.currentStepId,
       currentStepLabel: setupWizard.currentStepLabel,
-      closeout: setupWizard.closeout,
+      closeout: setupWizard._diagnostic.closeout,
     },
     routes: {
       inspectSetup: DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE,
@@ -149,14 +149,14 @@ export async function setupPostureSummary(context: CommandContext, args: AgentHa
         progressLabel: setupWizard.progressLabel,
         currentStepId: setupWizard.currentStepId,
         currentStepLabel: setupWizard.currentStepLabel,
-        repeatedBlocker: setupWizard.repeatedBlocker,
+        repeatedBlocker: setupWizard._diagnostic.repeatedBlocker,
       },
-      setupCloseout: setupWizard.closeout,
+      setupCloseout: setupWizard._diagnostic.closeout,
     },
     setupSmokeEvidence,
     setupSmokeHistory,
     setupWizard,
-    setupCloseout: setupWizard.closeout,
+    setupCloseout: setupWizard._diagnostic.closeout,
     currentRoute: snapshot.providerRouting,
     issues: snapshot.collectionIssues,
     readinessPlan: filteredPlan.map((item) => describePlanItem(item, includeParameters)),
@@ -175,7 +175,7 @@ export async function setupCheckpointSummary(context: CommandContext): Promise<R
   const setupWizard = buildSetupWizard(plan, context);
   return {
     mode: 'setup_checkpoint',
-    checkpoint: setupWizard.checkpoint,
+    checkpoint: setupWizard._diagnostic.checkpoint,
     currentStep: setupWizard.currentStepId
       ? setupWizard.steps.find((step) => step.id === setupWizard.currentStepId) ?? null
       : null,
@@ -254,7 +254,7 @@ export async function markSetupCheckpoint(context: CommandContext, args: AgentHa
       progressLabel: updatedWizard.progressLabel,
       currentStepId: updatedWizard.currentStepId,
       currentStepLabel: updatedWizard.currentStepLabel,
-      checkpoint: updatedWizard.checkpoint,
+      checkpoint: updatedWizard._diagnostic.checkpoint,
     },
     routes: {
       inspectCheckpoint: DEFAULT_AGENT_SETUP_WIZARD_INSPECT_CHECKPOINT_ROUTE,

package/src/tools/agent-harness-setup-smoke.ts

@@ -2,8 +2,10 @@ import type { ArtifactDescriptor } from '@pellux/goodvibes-sdk/platform/artifact
 import type { CommandContext } from '../input/command-registry.ts';
 import { requireShellPaths } from '../input/commands/runtime-services.ts';
 import { readOnboardingCompletionMarker } from '../runtime/onboarding/index.ts';
+import { buildSetupWizardDurableReceipts } from '../agent/setup-wizard-artifact-receipts.ts';
+import { mergeSetupWizardDurableReceipts, setupWizardLiveDurableReceipts } from '../input/setup-wizard-live-receipts.ts';
 import { clearSetupWizardCheckpoint, readSetupWizardCheckpoint, saveSetupWizardCheckpoint } from '../agent/setup-wizard-checkpoint.ts';
-import { DEFAULT_AGENT_SETUP_WIZARD_CLEAR_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_INSPECT_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_MARK_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_RERUN_SMOKE_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_SAVE_SMOKE_ROUTE, buildAgentSetupWizard, emptyAgentSetupSmokeHistory, emptyAgentSetupWizardCheckpoint, type AgentSetupWizard, type AgentSetupWizardCheckpoint, type AgentSetupWizardSmokeHistory, type AgentSetupWizardSourceItem } from '../agent/setup-wizard.ts';
+import { DEFAULT_AGENT_SETUP_WIZARD_CLEAR_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_INSPECT_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_MARK_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_REVIEW_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_RERUN_SMOKE_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_SAVE_SMOKE_ROUTE, buildAgentSetupWizard, emptyAgentSetupSmokeHistory, emptyAgentSetupWizardCheckpoint, type AgentSetupWizard, type AgentSetupWizardCheckpoint, type AgentSetupWizardDurableReceipt, type AgentSetupWizardSmokeHistory, type AgentSetupWizardSourceItem } from '../agent/setup-wizard.ts';
 import { previewHarnessText } from './agent-harness-text.ts';
 import { readFieldMap, readString, safeIso, setupSmokeArtifactStore } from './agent-harness-setup-posture-utils.ts';
 import { setupHandoffsForItem } from './agent-harness-setup-handoffs.ts';
@@ -273,6 +275,12 @@ export function setupSmokeEvidenceTrend(artifacts: readonly ArtifactDescriptor[]
   return 'unchanged';
 }
 
+function artifactCreatedAtIso(artifact: ArtifactDescriptor): string | null {
+  const createdAt = artifact.createdAt;
+  if (typeof createdAt !== 'number' || !Number.isFinite(createdAt)) return null;
+  return new Date(createdAt).toISOString();
+}
+
 export function setupSmokeBlockedCheckFrequency(artifacts: readonly ArtifactDescriptor[]): readonly Record<string, unknown>[] {
   const counts = new Map<string, number>();
   for (const artifact of artifacts) {
@@ -343,6 +351,8 @@ export function setupSmokeEvidenceHistory(context: CommandContext): Record<strin
     trend: setupSmokeEvidenceTrend(artifacts),
     latestResult: readArtifactMetadataString(artifacts[0]!, 'result') || 'unknown',
     previousResult: artifacts[1] ? readArtifactMetadataString(artifacts[1], 'result') || 'unknown' : null,
+    latestEvidenceId: artifacts[0]!.id,
+    latestEvidenceAt: artifactCreatedAtIso(artifacts[0]!),
     resultCounts,
     blockedCheckFrequency: setupSmokeBlockedCheckFrequency(artifacts),
     recent: artifacts.slice(0, 5).map(describeSetupSmokeEvidenceArtifact),
@@ -373,6 +383,8 @@ export function setupWizardSmokeHistory(context: CommandContext): AgentSetupWiza
     trend: setupSmokeEvidenceTrend(artifacts),
     latestResult: readArtifactMetadataString(artifacts[0]!, 'result') || 'unknown',
     previousResult: artifacts[1] ? readArtifactMetadataString(artifacts[1], 'result') || 'unknown' : null,
+    latestEvidenceId: artifacts[0]!.id,
+    latestEvidenceAt: artifactCreatedAtIso(artifacts[0]!),
     resultCounts,
     blockedCheckFrequency: setupSmokeBlockedCheckFrequency(artifacts).map((entry) => ({
       checkId: readString(entry.checkId),
@@ -430,6 +442,17 @@ export function setupWizardCheckpoint(context: CommandContext): AgentSetupWizard
   }
 }
 
+export function setupWizardDurableReceipts(context: CommandContext): readonly AgentSetupWizardDurableReceipt[] {
+  const artifactStore = setupSmokeArtifactStore(context);
+  const liveReceipts = setupWizardLiveDurableReceipts(context);
+  if (!artifactStore?.list) return liveReceipts;
+  try {
+    return mergeSetupWizardDurableReceipts(buildSetupWizardDurableReceipts(artifactStore.list(100)), liveReceipts);
+  } catch {
+    return liveReceipts;
+  }
+}
+
 export function setupCompletionMarkerExists(context: CommandContext): boolean {
   try {
     return readOnboardingCompletionMarker(requireShellPaths(context), 'user').exists;
@@ -467,6 +490,8 @@ export function buildSetupWizard(plan: readonly SetupPlanItem[], context: Comman
     smokeHistory: setupWizardSmokeHistory(context),
     checkpoint: setupWizardCheckpoint(context),
     closeoutCriticalStepIds: plan.filter((item) => item.blocksAutonomy).map((item) => item.id),
+    receiptRequiredStepIds: ['connected-host-readiness', 'connected-host-auth', 'install-smoke'],
+    durableReceipts: setupWizardDurableReceipts(context),
     setupMarkerExists: markerItem?.status === 'ready' || setupCompletionMarkerExists(context),
     repeatedBlockerAliases: SETUP_WIZARD_PLAN_BLOCKER_ALIASES,
   });

package/src/tools/agent-harness-tool-schema.ts

@@ -13,7 +13,7 @@ export const AGENT_HARNESS_MODES = [
   'execution_history', 'execution_history_item',
   'file_recovery', 'run_file_recovery',
   'personal_ops_briefing', 'personal_ops', 'personal_ops_queue', 'personal_ops_intake', 'personal_ops_lane', 'run_personal_ops_read',
-  'memory_posture', 'memory_provider',
+  'memory_posture', 'memory_provider', 'memory_refinement', 'run_memory_refinement',
   'autonomy_intake', 'autonomy_queue', 'autonomy_queue_item',
   'learning_curator', 'learning_candidate',
   'research_briefing', 'research_workflow', 'research_runs', 'research_run',
@@ -242,6 +242,28 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
     type: 'string',
     description: 'Selected Agent-local record id.',
   },
+  knowledgeSpaceId: {
+    type: 'string',
+    description: 'Agent Knowledge space id for memory_refinement or run_memory_refinement.',
+  },
+  sourceIds: {
+    type: 'array',
+    items: { type: 'string' },
+    description: 'Agent Knowledge source ids for scoped semantic refinement.',
+  },
+  gapIds: {
+    type: 'array',
+    items: { type: 'string' },
+    description: 'Agent Knowledge semantic gap ids for scoped refinement.',
+  },
+  maxRunMs: {
+    type: 'number',
+    description: 'Maximum semantic refinement run budget in milliseconds.',
+  },
+  force: {
+    type: 'boolean',
+    description: 'Force semantic refinement reprocessing where supported.',
+  },
   key: {
     type: 'string',
     description: 'Agent setting key.',

package/src/tools/agent-harness-tool-types.ts

@@ -41,6 +41,11 @@ export interface AgentHarnessToolArgs {
   readonly panelId?: unknown;
   readonly actionId?: unknown;
   readonly recordId?: unknown;
+  readonly knowledgeSpaceId?: unknown;
+  readonly sourceIds?: unknown;
+  readonly gapIds?: unknown;
+  readonly maxRunMs?: unknown;
+  readonly force?: unknown;
   readonly fields?: unknown;
   readonly combo?: unknown;
   readonly combos?: unknown;

package/src/tools/agent-harness-tool.ts

@@ -24,6 +24,7 @@ import { describeHarnessMcpServer, mcpServerCatalogStatus, mcpServerSummary } fr
 import { describeHarnessModelRoute, modelRoutingCatalogStatus, modelRoutingSummary, runLocalModelServerSmoke } from './agent-harness-model-routing.ts';
 import { describeHarnessModelTool, listHarnessModelTools } from './agent-harness-model-tool-catalog.ts';
 import { describeMemoryProvider, memoryPostureCatalogStatus, memoryPostureSummary } from './agent-harness-memory-posture.ts';
+import { memoryRefinementCatalogStatus, memoryRefinementSummary, runMemoryRefinement } from './agent-harness-memory-refinement.ts';
 import { describeHarnessOperatorMethod, operatorMethodCatalogStatus, operatorMethodSummary } from './agent-harness-operator-methods.ts';
 import { describePersonalOpsLane, personalOpsBriefingSummary, personalOpsCatalogStatus, personalOpsIntakeSummary, personalOpsQueueSummary, personalOpsSummary, runPersonalOpsRead } from './agent-harness-personal-ops.ts';
 import { describeHarnessPairingRoute, pairingPostureCatalogStatus, pairingPostureSummary } from './agent-harness-pairing-posture.ts';
@@ -99,7 +100,7 @@ function detailedHarnessModelAccessGuide(): Record<string, string> {
     executionHistory: 'Prefer execution action:"history|record" for activity cards and records; use returned verification, supervision, and recovery routes.',
     fileRecovery: 'Prefer execution action:"recovery"; apply local file undo/redo snapshots with mode:"run_file_recovery" and confirmation.',
     personalOps: 'Prefer personal_ops action:"briefing|status|queue|intake|lane|read"; lower-level modes personal_ops_briefing/personal_ops/personal_ops_queue/personal_ops_intake/personal_ops_lane/run_personal_ops_read remain available for harness inspection.',
-    memoryPosture: 'Prefer memory action:"status|provider|curator|candidate|list|search|get"; memory writes, vector rebuilds, and embedding-provider changes stay on confirmed existing routes.',
+    memoryPosture: 'Prefer memory action:"status|provider|refinement|run_refinement|curator|candidate|list|search|get"; run_refinement, memory writes, vector rebuilds, and embedding-provider changes stay on confirmed existing routes.',
     autonomyQueue: 'Prefer autonomy action:"intake|queue|item" for ongoing work and visible autonomous work; lower-level autonomy_* modes remain available for detail. Effects stay confirmed on the owning route.',
     learningCurator: 'Prefer memory action:"curator|candidate"; writes stay on reviewed Agent-local routes.',
     researchWorkflow: 'Prefer research action:"briefing" for the current next-action queue, action:"plan" for deep-research route planning, action:"search" for bounded public source candidates, and action:"runner" for browser-runner readiness; lower-level mode:"research_workflow" sequences visible run, web/fetch or browser posture, source queue, report, and Knowledge promotion routes.',
@@ -176,6 +177,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             status: 'unavailable',
             error: formatHarnessError(err),
           }));
+          const memoryRefinement = memoryRefinementCatalogStatus(deps.commandContext);
           const autonomyQueue = autonomyQueueCatalogStatus(deps.commandContext);
           const learningCurator = learningCuratorCatalogStatus(deps.commandContext);
           const researchBriefing = researchBriefingCatalogStatus(deps.commandContext);
@@ -232,6 +234,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             fileRecovery,
             personalOps,
             memoryPosture,
+            memoryRefinement,
             autonomyQueue,
             learningCurator,
             researchBriefing,
@@ -483,6 +486,11 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
           if (resolved.status === 'ambiguous') return error(`Ambiguous memory provider ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
           return error(resolved.usage);
         }
+        if (args.mode === 'memory_refinement') return output(memoryRefinementSummary(deps.commandContext, args));
+        if (args.mode === 'run_memory_refinement') {
+          const confirmationError = requireConfirmedAction(args, 'Agent Knowledge semantic refinement');
+          return confirmationError ? error(confirmationError) : output(await runMemoryRefinement(deps.commandContext, args));
+        }
         if (args.mode === 'autonomy_intake') return output(autonomyIntakeSummary(deps.commandContext, args));
         if (args.mode === 'autonomy_queue') return output(autonomyQueueSummary(deps.commandContext, args));
         if (args.mode === 'autonomy_queue_item') {

package/src/tools/agent-harness-workspace-actions.ts

@@ -322,7 +322,7 @@ export function describeWorkspaceAction(
         confirmation: 'required',
         readinessRoute: 'agent_harness mode:"ui_surface" surfaceId:"connected-browser-cockpit" includeParameters:true',
         fallback: 'Inspect host action:"service" endpointId:"web" or host action:"services" when the web cockpit is not enabled.',
-        note: 'Opens the connected-host browser/PWA cockpit through the configured web route; readiness inspection also reports workspace category coverage, mobile/PWA controls, and first-run receipt gaps without creating a separate Agent-hosted web app.',
+        note: 'Opens the connected-host browser/PWA cockpit through the configured web route; readiness inspection also reports certified workspace category coverage, mobile/PWA controls, and first-run receipt evidence without creating a separate Agent-hosted web app.',
       },
     } : {}),
     ...(action.kind === 'local-selection' || action.kind === 'local-operation' ? {

package/src/tools/agent-memory-tool.ts

@@ -6,6 +6,8 @@ import { createAgentHarnessTool } from './agent-harness-tool.ts';
 type AgentMemoryAction =
   | 'status'
   | 'provider'
+  | 'refinement'
+  | 'run_refinement'
   | 'curator'
   | 'candidate'
   | 'list'
@@ -24,6 +26,9 @@ interface AgentMemoryToolArgs {
   readonly recordId?: unknown;
   readonly providerId?: unknown;
   readonly candidateId?: unknown;
+  readonly knowledgeSpaceId?: unknown;
+  readonly sourceIds?: unknown;
+  readonly gapIds?: unknown;
   readonly target?: unknown;
   readonly query?: unknown;
   readonly includeParameters?: unknown;
@@ -36,6 +41,8 @@ interface AgentMemoryToolArgs {
   readonly confidence?: unknown;
   readonly tags?: unknown;
   readonly reason?: unknown;
+  readonly maxRunMs?: unknown;
+  readonly force?: unknown;
   readonly confirm?: unknown;
   readonly explicitUserRequest?: unknown;
 }
@@ -61,6 +68,8 @@ function normalizeMemoryAction(value: unknown): AgentMemoryAction | null {
   if (!action) return null;
   if (action === 'status' || action === 'summary' || action === 'posture' || action === 'memory_posture' || action === 'recall' || action === 'providers') return 'status';
   if (action === 'provider' || action === 'memory_provider' || action === 'embedding' || action === 'external' || action === 'external_provider') return 'provider';
+  if (action === 'refinement' || action === 'refinement_tasks' || action === 'semantic_refinement' || action === 'self_improvement' || action === 'semantic_self_improvement' || action === 'learning_loop') return 'refinement';
+  if (action === 'run_refinement' || action === 'refine' || action === 'run_semantic_refinement' || action === 'run_self_improvement' || action === 'self_improve') return 'run_refinement';
   if (action === 'curator' || action === 'learning' || action === 'learning_curator' || action === 'queue' || action === 'review_queue' || action === 'plan') return 'curator';
   if (action === 'candidate' || action === 'learning_candidate' || action === 'card' || action === 'inspect_candidate') return 'candidate';
   if (action === 'list' || action === 'records' || action === 'memories') return 'list';
@@ -131,7 +140,7 @@ export function createAgentMemoryTool(deps: AgentMemoryToolDeps): Tool {
         properties: {
           action: {
             type: 'string',
-            enum: ['status', 'provider', 'curator', 'candidate', 'list', 'search', 'get', 'create', 'update', 'review', 'stale', 'delete'],
+            enum: ['status', 'provider', 'refinement', 'run_refinement', 'curator', 'candidate', 'list', 'search', 'get', 'create', 'update', 'review', 'stale', 'delete'],
             description: 'Read memory posture/providers/curator or operate records.',
           },
           mode: { type: 'string', description: 'Alias for action.' },
@@ -139,6 +148,9 @@ export function createAgentMemoryTool(deps: AgentMemoryToolDeps): Tool {
           recordId: { type: 'string', description: 'Alias for id.' },
           providerId: { type: 'string', description: 'Embedding or external-memory provider id.' },
           candidateId: { type: 'string', description: 'Learning curator candidate id.' },
+          knowledgeSpaceId: { type: 'string', description: 'Agent Knowledge space id for semantic refinement.' },
+          sourceIds: { type: 'array', items: { type: 'string' }, description: 'Agent Knowledge source ids for scoped semantic refinement.' },
+          gapIds: { type: 'array', items: { type: 'string' }, description: 'Agent Knowledge semantic gap ids for scoped refinement.' },
           target: { type: 'string', description: 'Lookup target or search text.' },
           query: { type: 'string', description: 'Search text.' },
           includeParameters: { type: 'boolean', description: 'Include provider setup contracts or candidate details.' },
@@ -151,6 +163,8 @@ export function createAgentMemoryTool(deps: AgentMemoryToolDeps): Tool {
           confidence: { type: 'number', description: 'Review confidence, 0-100.' },
           tags: { type: 'array', items: { type: 'string' }, description: 'Memory tags.' },
           reason: { type: 'string', description: 'Reason for stale/delete decisions.' },
+          maxRunMs: { type: 'number', description: 'Maximum semantic refinement run budget in milliseconds.' },
+          force: { type: 'boolean', description: 'Force semantic refinement reprocessing where supported.' },
           confirm: { type: 'boolean', description: 'Required for deletion and other confirmed memory effects.' },
           explicitUserRequest: { type: 'string', description: 'User request authorizing confirmed memory effects.' },
         },
@@ -180,6 +194,31 @@ export function createAgentMemoryTool(deps: AgentMemoryToolDeps): Tool {
           includeParameters: args.includeParameters,
         }));
       }
+      if (action === 'refinement') {
+        return harnessTool.execute(compactArgs({
+          mode: 'memory_refinement',
+          target: args.target,
+          query: args.query,
+          knowledgeSpaceId: args.knowledgeSpaceId,
+          sourceIds: args.sourceIds,
+          gapIds: args.gapIds,
+          limit: args.limit,
+          includeParameters: args.includeParameters,
+        }));
+      }
+      if (action === 'run_refinement') {
+        return harnessTool.execute(compactArgs({
+          mode: 'run_memory_refinement',
+          knowledgeSpaceId: args.knowledgeSpaceId,
+          sourceIds: args.sourceIds,
+          gapIds: args.gapIds,
+          limit: args.limit,
+          maxRunMs: args.maxRunMs,
+          force: args.force,
+          confirm: args.confirm,
+          explicitUserRequest: args.explicitUserRequest,
+        }));
+      }
       if (action === 'curator') {
         return harnessTool.execute(compactArgs({
           mode: 'learning_curator',

package/src/tools/agent-model-compare-run.ts

@@ -461,6 +461,18 @@ export function toArtifactCandidate(candidate: CompareCandidateResult): Record<s
   };
 }
 
+export function toArtifactCandidateLatencyMetadata(candidate: CompareCandidateResult): Record<string, unknown> {
+  return {
+    blindId: candidate.blindId,
+    status: candidate.status,
+    latencyMs: candidate.latencyMs,
+    registryKey: candidate.model.registryKey,
+    providerId: candidate.model.providerId,
+    modelId: candidate.model.modelId,
+    displayName: candidate.model.displayName,
+  };
+}
+
 export function comparisonArtifactText(input: {
   readonly comparison: StoredComparison;
   readonly prompt: string;
@@ -580,6 +592,7 @@ export async function saveComparisonArtifact(input: {
         ...(input.comparison.documentId ? { documentId: input.comparison.documentId } : {}),
         candidateCount: input.comparison.candidates.length,
         completedCandidates: input.comparison.candidates.filter((candidate) => candidate.status === 'completed').length,
+        candidateLatencyEvidence: input.comparison.candidates.map(toArtifactCandidateLatencyMetadata),
         ...(input.benchmarkKind ? { benchmarkKind: input.benchmarkKind } : {}),
         ...(input.comparison.taskType ? { taskType: input.comparison.taskType } : {}),
         revealStored: true,