@sema-agent/client-core 0.112.1 → 0.113.0

package/dist/hooksWireCaps.js

@@ -1,15 +1,16 @@
-import { engineCapNestedTrue, engineCapState, engineCapString, engineCapValue } from './engineCapsCache.js';
-import { hooksReaderNotReadKeys } from './hooksReaderGenerations.js';
+import { engineCapNestedTrue, engineCapNestedValue, engineCapState, engineCapString, engineCapValue } from './engineCapsCache.js';
+import { compareReleaseVersions } from './supportFloor.js';
+import { hooksEntryKeyReaderOf } from './hooksReaderGenerations.js';
 import { msg, renderMessage } from './i18n/translate.js';
 import { capForDisplay } from './fleetTaskDesc.js';
 import { hostLog } from './host.js';
 import { faultText } from './hostCallbackGuard.js';
-import { HostSettingsSourceShapeError, MANAGED_READING_DISPOSITIONS, mergedBooleanOf, nonManagedLayerDown, readHostSettingsOnce } from './hostSettingsSource.js';
+import { HostSettingsSourceShapeError, MANAGED_READING_DISPOSITIONS, mergedBooleanOf, nonManagedLayersDown, readHostSettingsOnce } from './hostSettingsSource.js';
 import { admittedLayers, layerAdmissionWord } from './settingsLayerAdmission.js';
 import { guardedRead, readOwnDataValue } from './ownKey.js';
-import { HOOK_SETTINGS_SOURCE_TEXT, hooksSalvageMaskOf, salvageSettingsHooksEntries, settingsHooksSalvageNotice } from './settingsHooksSalvage.js';
+import { HOOK_SETTINGS_SOURCE_TEXT, hooksSalvageMaskOf, isGuardHookEvent, salvageSettingsHooksEntries, settingsHooksSalvageNotice } from './settingsHooksSalvage.js';
 import { submissionOriginOf } from './request/submissionIdentity.js';
-import { createSettingsHookJudge, decidePluginHooks, decideSessionHooks, dedupeSettingsHookGroups, filterSettingsHookGroups, hooksWirePlanShapeOf, hookEntryTypeWordOf, isEngineFiredHookEvent, occupancyOf, } from './pluginHooksWire.js';
+import { createSettingsHookJudge, decidePluginHooks, decideSessionHooks, dedupeSettingsHookGroups, filterSettingsHookGroups, hooksWirePlanShapeOf, hookEntryTypeWordOf, isEngineFiredHookEvent, SUPPORT_FLOOR_SETTINGS_CONTRACT, occupancyOf, } from './pluginHooksWire.js';
 import { MAX_HOOK_NOTICE_TEXT_CHARS } from './notifications.js';
 import { applyHttpHookPolicy, httpHookAdmittedSources, readHttpHookPolicy, wireHasHttpEntry } from './httpHookPolicy.js';
 import { goalStopHookMatcher, __resetGoalStopHookForTests } from './goalStopHook.js';
@@ -164,12 +165,15 @@ export function hooksWirePlan(opts) {
     for (const line of read.debug)
         hostLog('debug', line);
     const owned = o.engineOwnedByThisShell;
+    const reader = hooksEntryKeyReaderOf(engineCapValue(o.baseUrl, 'settingsContract'), engineCapString(o.baseUrl, 'version'));
     const engine = {
         ownedByThisShell: owned === true ? true : owned === false ? false : null,
         pluginHooksCapable: engineCapState(o.baseUrl, 'taskSettings') === 'unprobed'
             ? null
             : engineCapNestedTrue(o.baseUrl, 'taskSettings', 'pluginHooks'),
         hooksCapable: taskHooksCapability(o.baseUrl),
+        settingsContract: peerSettingsContractOf(o.baseUrl),
+        hookEntryFields: reader.fields,
     };
     const shellEvents = new Set();
     if (Array.isArray(o.shellHookEvents)) {
@@ -186,8 +190,19 @@ export function hooksWirePlan(opts) {
         const types = typesByEvent.get(event);
         return types === undefined || (typeof type === 'string' && types.has(type));
     };
-    const readerNotRead = hooksReaderNotReadKeys(engineCapString(o.baseUrl, 'version'));
-    return buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUserOf(o), suppressedLocallyOf(o), readerNotRead, compactionOnShellOf(o));
+    return buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUserOf(o), suppressedLocallyOf(o), reader, compactionOnShellOf(o));
+}
+function peerSettingsContractOf(baseUrl) {
+    const floor = (basis) => basis === 'absent' ? SUPPORT_FLOOR_SETTINGS_CONTRACT : Object.freeze({ version: SUPPORT_FLOOR_SETTINGS_CONTRACT.version, basis });
+    const group = engineCapValue(baseUrl, 'settingsContract');
+    if (group.kind === 'unobserved' || group.kind === 'not_reported')
+        return floor('absent');
+    if (group.kind !== 'value' || typeof group.value !== 'object' || group.value === null || Array.isArray(group.value))
+        return floor('unreadable');
+    const v = engineCapNestedValue(baseUrl, 'settingsContract', 'version');
+    if (v.kind !== 'value' || typeof v.value !== 'string' || compareReleaseVersions(v.value, v.value) === undefined)
+        return floor('unreadable');
+    return Object.freeze({ version: v.value, basis: 'reported' });
 }
 function taskHooksCapability(baseUrl) {
     const v = engineCapValue(baseUrl, 'taskSettings');
@@ -300,7 +315,7 @@ function withheldRowsOf(candidates, trust, layers) {
     }
     return rows;
 }
