@dsh-enhanced/assistant-growth-driver 0.1.64 → 0.1.66

package/lib/usage-runtime.js

@@ -1,6 +1,12 @@
+import { ScannerOwnerGuard, ScannerOwnerUnavailable, drainScannerFlights } from './scanner-owner-runtime.js';
 import { acceptanceDigest } from '@dsh-enhanced/task-acceptance-contract';
-import { SourceGrowthRunUnavailableError, isSourceOwnerContinuation, sourceGrowthEvidenceDigest, sourceGrowthRunDigest, validateSourceGrowthRunBinding } from '@dsh-enhanced/assistant-growth-contract';
-import { UsageStore } from './usage-store.js';
+import { SourceGrowthRunUnavailableError, isSourceOwnerContinuation, sourceGrowthEvidenceDigest, sourceGrowthRunDigest, validateSourceGrowthRunBinding, validateAnySourceGrowthRunBinding, anySourceGrowthRunDigest } from '@dsh-enhanced/assistant-growth-contract';
+import { UsageStore, isWorkItemUsageIntent } from './usage-store.js';
+import { freezeWorkItemData, ownData, isWorkItemCreationReady, workItemAuthorityDeadline, workItemTextDigest, workItemRunSource, workItemStableOwner } from './work-item-source.js';
+class WorkItemSourcePending extends Error {
+}
+class WorkItemSourceObsolete extends Error {
+}
 const OWNER = 'assistant-growth-usage';
 const EXECUTOR = 'assistant-growth-usage-v1';
 const CATALOG = acceptanceDigest({ executor: EXECUTOR, version: 1 });
@@ -17,6 +23,9 @@ export class UsageLearningRuntime {
     flights = new Set();
     unregister;
     unsubscribe;
+    ownerGuard;
+    unsubscribeWake;
+    initialized = false;
     active = false;
     scanning = false;
     lastError = null;
@@ -30,6 +39,10 @@ export class UsageLearningRuntime {
         if (typeof ports.evaluation.listTrustedTaskLearningProjections !== 'function'
             || typeof ports.evaluation.withTrustedCanonicalTaskWriterFence !== 'function'
             || typeof ports.evaluation.onTrustedTaskChange !== 'function'
+            || typeof ports.delivery.inspectOwnerRouteState !== 'function'
+            || typeof ports.automations.inspectSystemOwnedRetirement !== 'function'
+            || typeof ports.automations.retireSystemOwned !== 'function'
+            || typeof ports.automations.onSchedulerWake !== 'function'
             || typeof ports.delivery.inspectOwnerForegroundLearningTask !== 'function'
             || typeof ports.automations.registerHostExecutor !== 'function'
             || typeof ports.automations.inspectSystemOwnedActivation !== 'function') {
@@ -44,11 +57,22 @@ export class UsageLearningRuntime {
                 ...(allowRevision ? { allowRevision: true } : {}),
                 ...(allowModification === false ? { allowModification: false } : {}) } });
         this.scanId = `usage-scan-${this.lane}`;
+        this.ownerGuard = new ScannerOwnerGuard(OWNER, this.scanId, { authorityId: config.scope.ownerRouteId,
+            principalId: config.scope.principalId, workspace: config.scope.workspace, agentPreset: config.scope.preset }, ports.delivery, ports.automations);
     }
