@sema-agent/core 7.49.0 → 7.49.2

package/dist/core/runner/prepare-safety-scan.js

@@ -1,15 +1,16 @@
 import { NAMESPACED_NAME_SHAPES, carriesNamespaceSeparator } from "../protocol-table.js";
 import { engineCardTypes, handBandEffects } from "../tool-registry.js";
-import { callerCardIdOf, offendingResultCard, rosterMemberBoundProblem, schemaKeyBoundProblem } from "../tool-roster.js";
+import { callerCardIdOf, offendingResultCard, rosterMemberBoundProblem, schemaKeyBoundProblem, survivorsByName } from "../tool-roster.js";
 import { toolFaceProblem } from "./tool-face-overlay.js";
 import { OFFLOAD_TOOL_NAME } from "../tool-result-store.js";
 import { PRESENT_PLAN_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME } from "../present-plan-tool.js";
 const REPEAT_RISK = { read: 0, idempotent: 1, write: 2 };
 const leastRepeatSafe = (a, b) => (REPEAT_RISK[a] >= REPEAT_RISK[b] ? a : b);
+const tierOf = (t) => t.irreversibility ?? (t.reversibilityProbe ? "maybe" : undefined);
 export function prepareSafetyScan(input) {
     const { spec, deps } = input;
     const toolEffects = new Map();
-    const ownToolNames = new Set((spec.tools ?? []).map((t) => t.name));
+    const survivors = survivorsByName(spec.tools ?? []);
     const claimedAliases = new Set();
     const egressTools = new Set();
     const irreversibleTools = new Set();
@@ -76,10 +77,10 @@ export function prepareSafetyScan(input) {
                 throw e;
             }
         }