-function closedDropRowsOf(source, doc, reason) {
+function layerDropRowsOf(source, doc, reason) {
     const rows = [];
     try {
         const hooks = readOwnDataValue(doc, 'hooks');
@@ -317,7 +332,7 @@ function closedDropRowsOf(source, doc, reason) {
                 if (!Array.isArray(entries))
                     return;
                 entries.forEach((entry, hookIndex) => {
-                    rows.push({ source, event, groupIndex, hookIndex, ...hookEntryTypeWordOf(entry), reason, notRun: true });
+                    rows.push({ source, event, groupIndex, hookIndex, ...hookEntryTypeWordOf(entry), reason, notRun: true, guard: isGuardHookEvent(event) });
                 });
             });
         }
@@ -326,7 +341,7 @@ function closedDropRowsOf(source, doc, reason) {
     }
     return rows;
 }
-function buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUser, suppressedLocally, readerNotRead, compactionOnShell = false) {
+function buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUser, suppressedLocally, reader, compactionOnShell = false) {
     const settingsDropped = [];
     const settingsVerdicts = [];
     const settingsExcluded = [];
@@ -360,7 +375,7 @@ function buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUser, suppr
     const closedPlan = (reason) => {
         closedBy = reason;
         for (const source of ALL_HOOK_SOURCES)
-            settingsDropped.push(...closedDropRowsOf(source, read.layers[source].doc, reason));
+            settingsDropped.push(...layerDropRowsOf(source, read.layers[source].doc, reason));
         sessionReader = read.sessionHooks.state;
         const pr = read.plugins;
         if (pr.reading === undefined)
@@ -374,7 +389,7 @@ function buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUser, suppr
             shellRuns,
             promptAuthoredByUser,
             occupied: new Map(),
-            readerNotRead,
+            reader,
         }));
         if (d === undefined)
             return planOf('failed', undefined);
@@ -436,7 +451,9 @@ function buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUser, suppr
     if (managedReading.hooksRestriction === 'withhold') {
         hostLog('debug', `hooksWireCaps: managed policy layer reported ${read.managed} — only policySettings hooks projected to the engine`);
     }
-    const mergedDisable = () => mergedBooleanOf(read, 'disableAllHooks') === true || (read.current !== undefined && mergedBooleanOf(read.current, 'disableAllHooks') === true) || nonManagedLayerDown(read);
+    const explicitMergedDisable = () => mergedBooleanOf(read, 'disableAllHooks') === true || (read.current !== undefined && mergedBooleanOf(read.current, 'disableAllHooks') === true);
+    const layersDown = nonManagedLayersDown(read);
+    const mergedDisable = () => explicitMergedDisable() || layersDown.length > 0;
     const disabledByNonManaged = !managedByPolicy && mergedDisable();
     if (disabledByNonManaged) {
         hostLog('debug', 'hooksWireCaps: disableAllHooks (merged, non-managed) — only policySettings hooks projected to the engine');
@@ -479,6 +496,14 @@ function buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUser, suppr
     const notAdmitted = ALL_HOOK_SOURCES.filter((s) => !hookAdmitted.includes(s) && read.layers[s].doc !== null);
     if (sources === hookAdmitted)
         settingsWithheldNow = Object.freeze(withheldRowsOf(notAdmitted, read.trust, read.layers));
+    if (disabledByNonManaged && startupMode === undefined && !explicitMergedDisable() && layersDown.length > 0) {
+        settingsWithheldNow = Object.freeze(layersDown.map((source) => Object.freeze({ source, cause: 'layer_degraded', notice: renderMessage(msg('config.hooks.layerWithheld.degraded', { layer: HOOK_SETTINGS_SOURCE_TEXT[source] })) })));
+        for (const source of hookAdmitted) {
+            if (source === 'policySettings' || layersDown.includes(source))
+                continue;
+            settingsDropped.push(...layerDropRowsOf(source, read.layers[source].doc, 'layer_degraded'));
+        }
+    }
     if (sources !== hookAdmitted ? false : notAdmitted.length > 0) {
         hostLog('debug', `hooksWireCaps: workspace trust reading ${read.trust} — hooks from ${notAdmitted.join(', ')} are not admitted (repository-controlled layers need an accepted workspace)`);
     }
@@ -496,11 +521,11 @@ function buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUser, suppr
                 continue;
             if (!Array.isArray(groups) || groups.length === 0)
                 continue;
-            const kept = filterSettingsHookGroups(source, event, groups, engine.pluginHooksCapable === true, (type) => shellRuns(event, type), judge, readerNotRead, layer.mask);
+            const kept = filterSettingsHookGroups(source, event, groups, engine.pluginHooksCapable === true, (type) => shellRuns(event, type), judge, reader, engine.settingsContract, layer.mask);
             settingsDropped.push(...kept.drops);
             settingsVerdicts.push(...kept.verdicts);
             settingsExcluded.push(...kept.excluded);
-            if (!isEngineFiredHookEvent(event))
+            if (!isEngineFiredHookEvent(event, engine.settingsContract))
                 continue;
             settingsStripped += kept.stripped;
             if (kept.groups.length === 0)
@@ -520,7 +545,7 @@ function buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUser, suppr
         merged[event] = d.groups;
         settingsDeduped += d.removed;
     }