-    health = () => ({ enabled: true, connected: this.active, lastScanAt: this.lastScanAt,
+    health = () => ({ enabled: true, connected: this.active && !this.ownerGuard.retired, lastScanAt: this.lastScanAt,
         lastError: this.lastError, counts: this.store.counts(this.lane) });
     start() {
-        this.store.interrupt(this.lane);
+        let recoverNativeScanner = false;
+        try {
+            this.ownerGuard.check();
+        }
+        catch (error) {
+            this.lastError = String(error).slice(0, 200);
+            if (this.ownerGuard.retired)
+                return;
+            recoverNativeScanner = this.ownerGuard.canReconcileScanner;
+        }
         this.unregister = this.ports.automations.registerHostExecutor({
             descriptor: { executorId: EXECUTOR, contractVersion: 1, catalogDigest: CATALOG },
             accepts: spec => spec.executorId === EXECUTOR && spec.executorContractVersion === 1
@@ -61,31 +85,66 @@ export class UsageLearningRuntime {
             },
         });
         this.active = true;
+        this.unsubscribeWake = this.ports.automations.onSchedulerWake(() => {
+            if (!this.active || this.initialized || this.ownerGuard.retired)
+                return;
+            try {
+                this.initializeScanner();
+            }
+            catch (error) {
+                this.lastError = String(error).slice(0, 200);
+            }
+        });
         this.unsubscribe = this.ports.evaluation.onTrustedTaskChange(() => this.scan());
         // This persisted scan also discovers writes made by another Host process.
-        this.ports.automations.reconcileSystem({ owner: OWNER, automationId: this.scanId,
-            idempotencyKey: `${this.scanId}:${this.configDigest}`, desiredStatus: 'active', definition: this.definition() });
+        if (recoverNativeScanner) {
+            try {
+                this.ports.automations.reconcileSystem({ owner: OWNER, automationId: this.scanId,
+                    idempotencyKey: `${this.scanId}:${this.configDigest}`, desiredStatus: 'active', definition: this.definition() });
+            }
+            catch (error) {
+                this.lastError = String(error).slice(0, 200);
+            }
+        }
         this.scan();
     }
+    initializeScanner() {
+        const owner = this.owner();
+        if (!this.initialized) {
+            this.store.interrupt(this.lane);
+            this.ports.automations.reconcileSystem({ owner: OWNER, automationId: this.scanId,
+                idempotencyKey: `${this.scanId}:${this.configDigest}`, desiredStatus: 'active', definition: this.definition() });
+            this.initialized = true;
+        }
+        return owner;
+    }
     close() {
         return this.closing ??= (async () => {
             this.active = false;
+            this.unsubscribeWake?.();
             this.unsubscribe?.();
             this.unregister?.();
             this.abort.abort(new Error('usage learning provider disposed'));
-            await Promise.allSettled(this.flights);
-            this.store.close();
+            try {
+                await drainScannerFlights(this.flights);
+            }
+            finally {
+                this.store.close();
+            }
         })();
     }
     owner() {
         if (!this.active)
             throw new Error('usage learning unavailable');
+        this.ownerGuard.check();
         const scope = this.config.scope;
         return this.ports.delivery.validateOwnerRoute({ authorityId: scope.ownerRouteId, principalId: scope.principalId,
             workspace: scope.workspace, agentPreset: scope.preset });
     }
     source(job) {
         this.abort.signal.throwIfAborted();
+        if (isWorkItemUsageIntent(job.intent))
+            throw new Error('foreground usage source required');
         if (job.intent.configDigest !== this.configDigest || job.intent.expiresAt <= Date.now()
             || !isSourceOwnerContinuation(this.owner(), job.intent.source.owner))
             throw new Error('usage authority changed or expired');
@@ -107,12 +166,14 @@ export class UsageLearningRuntime {
             throw new SourceGrowthRunUnavailableError('usage runtime is temporarily unavailable');
         try {
             const job = this.store.get(request.runId);
-            if (!job || job.digest !== request.intentDigest || !['running', 'reviewed'].includes(job.state)
+            if (!job || isWorkItemUsageIntent(job.intent) || job.digest !== request.intentDigest || !['running', 'reviewed'].includes(job.state)
                 || !job.intent.modelOrigin || !job.intent.budget || !job.sourceRun
                 || job.definitionHash === null || job.occurrenceId === null)
                 return undefined;
             const source = this.source(job);
             const binding = job.sourceRun;
+            if (binding.protocol !== 'assistant-growth/source-run/v1')
+                return undefined;
             validateSourceGrowthRunBinding(binding);
             if (binding.creationAcceptance !== undefined) {
                 const current = this.ports.inspectCreationAcceptanceAuthority?.();
@@ -142,6 +203,8 @@ export class UsageLearningRuntime {
             return structuredClone(binding);
         }
         catch (error) {
+            if (error instanceof ScannerOwnerUnavailable && !this.ownerGuard.retired)
+                throw new SourceGrowthRunUnavailableError(error.message);
             const code = error instanceof Error ? error.code : undefined;
             if (code === 'SQLITE_BUSY' || code === 'SQLITE_LOCKED'
                 || code === 'ERR_SQLITE_ERROR' && error instanceof Error && /database (?:is )?(?:busy|locked)/iu.test(error.message)) {
@@ -150,20 +213,305 @@ export class UsageLearningRuntime {
             return undefined;
         }
     };
+    workItemScope(owner) {
+        return { authorityId: owner.authorityId, principalId: owner.principalId, workspace: owner.workspace, agentPreset: owner.agentPreset,
+            expectedOwner: { authorityHash: owner.authorityHash, principalRecordId: owner.principalRecordId, principalVersion: owner.principalVersion } };
+    }
+    assertWorkItemReadiness(owner, admission = true) {
+        const pins = this.config.usageLearning.workItemAuthorities;
+        const currentOwner = this.owner();
+        if (!isSourceOwnerContinuation(currentOwner, owner))
+            throw new WorkItemSourceObsolete('work item source owner changed');
+        if (!this.config.usageLearning.workItemFailures || !pins || !this.ports.reviewWorkItem
+            || this.ports.inspectWorkItemToolPreauthorization?.() !== true
+            || !isWorkItemCreationReady(this.ports.inspectWorkItemCreationReadiness?.({ owner: currentOwner }), pins, Date.now(), admission)) {
+            throw new WorkItemSourcePending('work item engineering peers or authorizations unavailable');
+        }
+    }
+    currentWorkItem(locator) {
+        if (locator.configDigest !== this.configDigest || locator.expiresAt <= Date.now()
+            || !same(workItemStableOwner(this.owner()), locator.owner))
+            throw new WorkItemSourceObsolete('work item usage authority changed or expired');
+        const get = this.ports.evaluation.getTrustedWorkItemLearningProjection;
+        if (typeof get !== 'function')
+            throw new WorkItemSourcePending('work item canonical reader unavailable');
+        const scope = this.ports.evaluation.canonicalHostScope({ workspace: locator.owner.workspace, preset: locator.owner.agentPreset });
+        const current = get.call(this.ports.evaluation, { scope, itemId: locator.itemId });
+        if (!current || current.projection.disposition !== 'upsert' || current.objective?.status !== 'not-achieved'
+            || current.objective.outcomeId !== locator.canonical.outcomeId || current.projection.version !== locator.canonical.version
+            || current.projection.digest !== locator.canonical.digest)
+            throw new WorkItemSourceObsolete('work item canonical source changed');
+    }
+    expectation(source) {
+        const task = source.task, outcome = task.canonical.objective;
+        return { ...this.workItemScope(task.owner), itemId: task.proofIdentity.itemId, outcomeId: outcome.outcomeId,
+            expectedSourceDigest: task.sourceDigest, expectedContentDigest: task.presentationDigest,
+            canonical: { version: task.canonical.projection.version, digest: task.canonical.projection.digest, objectiveStatus: 'not-achieved' },
+            expectedManifestDigest: source.manifest.manifestDigest, expectedObjectiveDigest: source.manifest.objective.fullTextDigest };
+    }
+    locatorFor(intent) {
+        const source = workItemRunSource(intent.source), owner = intent.source.task.owner;
+        return { protocol: 'assistant-growth/work-item-usage-locator/v1', configDigest: intent.configDigest,
+            owner: { authorityId: owner.authorityId, authorityHash: owner.authorityHash, principalId: owner.principalId,
+                principalRecordId: owner.principalRecordId, principalVersion: owner.principalVersion, workspace: owner.workspace, agentPreset: owner.agentPreset },
+            itemId: source.itemId, canonical: { outcomeId: source.outcomeId, version: source.projection.version,
+                digest: source.projection.digest, objectiveStatus: 'not-achieved' }, createdAt: intent.createdAt, expiresAt: intent.expiresAt };
+    }
+    withWorkItemSource(intent, callback) {
+        this.abort.signal.throwIfAborted();
+        this.currentWorkItem(this.locatorFor(intent));
+        if (!same(intent.authorities, this.config.usageLearning.workItemAuthorities))
+            throw new WorkItemSourceObsolete('work item authority pins changed');
+        const fence = this.ports.delivery.withOwnerWorkItemEngineeringContextFence;
+        if (!fence)
+            throw new WorkItemSourcePending('work item engineering fence unavailable');
+        return fence.call(this.ports.delivery, this.expectation(intent.source), source => {
+            this.abort.signal.throwIfAborted();
+            if (!this.active || intent.configDigest !== this.configDigest || Date.now() >= Math.min(intent.expiresAt, workItemAuthorityDeadline(intent.authorities)))
+                throw new WorkItemSourceObsolete('work item usage lifecycle or authority expired');
+            if (!same(workItemRunSource({ ...intent.source, ...source }), workItemRunSource(intent.source))
+                || !isSourceOwnerContinuation(source.task.owner, intent.source.task.owner)
+                || !same({ ...source.task, owner: intent.source.task.owner, canonical: intent.source.task.canonical }, intent.source.task)
+                || !same(source.manifest, intent.source.manifest) || source.objective !== intent.source.objective)
+                throw new WorkItemSourceObsolete('frozen work item engineering source changed');
+            return callback(source);
+        });
+    }
+    readWorkItem(locator) {
+        this.currentWorkItem(locator);
+        const inspect = this.ports.delivery.inspectOwnerWorkItemEngineeringContext, read = this.ports.delivery.readOwnerWorkItemEngineeringContext;
+        if (!inspect || !read)
+            throw new WorkItemSourcePending('work item engineering context reader unavailable');
+        const context = inspect.call(this.ports.delivery, { ...this.workItemScope(locator.owner), itemId: locator.itemId, outcomeId: locator.canonical.outcomeId });
+        if (!context)
+            throw new WorkItemSourcePending('complete work item context temporarily unreadable');
+        let shell = { protocol: 'assistant-delivery/work-item-engineering-context/v1', ...context, objective: '', parentReports: [] };
+        const expectation = this.expectation(shell);
+        const readAll = (selector, fullTextDigest, fullBytes) => {
+            if (!Number.isSafeInteger(fullBytes) || fullBytes < 1 || fullBytes > (selector.kind === 'objective' ? 16_384 : 65_536))
+                throw new WorkItemSourceObsolete('work item context exceeds complete input bound');
+            let offset = 0, text = '';
+            for (let pageNumber = 0; pageNumber < 32; pageNumber++) {
+                const page = read.call(this.ports.delivery, { ...expectation, selector, offset, maxBytes: 8192 });
+                if (!page || page.manifestDigest !== context.manifest.manifestDigest || page.fullTextDigest !== fullTextDigest
+                    || page.fullBytes !== fullBytes || page.offset !== offset || !page.text.isWellFormed()
+                    || page.returnedBytes !== Buffer.byteLength(page.text) || page.returnedBytes < 1)
+                    throw new WorkItemSourcePending('work item context pagination changed');
+                text += page.text;
+                offset += page.returnedBytes;
+                if (offset > fullBytes || page.nextOffset !== undefined && page.nextOffset !== offset)
+                    throw new WorkItemSourceObsolete('invalid work item context pagination');
+                if (page.nextOffset === undefined) {
+                    if (offset !== fullBytes || workItemTextDigest(text) !== fullTextDigest)
+                        throw new WorkItemSourceObsolete('work item context was not fully read');
+                    return text;
+                }
+            }
+            throw new WorkItemSourceObsolete('work item context pagination exceeds bound');
+        };
+        shell = { ...shell, objective: readAll({ kind: 'objective' }, context.manifest.objective.fullTextDigest, context.manifest.objective.fullBytes) };
+        let reportBytes = 0;
+        shell.parentReports = context.manifest.reports.map(report => {
+            reportBytes += report.fullBytes;
+            if (report.truncated || reportBytes > 262_144)
+                throw new WorkItemSourceObsolete('sealed background reports exceed bound');
+            return { itemId: report.itemId, revision: report.revision, fullTextDigest: report.fullTextDigest, fullBytes: report.fullBytes,
+                text: readAll({ kind: 'parent-report', itemId: report.itemId, revision: report.revision }, report.fullTextDigest, report.fullBytes) };
+        });
+        workItemRunSource(shell);
+        return freezeWorkItemData(shell);
+    }
+    scanWorkItems(owner, scope) {
+        for (let pageNumber = 0, stopped = false; pageNumber < 10 && !stopped; pageNumber++) {
+            const after = this.store.workItemCursor(this.lane);
+            const page = this.ports.evaluation.listTrustedTaskLearningProjections({ scope, ...(after ? { after } : {}), limit: 100 });
+            for (const item of page.items) {
+                const canonical = item.receipt, now = Date.now(), at = canonical.objective?.occurredAt ?? 0;
+                const workItem = canonical.projection.subjectKind === 'work-item';
+                const eligible = workItem && canonical.projection.disposition === 'upsert' && canonical.objective?.status === 'not-achieved'
+                    && at <= now && now - at < this.config.usageLearning.lookbackMs;
+                const locator = eligible ? { protocol: 'assistant-growth/work-item-usage-locator/v1',
+                    configDigest: this.configDigest, owner: { authorityId: owner.authorityId, authorityHash: owner.authorityHash,
+                        principalId: owner.principalId, principalRecordId: owner.principalRecordId, principalVersion: owner.principalVersion,
+                        workspace: owner.workspace, agentPreset: owner.agentPreset }, itemId: canonical.projection.subjectRef,
+                    canonical: { outcomeId: canonical.objective.outcomeId, version: canonical.projection.version,
+                        digest: canonical.projection.digest, objectiveStatus: 'not-achieved' }, createdAt: now, expiresAt: at + this.config.usageLearning.lookbackMs } : undefined;
+                const staged = this.ports.evaluation.withTrustedCanonicalTaskWriterFence({ scope, scopeWatermark: page.scopeWatermark,
+                    evidence: [canonical.projection] }, () => this.store.consumeWorkItem({ lane: this.lane, scopeKey: page.nextCursor.scopeKey,
+                    watermark: item.watermark, ...(workItem ? { itemId: canonical.projection.subjectRef } : {}),
+                    ...(locator ? { locator } : {}), maxPending: this.config.usageLearning.maxPending }));
+                if (!staged.matched || !staged.value) {
+                    stopped = true;
+                    break;
+                }
+            }
+            if (!page.hasMore)
+                break;
+        }
+        for (const pending of this.store.pendingWorkItems(this.lane)) {
+            try {
+                this.currentWorkItem(pending.locator);
+                const source = this.readWorkItem(pending.locator);
+                this.assertWorkItemReadiness(source.task.owner);
+                const fixed = this.config.provider !== null && this.config.model !== null;
+                const intent = { sourceKind: 'work-item', configDigest: this.configDigest, source,
+                    model: fixed ? { provider: this.config.provider, model: this.config.model, ...(this.config.reasoningEffort === null ? {} : { reasoningEffort: this.config.reasoningEffort }) }
+                        : structuredClone(source.task.proofIdentity.supplier), modelOrigin: fixed ? 'explicit-growth-override' : 'inherited-owner-task',
+                    budget: { budgetId: this.config.budgetId, amount: this.config.budgetAmount, maxModelCalls: this.config.maxModelCalls,
+                        maxToolCalls: this.config.maxToolCalls, maxOutputTokens: this.config.maxOutputTokens, maxDurationMs: this.config.maxDurationMs,
+                        maxPlansPerWake: this.config.pluginSourceProposals.maxPlansPerWake }, authorities: this.config.usageLearning.workItemAuthorities,
+                    createdAt: pending.locator.createdAt, expiresAt: pending.locator.expiresAt };
+                this.withWorkItemSource(intent, () => this.store.freezeWorkItem(pending.id, intent));
+            }
+            catch (error) {
+                if (error instanceof ScannerOwnerUnavailable)
+                    throw error;
+                if (error instanceof WorkItemSourceObsolete)
+                    this.store.abandonWorkItem(pending.id);
+                else if (!(error instanceof WorkItemSourcePending))
+                    this.lastError = String(error).slice(0, 200);
+            }
+        }
+    }
+    inspectAnySourceGrowthRun = (request) => {
+        if (!this.active)
+            throw new SourceGrowthRunUnavailableError('usage runtime temporarily unavailable');
+        const job = this.store.get(request.runId);
+        if (!job || !isWorkItemUsageIntent(job.intent))
+            return this.inspectSourceGrowthRun(request);
+        try {
+            if (job.digest !== request.intentDigest || !['running', 'reviewed'].includes(job.state) || !job.sourceRun
+                || job.sourceRun.protocol !== 'assistant-growth/source-run/v2')
+                return undefined;
+            this.assertWorkItemReadiness(job.intent.source.task.owner, false);
+            return this.withWorkItemSource(job.intent, () => this.store.withWorkItemRunWriter(request, current => {
+                if (!current.sourceRun || current.sourceRun.protocol !== 'assistant-growth/source-run/v2')
+                    throw new Error('work item run absent');
+                this.assertWorkItemBinding(current, current.sourceRun);
+                return freezeWorkItemData(current.sourceRun);
+            }));
+        }
+        catch (error) {
+            if (error instanceof WorkItemSourcePending || error instanceof ScannerOwnerUnavailable)
+                throw new SourceGrowthRunUnavailableError(error.message);
+            return undefined;
+        }
+    };
+    withWorkItemRunFence = (input, callback) => {
+        if (!this.active)
+            throw new SourceGrowthRunUnavailableError('usage runtime temporarily unavailable');
+        input = ownData(input);
+        if (Object.keys(input).sort().join(',') !== 'expectedGrowthRunDigest,intentDigest,runId' || typeof callback !== 'function'
+            || typeof input.runId !== 'string' || !input.runId || input.runId.length > 500
+            || typeof input.intentDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(input.intentDigest)
+            || typeof input.expectedGrowthRunDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(input.expectedGrowthRunDigest))
+            throw new Error('invalid work item run fence input');
+        const job = this.store.get(input.runId);
+        if (!job || job.digest !== input.intentDigest || !isWorkItemUsageIntent(job.intent))
+            throw new Error('work item run not found');
+        const intent = job.intent;
+        this.assertWorkItemReadiness(intent.source.task.owner, false);
+        return this.withWorkItemSource(intent, () => this.store.withWorkItemRunWriter(input, current => {
+            const binding = current.sourceRun;
+            if (!binding || binding.protocol !== 'assistant-growth/source-run/v2' || anySourceGrowthRunDigest(binding) !== input.expectedGrowthRunDigest
+                || binding.configDigest !== this.configDigest || !same(binding.authorities, this.config.usageLearning.workItemAuthorities)
+                || !same(binding.source, workItemRunSource(intent.source)))
+                throw new Error('work item run binding changed');
+            this.assertWorkItemBinding(current, binding);
+            return callback(freezeWorkItemData(binding));
+        }));
+    };
+    assertWorkItemBinding(job, binding) {
+        validateAnySourceGrowthRunBinding(binding);
+        if (!isWorkItemUsageIntent(job.intent) || binding.runId !== job.id || binding.intentDigest !== job.digest
+            || binding.configDigest !== this.configDigest || binding.ownerDigest !== sourceGrowthEvidenceDigest(job.intent.source.task.owner)
+            || binding.native.automationId !== job.id || binding.native.definitionHash !== job.definitionHash || binding.native.occurrenceId !== job.occurrenceId
+            || !same(binding.source, workItemRunSource(job.intent.source)) || !same(binding.model, job.intent.model)
+            || binding.modelOrigin !== job.intent.modelOrigin || !same(binding.budget, job.intent.budget)
+            || !same(binding.authorities, job.intent.authorities) || binding.expiresAt !== job.intent.expiresAt)
+            throw new Error('work item persisted run differs from frozen job');
+    }
+    async executeWorkItem(input, queued, result) {
+        if (!isWorkItemUsageIntent(queued.intent))
+            throw new Error('work item usage expected');
+        const intent = queued.intent;
+        let claimed = false;
+        try {
+            this.assertWorkItemReadiness(intent.source.task.owner);
+            this.withWorkItemSource(intent, () => { this.store.claim(queued.id, input.definitionHash, input.occurrenceId); claimed = true; });
+            const signal = AbortSignal.any([input.signal, this.abort.signal, AbortSignal.timeout(Math.max(1, Math.min(this.config.maxDurationMs, intent.expiresAt - Date.now(), workItemAuthorityDeadline(intent.authorities) - Date.now())))]);
+            const assertCurrent = () => {
+                signal.throwIfAborted();
+                // Peer/owner probes can synchronously change source state. Run them
+                // before the final complete source frame; its callback is local only.
+                this.assertWorkItemReadiness(intent.source.task.owner, false);
+                this.withWorkItemSource(intent, () => {
+                    signal.throwIfAborted();
+                    const current = this.store.get(queued.id);
+                    if (current?.state !== 'running' || current.occurrenceId !== input.occurrenceId
+                        || current.digest !== queued.digest)
+                        throw new Error('work item usage no longer owns dispatch');
+                });
+            };
+            const bindSourceRun = actual => {
+                assertCurrent();
+                this.assertWorkItemReadiness(intent.source.task.owner);
+                if (!same(actual.model, intent.model) || !same(actual.creationAcceptance, intent.authorities.creationAcceptance)
+                    || actual.revisionAcceptance !== undefined || actual.revisionRegressionAcceptance !== undefined
+                    || actual.generationDeadlineAt > workItemAuthorityDeadline(intent.authorities))
+                    throw new Error('work item run setup authority changed');
+                const binding = { protocol: 'assistant-growth/source-run/v2', mode: 'create',
+                    runId: queued.id, intentDigest: queued.digest, configDigest: intent.configDigest, ownerDigest: sourceGrowthEvidenceDigest(intent.source.task.owner),
+                    source: workItemRunSource(intent.source), model: actual.model, modelOrigin: intent.modelOrigin, budget: intent.budget,
+                    creationAcceptance: structuredClone(intent.authorities.creationAcceptance), authorities: structuredClone(intent.authorities),
+                    native: { owner: OWNER, automationId: queued.id, definitionHash: input.definitionHash, occurrenceId: input.occurrenceId },
+                    sessionId: actual.sessionId, toolContractDigest: actual.toolContractDigest, executionContractDigest: actual.executionContractDigest,
+                    createdAt: actual.createdAt, generationDeadlineAt: actual.generationDeadlineAt, expiresAt: intent.expiresAt };
+                return this.withWorkItemSource(intent, () => this.store.bindWorkItemSourceRun(queued.id, queued.digest, input.definitionHash, input.occurrenceId, binding));
+            };
+            this.assertWorkItemReadiness(intent.source.task.owner);
+            assertCurrent();
+            const outcome = await this.ports.reviewWorkItem({ sourceKind: 'work-item', id: queued.id, intentDigest: queued.digest,
+                definitionHash: input.definitionHash, occurrenceId: input.occurrenceId, expiresAt: Math.min(intent.expiresAt, workItemAuthorityDeadline(intent.authorities)),
+                model: intent.model, source: intent.source, signal, assertCurrent, assertFirstModelAdmission: () => { this.assertWorkItemReadiness(intent.source.task.owner); assertCurrent(); }, bindSourceRun });
+            assertCurrent();
+            this.store.settle(queued.id, outcome, outcome === 'reviewed' ? 'review-complete-not-adopted' : 'review-incomplete', input.occurrenceId);
+            return result(outcome === 'reviewed' ? 'succeeded' : outcome);
+        }
+        catch {
+            if (claimed)
+                this.store.settle(queued.id, 'unknown', 'interrupted-after-dispatch', input.occurrenceId);
+            return result(claimed ? 'unknown' : 'failed');
+        }
+    }
     /** Synchronous nudge, bounded to 1000 heads. Native scan resumes the cursor. */
     scan = () => {
         if (!this.active || this.scanning)
             return;
         this.scanning = true;
         try {
-            const owner = this.owner();
+            const owner = this.initializeScanner();
             for (const job of this.store.pending(this.lane))
                 if (job.state === 'queued') {
                     try {
-                        this.source(job);
-                        this.schedule(job);
+                        if (isWorkItemUsageIntent(job.intent)) {
+                            this.withWorkItemSource(job.intent, () => undefined);
+                            this.schedule(job);
+                        }
+                        else {
+                            this.source(job);
+                            this.schedule(job);
+                        }
                     }
-                    catch {
+                    catch (error) {
+                        if (isWorkItemUsageIntent(job.intent)) {
+                            if (error instanceof WorkItemSourceObsolete)
+                                this.store.settle(job.id, 'superseded', error.message);
+                            continue;
+                        }
+                        ;
+                        if (error instanceof ScannerOwnerUnavailable)
+                            throw error;
                         this.store.settle(job.id, 'failed', 'queued-source-or-schedule-unavailable');
                     }
                 }
@@ -211,12 +559,27 @@ export class UsageLearningRuntime {
                 if (!page.hasMore)
                     break;
             }
+            if (this.config.usageLearning.workItemFailures)
+                this.scanWorkItems(owner, scope);
             for (const job of this.store.pending(this.lane))
                 if (job.state === 'queued') {
+                    if (isWorkItemUsageIntent(job.intent)) {
+                        try {
+                            this.schedule(job);
+                        }
+                        catch (error) {
+                            if (error instanceof WorkItemSourceObsolete)
+                                this.store.settle(job.id, 'superseded', error.message);
+                        }
+                        ;
+                        continue;
+                    }
                     try {
                         this.schedule(job);
                     }
-                    catch {
+                    catch (error) {
+                        if (error instanceof ScannerOwnerUnavailable)
+                            throw error;
                         this.store.settle(job.id, 'failed', 'schedule-rejected');
                     }
                 }
@@ -246,7 +609,12 @@ export class UsageLearningRuntime {
     }
     schedule(input) {
         let job = input;
-        this.source(job);
+        if (isWorkItemUsageIntent(job.intent)) {
+            this.assertWorkItemReadiness(job.intent.source.task.owner);
+            this.withWorkItemSource(job.intent, () => undefined);
+        }
+        else
+            this.source(job);
         const definition = this.definition(job);
         if (job.definitionHash === null) {
             this.ports.automations.reconcileSystem({ owner: OWNER, automationId: job.id,
@@ -264,6 +632,10 @@ export class UsageLearningRuntime {
             this.store.settle(job.id, 'failed', 'native-run-ended-before-claim');
             return;
         }
+        if (isWorkItemUsageIntent(job.intent)) {
+            this.assertWorkItemReadiness(job.intent.source.task.owner);
+            this.withWorkItemSource(job.intent, () => undefined);
+        }
         this.ports.automations.reconcileSystem({ owner: OWNER, automationId: job.id,
             idempotencyKey: `${job.id}:activate`, desiredStatus: 'active', definition });
     }
@@ -290,9 +662,13 @@ export class UsageLearningRuntime {
             const queued = this.store.get(input.automationId);
             if (!queued || queued.state !== 'queued' || queued.digest !== input.activationNonce || queued.definitionHash !== input.definitionHash)
                 throw new Error('usage review is not queued');
+            if (isWorkItemUsageIntent(queued.intent))
+                return await this.executeWorkItem(input, queued, result);
             this.source(queued);
             claimed = this.store.claim(queued.id, input.definitionHash, input.occurrenceId);
             const job = claimed;
+            if (isWorkItemUsageIntent(job.intent))
+                throw new Error('foreground usage claim required');
             const signal = AbortSignal.any([input.signal, this.abort.signal,
                 AbortSignal.timeout(Math.max(1, Math.min(this.config.maxDurationMs, job.intent.expiresAt - Date.now())))]);
             const assertCurrent = () => {