-        if (t.effect) {
+        if (t.effect && survivors.get(t.name) === t) {
             toolEffects.set(t.name, t.effect);
         }
-        const tier = t.irreversibility ?? (t.reversibilityProbe ? "maybe" : undefined);
+        const tier = tierOf(t);
         if (tier !== undefined) {
             irreversibilityTier.set(t.name, tier);
             if (tier === "always" || tier === "maybe") {
@@ -98,8 +99,11 @@ export function prepareSafetyScan(input) {
             egressTools.add(t.name);
             markedBy(t.name, "deployment");
         }
+    }
+    for (const t of survivors.values()) {
+        const tier = tierOf(t);
         for (const alias of t.aliases ?? []) {
-            if (alias === t.name || ownToolNames.has(alias))
+            if (alias === t.name || survivors.has(alias))
                 continue;
             if (claimedAliases.has(alias))
                 continue;
@@ -122,7 +126,7 @@ export function prepareSafetyScan(input) {
         }
     }
     toolEffects.set(OFFLOAD_TOOL_NAME, "read");
-    const claimerEffects = new Map([...claimedAliases].map((a) => [a, toolEffects.get(a) ?? "write"]));
+    const claimerEffects = new Map([...claimedAliases, ...survivors.keys()].map((a) => [a, toolEffects.get(a) ?? "write"]));
     const recordHandEffect = (name, effect) => {
         const claimed = claimerEffects.get(name);
         toolEffects.set(name, claimed === undefined ? effect : leastRepeatSafe(claimed, effect));

package/dist/core/runner/run-harness-handlers.js

@@ -13,7 +13,7 @@ import { announceToolCall, batchResponseDigest, emitSettled } from "./tool-end-b
 import { createResponseModelSeat } from "./response-model-seat.js";
 import { createToolCallIdFoldSeat } from "./tool-call-id-fold-seat.js";
 import { createFinishReasonSeat } from "./finish-reason-seat.js";
-import { createToolTurnIncompleteSeat } from "./tool-turn-repair-seat.js";
+import { createToolTurnIncompleteSeat, turnCarriesToolCall } from "./tool-turn-repair-seat.js";
 import { wireOf } from "../tool-name-readings.js";
 import { rosterToolName } from "../tool-roster.js";
 export function createHarnessHandlers(input) {
@@ -199,7 +199,7 @@ export function createHarnessHandlers(input) {
             const content = m.content;
             if (rs.attach.attachState !== undefined)
                 rs.counters.cadenceTurns = advanceCadenceClock(rs.attach.attachState, rs.counters.cadenceTurns, content, writeFamilyOf);
-            rs.turn.lastTurnHadToolCalls = Array.isArray(content) && content.some((c) => c?.type === "toolCall");
+            rs.turn.lastTurnHadToolCalls = turnCarriesToolCall(content);
         }
         rs.turn.callStartAt = undefined;
         rs.turn.firstTokenAt = undefined;

package/dist/core/runner/tool-turn-repair-seat.d.ts

@@ -1,15 +1,39 @@
 import type { EngineNotice } from "../engine-notice.js";
-import { type ToolTurnIncompleteCause, type ToolTurnRepair } from "../../internal/llm.js";
+import { type ToolTurnRepair } from "../../internal/llm.js";
 /** The notice's attribution ids — the same pair, for the same reason, as the fold seat's. */
 export interface ToolTurnRepairSeatIds {
     sessionId: string;
     runId: string;
 }
+/** What the message says became of a turn that dropped calls: the run ended on it (`model_output_invalid`), or the next
+ *  request asks the model to re-issue them. */
+export type ToolTurnOutcome = "terminal" | "reissued";
+/** One thing the person is told, per cause. A dropped-call cause carries the outcome when its message states one (else
+ *  `undefined`: nothing is said about the run's fate); the others have none. */
+export type ToolTurnIncompleteItem = {
+    cause: "truncated";
+    count: number;
+    outcome: ToolTurnOutcome | undefined;
+} | {
+    cause: "unnamed";
+    count: number;
+    outcome: ToolTurnOutcome | undefined;
+} | {
+    cause: "bad_frame";
+    count: number;
+} | {
+    cause: "missing_result_synthesized";
+    count: number;
+    toolCallIds: readonly string[];
+};
+/** Does a turn's content carry a tool call? A tool-calling turn GUARANTEES a next request (its results go back to the
+ *  model): the engine's one continuation fact — the harness's boundary gates and the dropped-call line read it here. */
+export declare function turnCarriesToolCall(content: unknown): boolean;
 /** The person's line for one cause — once per run per cause, whichever observer saw it first. */
 export interface ToolTurnIncompleteSeat {
-    /** Announce `count` items of `cause` (and, for a missing result, the calls) unless this run already said it. */
-    announce(cause: ToolTurnIncompleteCause, count: number, toolCallIds?: readonly string[]): void;
-    /** Observe one assistant message: announces each stream drop it reports (`streamDropsOf`). */
+    /** Announce `item` unless this run already said its cause. */
+    announce(item: ToolTurnIncompleteItem): void;
+    /** Observe one assistant message: announces each stream drop it reports (`streamDropsOf`), worded by what became of the turn. */
     observe(message: {
         readonly diagnostics?: unknown;
     }): void;

package/dist/core/runner/tool-turn-repair-seat.js

@@ -1,6 +1,8 @@
 import { deliverEngineNotice } from "../engine-notice.js";
 import { isProviderEchoShape } from "../../brain/errors.js";
 import { streamDropsOf } from "../../internal/llm.js";
+import { readMember } from "../thrown-value.js";
+import { modelOutputInvalidOfMessage } from "./terminal-account.js";
 const FORM_SENTENCE = {
     trailing_text: "a block after an assistant's tool calls was moved ahead of them",
     late_result: "a result recorded later was moved up behind its call",
@@ -9,30 +11,51 @@ const FORM_SENTENCE = {
     duplicate_call: "a second call with the same id in one assistant message was left out (its results answer the first)",
     orphan_result: "a result that answers no call before it was left out",
 };
+const afterDroppedCalls = (outcome) => outcome === "reissued" ? "; the model was asked to re-issue them" : outcome === "terminal" ? "; the run ended with this turn (model_output_invalid)" : "";
 const INCOMPLETE_SENTENCE = {
-    truncated: (n) => `${n} tool call(s) the model made were cut off before their arguments were complete, so they did not run; the model was asked to re-issue them`,
-    unnamed: (n) => `${n} tool call(s) the model made arrived with no tool name, so they did not run; the model was asked to re-issue them`,
-    bad_frame: (n) => `${n} frame(s) of the model's streamed response could not be read and were dropped, so the response may be missing content; the model was told`,
-    missing_result_synthesized: (n) => `${n} earlier tool call(s) have no recorded result, so the model was told their outcome is unknown`,
+    truncated: (i) => `${i.count} tool call(s) the model made were cut off before their arguments were complete, so they did not run${afterDroppedCalls(i.outcome)}`,
+    unnamed: (i) => `${i.count} tool call(s) the model made arrived with no tool name, so they did not run${afterDroppedCalls(i.outcome)}`,
+    bad_frame: (i) => `${i.count} frame(s) of the model's streamed response could not be read and were dropped, so the response may be missing content; the model was told`,
+    missing_result_synthesized: (i) => `${i.count} earlier tool call(s) have no recorded result, so the model was told their outcome is unknown`,
 };
+export function turnCarriesToolCall(content) {
+    try {
+        return Array.isArray(content) && content.some((c) => c?.type === "toolCall");
+    }
+    catch {
+        return false;
+    }
+}
+function outcomeOf(message) {
+    const stop = readMember(message, "stopReason");
+    if (stop === "error")
+        return modelOutputInvalidOfMessage(message) !== undefined ? "terminal" : undefined;
+    if (stop === "aborted")
+        return undefined;
+    return turnCarriesToolCall(readMember(message, "content")) || stop === "toolUse" || stop === "length" ? "reissued" : undefined;
+}
 export function createToolTurnIncompleteSeat(onNotice, ids) {
     const announced = new Set();
-    const announce = (cause, count, toolCallIds) => {
-        if (announced.has(cause))
+    const announce = (item) => {
+        if (announced.has(item.cause))
             return;
-        announced.add(cause);
-        const shown = (toolCallIds ?? []).filter((id) => isProviderEchoShape(id));
+        announced.add(item.cause);
+        const shown = "toolCallIds" in item ? item.toolCallIds.filter((id) => isProviderEchoShape(id)) : [];
         deliverEngineNotice(onNotice, {
             code: "task.tool_turn_incomplete",
-            message: `${INCOMPLETE_SENTENCE[cause](count)}. Announced once per run for this cause.`,
-            detail: { cause, count, ...(shown.length > 0 ? { toolCallIds: shown } : {}), sessionId: ids.sessionId, runId: ids.runId },
+            message: `${INCOMPLETE_SENTENCE[item.cause](item)}. Announced once per run for this cause.`,
+            detail: { cause: item.cause, count: item.count, ...("outcome" in item && item.outcome !== undefined ? { outcome: item.outcome } : {}), ...(shown.length > 0 ? { toolCallIds: shown } : {}), sessionId: ids.sessionId, runId: ids.runId },
         });
     };
     return {
         announce,
         observe(message) {
-            for (const drop of streamDropsOf(message))
-                announce(drop.cause, drop.count);
+            const drops = streamDropsOf(message);
+            if (drops.length === 0)
+                return;
+            const outcome = outcomeOf(message);
+            for (const drop of drops)
+                announce(drop.cause === "bad_frame" ? { cause: "bad_frame", count: drop.count } : { cause: drop.cause, count: drop.count, outcome });
         },
     };
 }
@@ -42,7 +65,7 @@ export function createToolTurnRepairSeat(onNotice, ids) {
     return (repairs) => {
         const missing = repairs.filter((repair) => repair.form === "missing_result" && repair.beforeRun !== true).flatMap((repair) => repair.toolCallIds);
         if (missing.length > 0)
-            incomplete.announce("missing_result_synthesized", missing.length, missing);
+            incomplete.announce({ cause: "missing_result_synthesized", count: missing.length, toolCallIds: missing });
         const fresh = repairs.filter((repair) => {
             const key = `${repair.form}\u0000${[...repair.toolCallIds].sort().join("\u0000")}`;
             if (announced.has(key))

package/dist/core/runner-deps.d.ts

@@ -1249,10 +1249,10 @@ export interface RunnerDeps {
      * declaration refusing the batch legs). Absent = no posture check anywhere.
      */
     interactionPosture?: "interactive" | "headless";
-    /** LSP code-intelligence seam (design/64 §13.1): when set, every task mounts an `lsp` tool routed to this
+    /** LSP code-intelligence seam (design/64 §13.1): when set, every task WITH HANDS mounts an `lsp` tool routed to this
      *  manager (a deployment-provided language-server bridge, e.g. an E2B LSP sidecar). The manager returns
      *  `undefined` for a file whose language has no server, and the tool degrades to "fall back to grep". A
-     *  task's own `lspManager` overrides this. Unset ⇒ no `lsp` tool. */
+     *  task's own `lspManager` overrides this. Neither seat set, or a leg without an execution env ⇒ the engine mounts no `lsp` tool. */
     lspManager?: import("./lsp.js").LspServerManager;
     /**
      * The Artifacts hosting seat — a storage/service-tier seam of the same family as

package/dist/core/shell-wrapper-projection.js

@@ -38,7 +38,7 @@ function projectRow(row) {
         return executes.length > 0 ? { valueFlags: [], flags: [], commandString: [], executes } : undefined;
     }
     const commandString = sorted(all.filter((o) => o.spec.value?.kind === "shell-text").map((o) => o.spelling));
-    const values = all.filter((o) => o.spec.value?.kind !== "shell-text");
+    const values = all.filter((o) => o.spec.value?.kind !== "shell-text" && o.spec.mode !== "queries");
     const attached = sorted(values.filter((o) => o.arity === "attached" && !o.spelling.startsWith("--")).map((o) => o.spelling));
     const required = row.launcher.requiredOperands ?? 0;
     const duration = required > 0 && row.launcher.requiredOperandSpelling === DURATION_SPELLING;

package/dist/core/task-spec.d.ts

@@ -602,8 +602,8 @@ export interface TaskSpec {
      *  AskUserQuestion tool is mounted (one of the delivery faces in the criterion — see
      *  {@link interactiveTools}). Overrides `RunnerDeps.onQuestion`. Distinct from `onAsk` (permission). */
     onQuestion?: import("./ask-question.js").OnQuestion;
-    /** LSP code-intelligence seam (design/64 §13.1): when set, the `lsp` tool is mounted and routed to this
-     *  manager. Overrides `RunnerDeps.lspManager`. Unset ⇒ no `lsp` tool (the model uses grep/read_file). */
+    /** LSP code-intelligence seam (design/64 §13.1): when set, the `lsp` tool is mounted on a leg with hands and routed to
+     *  this manager. Overrides `RunnerDeps.lspManager`. Neither seat set, or no hands ⇒ the engine mounts no `lsp` tool (the model uses grep/read_file). */
     lspManager?: import("./lsp.js").LspServerManager;
     /**
      * design/121 (CC 198 parity): after the agent edits a file, NEW language-server diagnostics are

package/dist/core/tool-catalog-entries.js

@@ -98,7 +98,7 @@ export const TOOL_CATALOG_ENTRIES = [
         },
     },
     { id: "repo-map", name: "RepoMap", source: "builtin", definedIn: "src/tools/fs/repo-map.ts", mountedBy: ["hands"], cards: ["repo-map"], face: { family: "search", effect: "read", contract: c("core.repo_map@1") } },
-    { id: "lsp", name: "LSP", source: "builtin", definedIn: "src/core/lsp.ts", mountedBy: ["optional"], cards: [], face: { family: "search", effect: "read", contract: c("core.lsp@1") } },
+    { id: "lsp", name: "LSP", source: "builtin", definedIn: "src/core/lsp.ts", mountedBy: ["hands"], cards: [], face: { family: "search", effect: "read", contract: c("core.lsp@1") } },
     {
         id: "artifact", name: ARTIFACT_TOOL_NAME, source: "builtin", definedIn: "src/tools/artifact/artifact-tool.ts", mountedBy: ["optional"], cards: ["artifact"],
         face: { family: "other", effect: "write", contract: c("core.artifact@1"), ruleFace: { primaryParams: ["action"] }, renderHints: { summaryParams: ["action", "file_path", "url"] } },

package/dist/core/tool-conformance.js

@@ -14,6 +14,7 @@ export const TOOL_CONFORMANCE_VECTORS = [
         { name: "SendMessage", why: "needs the runner self seat (a direct prepare has none)" },
         { name: "AgentTranscript", why: "needs the runner self seat (a direct prepare has none)" },
         { name: "ListAgents", why: "mounts with the delegation face only under a runner self seat (a direct prepare has none)" },
+        { name: "LSP", why: "needs a wired LSP manager" },
     ], [OFFLOAD_READER]),
     vector("hands-readonly", ["always", "hands"], [
         { name: "Edit", why: "the read-only band mounts the read half only" },
@@ -23,9 +24,9 @@ export const TOOL_CONFORMANCE_VECTORS = [
         { name: "TaskStop", why: "the background-shell pair mounts on the full shell only" },
         { name: "EnterWorktree", why: "the worktree pair needs the tracked cwd the full shell owns" },
         { name: "ExitWorktree", why: "the worktree pair needs the tracked cwd the full shell owns" },
+        { name: "LSP", why: "needs a wired LSP manager" },
     ], [OFFLOAD_READER]),
     vector("plan-mode", ["always", "optional"], [
-        { name: "LSP", why: "needs a wired LSP manager" },
         { name: "Artifact", why: "needs a wired artifact host" },
         { name: "Skill", why: "needs a skills listing" },
         { name: "StructuredOutput", why: "needs an output schema" },

package/dist/core/tool-roster.d.ts

@@ -392,6 +392,11 @@ export declare function ruleFaceOfInstance(schema: TSchema | undefined, declared
     primaryParams: string[];
     params: string[];
 };
+/** The instance each NAME dispatches to when several are mounted under it: the LATER mount (the harness keeps the
+ *  later one). The one selection — the roster's snapshot and every table keyed by a caller tool's name read it here. */
+export declare function survivorsByName<T extends {
+    readonly name: string;
+}>(mounted: readonly T[]): Map<string, T>;
 /** What a mount site knows that the instance does not: where the tool came from and which condition fired. */
 export interface RosterMountMeta {
     source: RosterSource;
@@ -443,13 +448,13 @@ export declare class RosterBuilder {
     get tools(): readonly AgentTool[];
     get length(): number;
     metaOf(tool: AgentTool): RosterMountMeta | undefined;
-    /** Mount one instance at the tail. An instance that DECLARES an effect writes it into the leg's effect map —
-     *  the later mount under a name is the one the harness dispatches to (`snapshot`'s yield rule), so its
+    /** Mount one instance at the tail. An engine-lane instance that DECLARES an effect writes it into the leg's effect
+     *  map — the later mount under a name is the one the harness dispatches to (`snapshot`'s yield rule), so its
      *  declaration is the map's truth for that name; a pre-mount registration (the hand band, the plan pair, an
-     *  MCP axis) stands only for names no mounted instance declares. ONE lane is different by construction: the
-     *  `scenario` lane's declarations were latched by the safety scan BEFORE any mount, on the synchronous
-     *  doors+scan stretch (a microtask cannot flip them) — so a scenario mount never re-reads its instance's
-     *  effect over a registered name; an engine lane's mount under that name still displaces it. */
+     *  MCP axis) stands only for names no mounted instance declares. The `scenario` lane never writes the map: its
+     *  declarations were latched by the safety scan BEFORE any mount (on the kept instance of each name, on the
+     *  synchronous doors+scan stretch — a microtask cannot flip them), so a scenario mount, kept or dropped, leaves
+     *  the map as the scan made it; an engine lane's mount under that name still displaces it. */
     mount(tool: AgentTool, meta: RosterMountMeta): void;
     /** An ENGINE-INJECTED instance the harness list carries outside the mount array (the ToolSearch lane): a roster
      *  row — the model can call it — never a mount-array element (the disclosure lane owns that list and appends the

package/dist/core/tool-roster.js

@@ -294,6 +294,12 @@ function capRenderHints(h) {
         out.approvalCard = h.approvalCard;
     return Object.keys(out).length > 0 ? out : undefined;
 }
+export function survivorsByName(mounted) {
+    const winner = new Map();
+    for (const t of mounted)
+        winner.set(t.name, t);
+    return winner;
+}
 export const faceOf = (t) => t;
 function configError(code, message) {
     const e = new Error(message);
@@ -333,7 +339,7 @@ export class RosterBuilder {
             throw configError("config.tool_roster_mount_tag", `tool ${JSON.stringify(tool.name)}: mount tag ${JSON.stringify(meta.mountedBy)} is outside the closed set`);
         this.#meta.set(tool, meta);
         const eff = faceOf(tool).effect;
-        if (eff !== undefined && !(meta.mountedBy === "scenario" && this.#effects.has(tool.name)))
+        if (eff !== undefined && meta.mountedBy !== "scenario")
             this.#effects.set(tool.name, eff);
     }
     mountAll(tools, meta) {
@@ -382,9 +388,7 @@ export class RosterBuilder {
     }
     snapshot(facts) {
         const all = [...this.#tools, ...this.#engineLane];
-        const winner = new Map();
-        for (const t of all)
-            winner.set(t.name, t);
+        const winner = survivorsByName(all);
         const entries = [];
         const emitted = new Set();
         for (const t of all) {

package/dist/core/write-protect.d.ts

@@ -1,4 +1,5 @@
 import type { ExecutionEnv } from "../internal/harness-types.js";
+import type { ObservedFilesystem } from "../tools/fs/shell-read-environment.js";
 import type { PermissionResult } from "./tool-policy.js";
 import { type ToolCallLike } from "./tool-registry.js";
 /**
@@ -231,7 +232,8 @@ export interface LegWriteJudgment {
      *  write rows together — one reading of the target (its spelling, its real target, its symlink chain; a `canonical` key
      *  judged as a key), one exempt root, one absence law. `undefined` ⇒ no row covers it. Absent when neither table has a
      *  row. */
-    readonly judgeWriteTarget: ((target: string, opts?: {
+    readonly judgeWriteTarget: ((target: string, opts: {
+        readonly fs: ObservedFilesystem;
         readonly signal?: AbortSignal;
         readonly canonical?: true;
     }) => Promise<WriteTargetCoverage | undefined>) | undefined;

package/dist/core/write-protect.js

@@ -223,7 +223,7 @@ export function compileLegWriteJudgment(entries, opts) {
         judgeWriteTarget: rows.length === 0 && guardRows === undefined
             ? undefined
             : async (target, judgeOpts) => {
-                const hit = await compiled.judgment(target, { ...(judgeOpts?.signal !== undefined ? { signal: judgeOpts.signal } : {}), ...(judgeOpts?.canonical === true ? { canonical: true } : {}) }, guardRows);
+                const hit = await compiled.judgment(target, { ...(judgeOpts.signal !== undefined ? { signal: judgeOpts.signal } : {}), ...(judgeOpts.canonical === true ? { canonical: true } : {}) }, judgeOpts.fs, guardRows);
                 return hit === undefined ? undefined : hit.unreadable === undefined && TABLE_ROWS.has(hit.row) ? "protected" : "guarded";
             },
     };
@@ -283,9 +283,8 @@ function compileWriteJudgment(rows, origin, opts) {
         const base = typeof cwd === "string" && cwd.length > 0 ? cwd : undefined;
         return base !== undefined ? anchorSpelling(pathFamilyOf({ cwd: base }), base, path) : path;
     };
-    const env = opts?.env;
     const rootPath = opts?.rootPath;
-    const judgment = async (path, ctx, extraSource) => {
+    const judgment = async (path, ctx, env, extraSource) => {
         let noted = false;
         const noteAbsence = (cause, unresolvedSymlink) => {
             if (noted)
@@ -384,13 +383,13 @@ function compileWriteJudgment(rows, origin, opts) {
     };
     const matcher = {
         rows,
-        targetView: env === undefined ? "spelling-only" : "target",
+        targetView: opts?.env === undefined ? "spelling-only" : "target",
         matchPath(path, cwd) {
             const hit = judgePathRows(tableAt([]), { views: [spelledView(anchoredSpelling(path, cwd), "lexical")] }, "tighten");
             return hit === undefined ? null : { name: hit.row.name, kind: hit.row.kind };
         },
         async judge(path, ctx = {}) {
-            const hit = await judgment(path, ctx);
+            const hit = await judgment(path, ctx, opts?.env);
             if (hit === undefined)
                 return { kind: "clear" };
             if (hit.unreadable !== undefined)

package/dist/tools/fs/bash-program-position.d.ts

@@ -94,7 +94,8 @@ export interface ProgramPosition {
     /** The program the stream-fed chain member runs when the chain names none (`xargs` runs `echo`). */
     readonly defaultProgram?: string;
     /** The program bash RUNS: the first word past the chain. `name` is the folded word as written, `basename` what
-     *  bash resolves (`/usr/bin/cat` is `cat`). `undefined` when the chain names none or the read was refused. */
+     *  bash resolves (`/usr/bin/cat` is `cat`). `undefined` when the chain names none (a lookup, `command -v git`, runs
+     *  nothing) or the read was refused. */
     readonly program: {
         readonly index: number;
         readonly name: string;

package/dist/tools/fs/bash-program-position.js

@@ -1,6 +1,6 @@
 import { SHELL_CONTROL_PREFIXES } from "../../shell/lex.js";
 import { shellWordsOf } from "../../shell/shell-words.js";
-import { BLOCK_WORD_NAMES, LAUNCHER_NAMES, feedsArgvFromStdin, launcherOptionMovesBase, launcherOptionStep, launcherRunsShell, programRow, selectedOptions, streamDefaultProgram } from "./program-read-model.js";
+import { BLOCK_WORD_NAMES, LAUNCHER_NAMES, feedsArgvFromStdin, launcherOptionMovesBase, launcherOptionQueries, launcherOptionStep, launcherRunsShell, programRow, selectedOptions, streamDefaultProgram } from "./program-read-model.js";
 export const NOT_AUTO_ALLOWED = "— not auto-allowed";
 export function programBasename(word) {
     return word.includes("/") ? (word.split("/").pop() ?? word) : word;
@@ -38,7 +38,7 @@ function launcherRowOf(name) {
     const row = programRow(name);
     return row?.launcher !== undefined ? row : undefined;
 }
-function pastLauncherOptions(launcher, folded, i, moved) {
+function pastLauncherOptions(launcher, folded, i, moved, queried) {
     const row = launcherRowOf(launcher);
     if (row === undefined)
         return i;
@@ -57,7 +57,11 @@ function pastLauncherOptions(launcher, folded, i, moved) {
             return i;
         if (launcherOptionMovesBase(row, tok))
             moved?.();
+        if (launcherOptionQueries(row, tok))
+            queried?.();
         i += step;
+        if (tok === "--")
+            return i;
     }
 }
 export const PROGRAM_POSITION_REFUSAL_KINDS = Object.freeze(["option_at_program_position", "control_syntax_at_program_position"]);
@@ -103,12 +107,17 @@ export function readProgramPosition(words) {
     let reentryDefault = argvFromStdin ? streamDefaultProgram(basename) : undefined;
     let launcherMovesBase = false;
     const moved = () => { launcherMovesBase = true; };
+    let looksUp = false;
+    const queried = () => { looksUp = true; };
     const chain = (program, refusal) => {
         const runsDefaultProgram = lastReentry === folded.length - 1;
         return { controlWords, written, assignments, launchers, argvFromStdin, runsDefaultProgram, ...(runsDefaultProgram && reentryDefault !== undefined ? { defaultProgram: reentryDefault } : {}), program, refusal, launcherMovesBase };
     };
     const selectsShell = (l, end) => selectedOptions(launcherRowOf(l.name), folded.slice(l.index + 1, end)).some((o) => o.mode === "interactive");
-    for (let j = pastLauncherOptions(basename, folded, i + 1, moved); j < folded.length; j++) {
+    const first = pastLauncherOptions(basename, folded, i + 1, moved, queried);
+    if (looksUp)
+        return chain(undefined);
+    for (let j = first; j < folded.length; j++) {
         const t = folded[j];
         if (owedOperands > 0 && !t.startsWith("-")) {
             owedOperands -= 1;
@@ -133,7 +142,9 @@ export function readProgramPosition(words) {
             if (launcherRunsShell(launcherRowOf(wordBasename), folded.slice(j + 1)))
                 return chain(undefined, shellRefusal(j, j + 1));
             owedOperands = lastRow?.requiredOperands ?? 0;
-            j = pastLauncherOptions(wordBasename, folded, j + 1, moved) - 1;
+            j = pastLauncherOptions(wordBasename, folded, j + 1, moved, queried) - 1;
+            if (looksUp)
+                return chain(undefined);
             continue;
         }
         if (t.startsWith("-"))

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -167,8 +167,8 @@ export interface StrictResidualOptions {
  *  1. the quote-blind class ({@link SHELL_SEGMENT_QUOTE_BLIND_REJECT}) over every written spelling — a word, a
  *     redirection target under `tolerateRedirection` — plus every group, here-document, line-break connector
  *     and (unless tolerated or data-free) redirection token;
- *  2. the expansion character where bash expands it ({@link expandsDollar}), the home-directory word excepted
- *     under `homeDeclared`;
+ *  2. the expansion character where bash expands it and a `~user` / `~+` / `~-` tilde word
+ *     ({@link expandsBeyondText}), the home-directory word excepted under `homeDeclared`;
  *  3. a backgrounding `&` and a `|&`;
  *  4. a word whose value the text does not settle ({@link UNRESOLVED_SENTENCE}) — a compound array, an
  *     off-table ANSI-C escape, a subscript or parameter expansion this lexer does not read.

package/dist/tools/fs/bash-readonly-classifier.js

@@ -26,20 +26,22 @@ function hasBareShellOperator(s, quotedOperatorsAreText) {
     for (const t of lexed.segments[0].tokens) {
         if (t.kind !== "word")
             return true;
-        if (expandsDollar(t) || t.assignment?.form === "compound")
+        if (expandsBeyondText(t) || t.assignment?.form === "compound")
             return true;
         if (t.pieces.some((p) => p.quotedBy === "\\" || (p.quotedBy === undefined && p.literal !== undefined && /[\r\\]/.test(p.literal))))
             return true;
     }
     return false;
 }
-function expandsDollar(w) {
+function expandsBeyondText(w) {
     if (w.quotedSpans.some((q) => q.by === '$"'))
         return true;
     for (const p of w.pieces) {
         const k = p.expansion?.kind;
         if (k === "parameter" || k === "command" || k === "process" || k === "arithmetic")
             return true;
+        if (k === "tilde" && p.expansion?.body !== "~")
+            return true;
         if (p.literal !== undefined && (p.quotedBy === undefined || p.quotedBy === '"') && /[$`]/.test(p.literal))
             return true;
     }
@@ -126,7 +128,7 @@ export function strictResidualRefusal(lexed, source, opts = {}) {
     }
     const home = opts.homeDir !== undefined && !textBindsHome(source) ? opts.homeDir : undefined;
     for (const w of words) {
-        if (expandsDollar(w) && !(home !== undefined && homeSpelledForClassify(w, home) !== undefined))
+        if (expandsBeyondText(w) && !(home !== undefined && homeSpelledForClassify(w, home) !== undefined))
             return reason;
     }
     for (const s of lexed.segments) {

package/dist/tools/fs/program-read-model.d.ts

@@ -29,7 +29,7 @@ export declare const PATH_VALUE_FORMS: readonly ["indirect", "form", "header", "
 export type PathValueForm = (typeof PATH_VALUE_FORMS)[number];
 /** What selecting an option does to how the program runs ({@link OptionSpec.mode}) — a CLOSED set (`docs/CLOSED-SETS.md`,
  *  `OptionMode`). */
-export declare const OPTION_MODES: readonly ["banner", "interactive", "names-program", "follows", "repeats", "quiet", "forced"];
+export declare const OPTION_MODES: readonly ["banner", "interactive", "names-program", "follows", "repeats", "quiet", "forced", "queries"];
 export type OptionMode = (typeof OPTION_MODES)[number];
 /**
  * What one word is in this program's hands — a CLOSED set (`docs/CLOSED-SETS.md`, `ArgRoleKind`), the eleven members the
@@ -188,7 +188,8 @@ export interface OptionSpec {
      *  the program to run without a value (`node --test`; a launcher's, from the caller's environment: `su -m`); `follows`:
      *  follows its files as they grow, until killed (`tail -f`); `repeats`: repeats on an interval until killed (`free -s`);
      *  `quiet`: prints only what the program's own text tells it to (`sed -n`); `forced`: removes without asking, and passes
-     *  over an operand that is not there (`rm -f`). */
+     *  over an operand that is not there (`rm -f`); `queries`: a LOOKUP — the operands are names it looks up and describes, and
+     *  it runs none of them (`command -v`). */
     readonly mode?: OptionMode;
     /** This switch turns the program's own value glob off (`curl -g`): every {@link ArgRole} `programGlob` value of the
      *  invocation is read literally. */
@@ -717,6 +718,10 @@ export declare function launcherOptionPathRole(row: ProgramRow, tok: string): Ex
  *  written (`nsenter -w` bare takes the target process's directory)? In a cluster, a letter up to the first that takes a
  *  value. `false` for any word the walk does not step. */
 export declare function launcherOptionMovesBase(row: ProgramRow, tok: string): boolean;
+/** Does this launcher option word select a LOOKUP ({@link OptionSpec.mode} `queries`: `command -v`, `-V`, a cluster
+ *  carrying one — `-pv`), so that the words after the options are names and no program is run? In a cluster, a letter up
+ *  to the first that takes a value. `false` for any word the walk does not step. */
+export declare function launcherOptionQueries(row: ProgramRow, tok: string): boolean;
 /** How many words one launcher option occupies ({@link readLauncherOption}), or `undefined` where the row does not
  *  explain it. */
 export declare function launcherOptionStep(row: ProgramRow, tok: string): 1 | 2 | undefined;

package/dist/tools/fs/program-read-model.js

@@ -2,7 +2,7 @@ import { literalTildeSpelling } from "../../shell/lex.js";
 import { PROGRAM_ROWS } from "./program-read-model.rows.js";
 export const DATUM_FORMS = Object.freeze(["count", "pattern", "name-pattern", "label", "message", "delimiter"]);
 export const PATH_VALUE_FORMS = Object.freeze(["indirect", "form", "header", "url"]);
-export const OPTION_MODES = Object.freeze(["banner", "interactive", "names-program", "follows", "repeats", "quiet", "forced"]);
+export const OPTION_MODES = Object.freeze(["banner", "interactive", "names-program", "follows", "repeats", "quiet", "forced", "queries"]);
 export const ARG_ROLE_KINDS = Object.freeze(["path", "mount-source", "object-path", "program-text", "program-file", "shell-text", "command", "assignment", "binds-name", "entry-probe", "datum"]);
 export const PATH_EFFECTS = Object.freeze(["read", "names", "write", "create", "edit-in-place"]);
 export const WRITING_EFFECTS = new Set(["write", "create", "edit-in-place"]);
@@ -1091,6 +1091,26 @@ export function launcherOptionMovesBase(row, tok) {
     }
     return false;
 }
+export function launcherOptionQueries(row, tok) {
+    if (tok === "-" || tok === "--")
+        return false;
+    if (tok.startsWith("--")) {
+        const eq = tok.indexOf("=");
+        return steppableLauncherOption(row, eq > 2 ? tok.slice(0, eq) : tok)?.spec.mode === "queries";
+    }
+    if (!/^-[^-]/.test(tok))
+        return false;
+    for (let i = 1; i < tok.length; i++) {
+        const m = steppableLauncherOption(row, `-${tok[i]}`);
+        if (m === undefined)
+            return false;
+        if (m.spec.mode === "queries")
+            return true;
+        if (m.arity !== 0)
+            return false;
+    }
+    return false;
+}
 export function launcherOptionStep(row, tok) {
     return readLauncherOption(row, tok)?.step;
 }