-    const goalMatcher = goalStopHookMatcher(managedOnly);
+    const goalMatcher = isEngineFiredHookEvent('Stop', engine.settingsContract) ? goalStopHookMatcher(managedOnly) : null;
     if (goalMatcher !== null) {
         merged['Stop'] = [...(merged['Stop'] ?? []), goalMatcher];
     }
@@ -530,7 +555,7 @@ function buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUser, suppr
     }
     if (settingsDeduped > 0) {
         hostLog('debug', `hooksWireCaps: ${settingsDeduped} settings hook entr${settingsDeduped === 1 ? 'y appears' : 'ies appear'} more than once ` +
-            '(same event, matcher group and hook) — sent once, at the first position, with the fields of the highest-precedence source');
+            '(same event, matcher group and identical hook content) — sent once, at the first position');
     }
     if (settingsStripped > 0) {
         hostLog('debug', `hooksWireCaps: ${settingsStripped} settings hook entr${settingsStripped === 1 ? 'y' : 'ies'} carried a plugin key — ` +
@@ -564,7 +589,7 @@ function buildHooksWirePlan(read, engine, shellRuns, promptAuthoredByUser, suppr
             promptAuthoredByUser,
             occupied,
             ...(suppressedLocally !== undefined ? { suppressedLocally } : {}),
-            readerNotRead,
+            reader,
         });
     });
     if (d === undefined)

package/dist/hostSettingsSource.d.ts

@@ -73,7 +73,7 @@ export declare function mergedBooleanOf(read: HostSettingsRead, key: string): bo
 export declare const CC_MERGE_ORDER: readonly ["userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings"];
 export type TightenOnlyHostSettingsLayer = Exclude<HostSettingsLayer, (typeof CC_MERGE_ORDER)[number]>;
 export declare const TIGHTEN_ONLY_HOST_SETTINGS_LAYERS: readonly TightenOnlyHostSettingsLayer[];
-export declare function nonManagedLayerDown(read: HostSettingsRead): boolean;
+export declare function nonManagedLayersDown(read: HostSettingsRead): readonly (typeof CC_MERGE_ORDER)[number][];
 export declare const ADOPTED_LAYERS: readonly ["userSettings", "projectSettings", "localSettings", "flagSettings"];
 export type AdoptedLayer = (typeof ADOPTED_LAYERS)[number];
 export interface HostLayerRule {

package/dist/hostSettingsSource.js

@@ -395,8 +395,8 @@ export function mergedBooleanOf(read, key) {
 }
 export const CC_MERGE_ORDER = Object.freeze(['userSettings', 'projectSettings', 'localSettings', 'flagSettings', 'policySettings']);
 export const TIGHTEN_ONLY_HOST_SETTINGS_LAYERS = Object.freeze(HOST_SETTINGS_LAYERS.filter((l) => !CC_MERGE_ORDER.includes(l)));
-export function nonManagedLayerDown(read) {
-    return CC_MERGE_ORDER.some((l) => {
+export function nonManagedLayersDown(read) {
+    return CC_MERGE_ORDER.filter((l) => {
         if (l === 'policySettings')
             return false;
         const snap = read.layers[l];

package/dist/hostTurnSettings.d.ts

@@ -3,7 +3,7 @@ import type { WireHooksConfig } from './finalVerifyWire.js';
 import type { memoryOffDeclared as MemoryOffDeclared } from './request/taskRequest.js';
 import type { EnvLike } from './hostEnv.js';
 import { type SettingsDocument } from './host.js';
-import { type HooksWirePlan, type HooksWirePlanOptions } from './pluginHooksWire.js';
+import { type HooksWirePlan, type HooksWirePlanOptions, type HooksWireSettingsContract } from './pluginHooksWire.js';
 import { type HostSettingsLayer, type HostSettingsSession, type HostSettingsSource } from './hostSettingsSource.js';
 import { type SubmissionIdentity } from './request/submissionIdentity.js';
 import { type WebSearchApiKeyFor } from './webSearchWireCaps.js';
@@ -114,7 +114,7 @@ export interface HostSettingsHeld {
     };
     readonly version: string;
 }
-export declare function hookEnvNamesOf(hooks: unknown): readonly string[];
+export declare function hookEnvNamesOf(hooks: unknown, contract: HooksWireSettingsContract | undefined): readonly string[];
 export interface HostTurnSettingsJudges {
     readonly materialize: HostResolvedMaterializer;
     readonly memoryOffDeclared: typeof MemoryOffDeclared;

package/dist/hostTurnSettings.js

@@ -1,6 +1,6 @@
 import { SETTINGS_CLASSIFY_HOOKS_CONFIG } from './generated/settingsSchemaFns.js';
 import { hostLog } from './host.js';
-import { isEngineFiredHookEvent } from './pluginHooksWire.js';
+import { engineLaneOf, planSettingsContractOf } from './pluginHooksWire.js';
 import { layerNotAppliedRefusesTurn, salvageSettingsHooksEntries } from './settingsHooksSalvage.js';
 import { ADOPTED_LAYERS, HOST_SETTINGS_LAYERS, HostSettingsSourceShapeError, TIGHTEN_ONLY_HOST_SETTINGS_LAYERS, permissionBucketOf, permissionRulesOf, MANAGED_READING_DISPOSITIONS, adoptHostSettingsRead, mintHostSettingsSession, readHostSettingsOnce, remintSameContent, sessionSnapshotOf, settingsValueOf, sourceOfRead, } from './hostSettingsSource.js';
 import { hooksWirePlan } from './hooksWireCaps.js';
@@ -14,7 +14,7 @@ import { assemblyRefusalOf } from './wireFailureShape.js';
 import { permissionRuleLayersOn } from './permissionsAllowGrantCapability.js';
 import { layerAdmissionReading, layerAdmitted } from './settingsLayerAdmission.js';
 import { SETTINGS_BUILD_LAYER_PARTS_UNREAD_NOTICE } from './generated/settingsSchemaFns.js';
-import { appendOwnElement, ownDataField, readOwnDataValue } from './ownKey.js';
+import { appendOwnElement, ownDataField, readOwnDataValue, sameJson } from './ownKey.js';
 export const HOST_SUPPLIED_KEYS = Object.freeze(['settings.hooks', 'settings.resolved', 'settings.webSearch', 'settings.outputStyle', 'memory', 'fileHistory', 'settings.env']);
 export const HOST_SETTING_CAUSES = Object.freeze([
     'carried',
@@ -219,12 +219,14 @@ function ownElementsOf(v) {
         appendOwnElement(out, readOwnDataValue(v, String(i)));
     return out;
 }
-export function hookEnvNamesOf(hooks) {
+export function hookEnvNamesOf(hooks, contract) {
     const out = [];
     if (!isRecordShape(hooks))
         return out;
+    let engineEvent;
     for (const event of Object.keys(hooks)) {
-        if (!isEngineFiredHookEvent(event))
+        engineEvent ??= engineLaneOf(contract);
+        if (!engineEvent(event))
             continue;
         for (const group of ownElementsOf(readOwnDataValue(hooks, event))) {
             if (!isRecordShape(group))
@@ -241,6 +243,9 @@ export function hookEnvNamesOf(hooks) {
     }
     return out;
 }
+function objectOrUndefined(v) {
+    return typeof v === 'object' && v !== null ? v : undefined;
+}
 function hookEnvLayerOf(names, env) {
     const layer = {};
     let n = 0;
@@ -253,7 +258,7 @@ function hookEnvLayerOf(names, env) {
     }
     return n > 0 ? freeze(layer) : undefined;
 }
-function hookEnvConsistent(env, hooks) {
+function hookEnvConsistent(env, hooks, contract) {
     if (env === undefined)
         return true;
     try {
@@ -262,14 +267,14 @@ function hookEnvConsistent(env, hooks) {
         const keys = Reflect.ownKeys(env);
         if (keys.length === 0)
             return false;
-        const names = hookEnvNamesOf(hooks);
+        const names = hookEnvNamesOf(hooks, contract);
         return keys.every((k) => typeof k === 'string' && names.includes(k) && typeof readOwnDataValue(env, k) === 'string');
     }
     catch {
         return false;
     }
 }
-function envArm(src, hooksCarried) {
+function envArm(src, hooksCarried, contract) {
     const key = 'settings.env';
     if (src.kind === 'missing')
         return missingArm(key);
@@ -293,7 +298,7 @@ function envArm(src, hooksCarried) {
         throw badSource(key, '{ env } where env is the environment record');
     let layer;
     try {
-        layer = hookEnvLayerOf(hookEnvNamesOf(hooksCarried), env);
+        layer = hookEnvLayerOf(hookEnvNamesOf(hooksCarried, contract), env);
     }
     catch {
         return unreadableArm(key);
@@ -864,7 +869,7 @@ export function buildHostTurnSettings(input, judges) {
     }
     const hooksFinal = armsByKey[0];
     const hooksToCarry = hooksFinal.row.disposition === 'carry' || hooksFinal.row.disposition === 'carry_partial' || hooksFinal.row.disposition === 'hold_for_consent' ? hooksFinal.carried : undefined;
-    const env = envArm(envSource, hooksToCarry);
+    const env = envArm(envSource, hooksToCarry, planSettingsContractOf(hooks.plan));
     const arms = [...armsByKey, env];
     const rows = freeze(arms.map((a) => a.row));
     const resolvedOut = arms[1]?.row.disposition === 'carry' || arms[1]?.row.disposition === 'carry_partial' || arms[1]?.row.disposition === 'hold_for_consent' ? resolvedCarried : undefined;
@@ -1089,7 +1094,7 @@ export function hostTurnSettingsOf(v, depth = 'full') {
             return undefined;
         if (Object.hasOwn(carried, 'hooks') && carried.hooks !== undefined && !hooksPassJudge(carried.hooks))
             return undefined;
-        if (!hookEnvConsistent(Object.hasOwn(carried, 'env') ? carried.env : undefined, Object.hasOwn(carried, 'hooks') ? carried.hooks : undefined))
+        if (!hookEnvConsistent(Object.hasOwn(carried, 'env') ? carried.env : undefined, Object.hasOwn(carried, 'hooks') ? carried.hooks : undefined, planSettingsContractOf(objectOrUndefined(readOwnDataValue(shaped, 'hooks')))))
             return undefined;
         return shaped;
     }
@@ -1101,22 +1106,6 @@ function wireFormOf(v) {
     const text = JSON.stringify(v);
     return text === undefined ? undefined : JSON.parse(text);
 }
-function sameJson(a, b) {
-    if (a === b)
-        return true;
-    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
-        return false;
-    if (Array.isArray(a) !== Array.isArray(b))
-        return false;
-    if (Array.isArray(a) && Array.isArray(b))
-        return a.length === b.length && a.every((x, i) => sameJson(x, b[i]));
-    const ra = a;
-    const rb = b;
-    const ka = Object.keys(ra);
-    if (ka.length !== Object.keys(rb).length)
-        return false;
-    return ka.every((k) => Object.hasOwn(rb, k) && sameJson(ra[k], rb[k]));
-}
 function groupHead(g) {
     if (!isRecordShape(g))
         return undefined;
@@ -1126,6 +1115,26 @@ function groupHead(g) {
             head[k] = g[k];
     return head;
 }
+function httpAllowedEnvNames(entry) {
+    if (!isRecordShape(entry) || !Object.hasOwn(entry, 'type') || entry.type !== 'http')
+        return undefined;
+    if (!Object.hasOwn(entry, 'allowedEnvVars'))
+        return undefined;
+    const names = entry.allowedEnvVars;
+    return Array.isArray(names) && names.every((n) => typeof n === 'string') ? names : undefined;
+}
+function withoutAllowedEnvVars(entry) {
+    return Object.fromEntries(Object.entries(entry).filter(([k]) => k !== 'allowedEnvVars'));
+}
+function isSubsetWitness(entry, witness) {
+    if (!isRecordShape(entry) || !isRecordShape(witness))
+        return false;
+    const want = httpAllowedEnvNames(entry);
+    const have = httpAllowedEnvNames(witness);
+    if (want === undefined || have === undefined)
+        return false;
+    return want.every((n) => have.includes(n)) && sameJson(withoutAllowedEnvVars(entry), withoutAllowedEnvVars(witness));
+}
 export function intersectHostHooks(sent, now) {
     try {
         return intersectHostHooksUnguarded(sent, now);
@@ -1156,38 +1165,68 @@ function intersectHostHooksUnguarded(sentIn, nowIn) {
         return { hooks: undefined, dropped: 0, judged: true };
     if (!isRecordShape(now))
         return { hooks: undefined, dropped: total, judged: true };
-    const out = {};
-    let kept = 0;
-    for (const ev of Object.keys(sent)) {
-        const groups = sent[ev];
-        const nowGroups = now[ev];
+    const events = [];
+    for (const event of Object.keys(sent)) {
+        const groups = sent[event];
+        const nowGroups = now[event];
         if (!Array.isArray(groups) || !Array.isArray(nowGroups))
             continue;
         const pool = nowGroups.map((g) => ({ head: groupHead(g), left: isRecordShape(g) && Array.isArray(g.hooks) ? [...g.hooks] : [] }));
-        const evOut = [];
+        const sentGroups = [];
         for (const g of groups) {
             const head = groupHead(g);
             if (head === undefined || !isRecordShape(g) || !Array.isArray(g.hooks))
                 continue;
-            const keep = [];
-            for (const entry of g.hooks) {
-                for (const slot of pool) {
-                    if (slot.head === undefined || !sameJson(slot.head, head))
-                        continue;
-                    const at = slot.left.findIndex((x) => sameJson(x, entry));
-                    if (at < 0)
-                        continue;
-                    slot.left.splice(at, 1);
-                    appendOwnElement(keep, entry);
-                    break;
-                }
+            const claims = [];
+            for (const entry of g.hooks)
+                appendOwnElement(claims, { entry, claimed: false });
+            appendOwnElement(sentGroups, { head, claims });
+        }
+        appendOwnElement(events, { event, groups: sentGroups, pool });
+    }
+    const takeWitness = (ev, g, matches) => {
+        for (const slot of ev.pool) {
+            if (slot.head === undefined || !sameJson(slot.head, g.head))
+                continue;
+            const at = slot.left.findIndex(matches);
+            if (at < 0)
+                continue;
+            const [witness] = slot.left.splice(at, 1);
+            return { witness };
+        }
+        return undefined;
+    };
+    for (const ev of events)
+        for (const g of ev.groups)
+            for (const c of g.claims)
+                if (takeWitness(ev, g, (w) => sameJson(w, c.entry)) !== undefined)
+                    c.claimed = true;
+    for (const ev of events) {
+        for (const g of ev.groups) {
+            for (const c of g.claims) {
+                if (c.claimed)
+                    continue;
+                const hit = takeWitness(ev, g, (w) => isSubsetWitness(c.entry, w));
+                if (hit !== undefined)
+                    c.claimed = true;
             }
+        }
+    }
+    const out = {};
+    let kept = 0;
+    for (const ev of events) {
+        const evOut = [];
+        for (const g of ev.groups) {
+            const keep = [];
+            for (const c of g.claims)
+                if (c.claimed)
+                    appendOwnElement(keep, c.entry);
             if (keep.length > 0)
-                appendOwnElement(evOut, { ...head, hooks: keep });
+                appendOwnElement(evOut, { ...g.head, hooks: keep });
             kept += keep.length;
         }
         if (evOut.length > 0)
-            out[ev] = evOut;
+            out[ev.event] = evOut;
     }
     const hooks = Object.keys(out).length > 0 ? out : undefined;
     return { hooks, dropped: total - kept, judged: hooks === undefined || hooksPassJudge(hooks) };
@@ -1363,7 +1402,8 @@ function intakeSnapshotUnguarded(product, onResolved) {
         return undefined;
     if (values.hooks !== undefined && !hooksPassJudge(values.hooks))
         return undefined;
-    if (!hookEnvConsistent(values.env, values.hooks))
+    const planR = ownDataOf(product, 'hooks');
+    if (!hookEnvConsistent(values.env, values.hooks, planR.ok ? planSettingsContractOf(objectOrUndefined(planR.value)) : undefined))
         return undefined;
     const v = ownDataOf(product, 'verdict');
     if (!v.ok)

package/dist/humanTurn.d.ts

@@ -38,6 +38,7 @@ export interface HumanTurnItem {
 export interface HumanTurnCaps {
     readonly vision?: ImageVision;
     readonly userAttachments?: UserAttachmentSeatReading;
+    readonly scenario?: {} | null;
 }
 export interface HumanTurnInput {
     readonly items: readonly HumanTurnItem[];
@@ -45,7 +46,7 @@ export interface HumanTurnInput {
     readonly caps: HumanTurnCaps;
     readonly otherBodyBytes?: number;
 }
-type EncoderShortfall = 'body_budget' | 'steer_admission' | 'vision_no' | 'image_too_large' | 'seat_count' | 'seat_total' | 'lane_has_no_image_seat' | 'lane_has_no_attachment_id_seat';
+type EncoderShortfall = 'body_budget' | 'steer_admission' | 'vision_no' | 'image_too_large' | 'seat_count' | 'seat_total' | 'lane_has_no_image_seat' | 'lane_has_no_attachment_id_seat' | 'lane_has_no_path_seat' | 'path_not_admitted' | 'path_seat_count';
 export interface HumanTurnSharePart {
     readonly kind: 'text' | 'image' | 'attachment_ref' | 'attachment_id' | 'rider_text' | 'non_text';
     readonly ref?: string | number;

package/dist/humanTurn.js

@@ -1,5 +1,5 @@
 import { CORE_IMAGE_ADMISSION_HARD_IMAGE_BASE64_CHARS, CORE_MAX_PENDING_STEER_CHARS, CORE_USER_ATTACHMENT_LABEL_MAX } from './generated/engineFactTables.js';
-import { mintEnvelopeOf, mintReferenceOf, seatTextOf } from './userAttachmentEnvelope.js';
+import { mintEnvelopeOf, mintPathPointerOf, mintReferenceOf, seatTextOf } from './userAttachmentEnvelope.js';
 import { readEncodingShares, readHumanTurnInput } from './humanTurnRead.js';
 import { putOwnKey } from './ownKey.js';
 import { msg, renderMessage } from './i18n/translate.js';
@@ -76,11 +76,11 @@ function steerRefusal(text) {
         return 'too_long';
     return undefined;
 }
-function textOf(p) {
+function textOf(p, pointers) {
     if (p.form === 'reference')
         return mintReferenceOf(p.a.d);
     if (p.form === 'seat')
-        return '';
+        return pointers && p.a.d.kind === 'path' ? mintPathPointerOf(p.a.d) : '';
     return mintEnvelopeOf(p.a.d, p.seated ? 'attached' : 'not-attached');
 }
 const digits = (n) => String(n).length;
@@ -100,10 +100,14 @@ function seatEntryOf(a, maxRenderedTextChars) {
         return undefined;
     return a.d.kind === 'text' ? { name, text, startLine } : { name, text };
 }
-function compose(items, placements) {
-    const perItem = items.map((it, i) => [...placements.filter((p) => p.item === i).map(textOf), it.text].filter((s) => s.length > 0).join('\n\n'));
+function compose(items, placements, pointers = false) {
+    const perItem = items.map((it, i) => [...placements.filter((p) => p.item === i).map((p) => textOf(p, pointers)), it.text].filter((s) => s.length > 0).join('\n\n'));
     return perItem.filter((s) => s.length > 0).join('\n');
 }
+function composeObjective(items, placements) {
+    const text = compose(items, placements);
+    return text.trim() === '' && placements.some((p) => p.form === 'seat' && p.a.d.kind === 'path') ? compose(items, placements, true) : text;
+}
 function seatedImages(items, pastedWhy, placements) {
     const out = [];
     items.forEach((it, i) => {
@@ -127,6 +131,9 @@ const ENCODER_WHY_LIST = [
     'seat_total',
     'lane_has_no_image_seat',
     'lane_has_no_attachment_id_seat',
+    'lane_has_no_path_seat',
+    'path_not_admitted',
+    'path_seat_count',
 ];
 const encoderWhysExhaustive = true;
 void encoderWhysExhaustive;
@@ -146,7 +153,7 @@ function records(lane, items, pastedWhy, placements) {
         for (const p of placements) {
             if (p.item !== i)
                 continue;
-            push(i, p.form !== 'reference' ? { kind: 'attachment_ref', ref: p.a.uuid, status: 'full' } : { kind: 'attachment_ref', ref: p.a.uuid, status: 'none', why: lane === 'objective' ? 'body_budget' : 'steer_admission' });
+            push(i, p.form !== 'reference' ? { kind: 'attachment_ref', ref: p.a.uuid, status: 'full' } : { kind: 'attachment_ref', ref: p.a.uuid, status: 'none', why: p.refWhy ?? (lane === 'objective' ? 'body_budget' : 'steer_admission') });
             if (p.a.pixels !== undefined) {
                 if (lane === 'steer')
                     push(i, { kind: 'image', ref: p.a.uuid, status: 'none', why: 'lane_has_no_image_seat' });
@@ -238,7 +245,7 @@ function encodeObjective(v) {
     const placements = [];
     items.forEach((it, i) => {
         for (const a of it.attachments) {
-            const p = { item: i, a, form: 'content', seated: false, seatWhy: undefined, entry: undefined };
+            const p = { item: i, a, form: 'content', seated: false, seatWhy: undefined, entry: undefined, refWhy: undefined };
             if (a.pixels !== undefined) {
                 if (v.vision === 'no')
                     p.seatWhy = 'vision_no';
@@ -250,10 +257,29 @@ function encodeObjective(v) {
             placements.push(p);
         }
     });
+    let pathSeated = 0;
+    for (const p of placements) {
+        const d = p.a.d;
+        if (d.kind !== 'path')
+            continue;
+        if (v.pathSeats === undefined) {
+            p.form = 'reference';
+            p.refWhy = 'path_not_admitted';
+        }
+        else if (pathSeated >= v.pathSeats) {
+            p.form = 'reference';
+            p.refWhy = 'path_seat_count';
+        }
+        else {
+            p.form = 'seat';
+            p.entry = d.entry;
+            pathSeated += 1;
+        }
+    }
     if (v.seat !== undefined) {
         let n = 0;
         for (const p of placements) {
-            if (n >= v.seat.maxEntries)
+            if (pathSeated + n >= v.seat.maxEntries)
                 break;
             const entry = seatEntryOf(p.a, v.seat.maxRenderedTextChars);
             if (entry === undefined)
@@ -264,7 +290,7 @@ function encodeObjective(v) {
         }
         if (n > 0 && compose(items, placements).trim() === '') {
             for (const p of placements) {
-                if (p.form === 'seat') {
+                if (p.form === 'seat' && p.a.d.kind !== 'path') {
                     p.form = 'content';
                     p.entry = undefined;
                 }
@@ -273,7 +299,7 @@ function encodeObjective(v) {
     }
     const ids = items.flatMap((it) => it.attachmentIds);
     for (;;) {
-        const text = compose(items, placements);
+        const text = composeObjective(items, placements);
         const images = seatedImages(items, pastedWhy, placements);
         const seated = placements.filter((p) => p.form === 'seat');
         const entries = seated.map((p) => p.entry);
@@ -298,6 +324,8 @@ function encodeObjective(v) {
         placements.forEach((p, k) => {
             if (p.form === 'reference')
                 return;
+            if (p.a.d.kind === 'path')
+                return;
             if (p.form === 'seat') {
                 const cost = jsonBytes(p.entry) + 1;
                 if (cost >= pickCost) {
@@ -306,7 +334,7 @@ function encodeObjective(v) {
                 }
                 return;
             }
-            const cost = jsonBytes(textOf(p)) + (p.seated && p.a.pixels !== undefined ? jsonBytes({ data: p.a.pixels.data, mimeType: p.a.pixels.mimeType }) : 0);
+            const cost = jsonBytes(textOf(p, false)) + (p.seated && p.a.pixels !== undefined ? jsonBytes({ data: p.a.pixels.data, mimeType: p.a.pixels.mimeType }) : 0);
             if (cost >= pickCost) {
                 pick = k;
                 pickCost = cost;
@@ -321,8 +349,11 @@ function encodeSteer(v) {
     const { items } = v;
     const placements = [];
     items.forEach((it, i) => {
-        for (const a of it.attachments)
-            placements.push({ item: i, a, form: 'content', seated: false, seatWhy: undefined, entry: undefined });
+        for (const a of it.attachments) {
+            placements.push(a.d.kind === 'path'
+                ? { item: i, a, form: 'reference', seated: false, seatWhy: undefined, entry: undefined, refWhy: 'lane_has_no_path_seat' }
+                : { item: i, a, form: 'content', seated: false, seatWhy: undefined, entry: undefined, refWhy: undefined });
+        }
     });
     let text = compose(items, placements);
     let refusal = steerRefusal(text);

package/dist/humanTurnRead.d.ts

@@ -3,6 +3,7 @@ import type { UserAttachmentDescriptor, UserAttachmentMcpResourcePart, UserAttac
 import type { HumanTurnAttachment, HumanTurnEncoding, HumanTurnInput, HumanTurnMissing } from './humanTurn.js';
 import type { ImageVision } from './liveModelCatalog.js';
 import { type UserAttachmentSeatLimits } from './userAttachmentSeat.js';
+import { type UserAttachmentPathEntry } from './attachmentPathPlan.js';
 export interface CellView {
     cellType: string | undefined;
     source: string | undefined;
@@ -70,6 +71,11 @@ export type DescriptorView = {
     name: string;
     parts: UserAttachmentMcpResourcePart[];
     truncated: boolean;
+} | {
+    kind: 'path';
+    name: string;
+    path: string;
+    entry: UserAttachmentPathEntry;
 };
 export declare function readDescriptor(x: UserAttachmentDescriptor | HumanTurnAttachment['descriptor'], imageDelivery: 'required' | 'ignored'): DescriptorView | undefined;
 type Reason = Exclude<Extract<HumanTurnEncoding, {
@@ -106,6 +112,7 @@ export interface InputView {
     lane: 'objective' | 'steer';
     vision: ImageVision;
     seat: UserAttachmentSeatLimits | undefined;
+    pathSeats: number | undefined;
     otherBodyBytes: number;
     items: ItemView[];
 }