@huynle/hub 0.7.4 → 0.8.0

package/packages/spoke-sdk/src/profile-apply.ts

@@ -0,0 +1,245 @@
+// Profile application for harness adapters (HWA-15; contract packages/protocol/src/profiles.ts). Shared by the
+// OpenCode (HWA-16), Claude Code (HWA-17) and Codex/preset (HWA-18) adapters; checked by the conformance suite.
+//
+// Precedence (the documented rule): a profile ADDS a session-scoped layer and never replaces local configuration.
+//   - Local instructions (project AGENTS.md/CLAUDE.md, the user's own harness config) load unchanged. Profile
+//     instructions come after them, framed by profileInstructionsBlock, which says local instructions take
+//     precedence where they conflict.
+//   - A local skill or command with the same name wins: the profile's is skipped with a note (status partial).
+//   - Parts the adapter cannot apply are skipped with a note (partial); nothing applicable is `unsupported`.
+//   - An adapter whose harness reads the profile only at session start answers `restart_required`.
+//   - Adapters write session-scoped state only, never global harness configuration.
+// Secrets: profiles carry `{{secret:NAME}}` references only (central never resolves them). The adapter resolves
+// them on the spoke's machine when a command is rendered at invocation (renderProfileCommand; default source
+// envSecrets: HUB_SECRET_<NAME> in the spoke's environment). Resolved values are never written to disk, sent to
+// the hub, or put in notes; an adapter that cannot render at invocation skips commands that reference secrets.
+import { createHash } from "node:crypto"
+import {
+  canonicalProfileJSON,
+  PROFILE_APPLY_LIMITS,
+  type ProfileApplyRequest,
+  type ProfileApplyResult,
+  type ProfileApplyStatus,
+  type ProfileCommand,
+  type ProfileSkill,
+  profileTemplateParts,
+  type ProfileVersionContent,
+} from "../../protocol/src/index.ts"
+
+/** sha256 hex of the canonical JSON of a version's content: what the hub sends as `digest`. */
+export function profileDigest(content: ProfileVersionContent): string {
+  return createHash("sha256").update(canonicalProfileJSON(content)).digest("hex")
+}
+
+/** What a harness adapter can apply to a running session. */
+export interface ProfileCapabilities {
+  readonly instructions: boolean
+  readonly skills: boolean
+  readonly commands: boolean
+  /** It can switch the session's model. */
+  readonly model: boolean
+  /** Applied parts take effect in the running session; false: only after the session restarts. */
+  readonly live: boolean
+  /** It renders commands when they are invoked (so secret references resolve then, on this machine). */
+  readonly renderAtInvocation: boolean
+}
+
+/** Names the session already has locally (they win over the profile's). */
+export interface ProfileLocalNames {
+  readonly skills?: Iterable<string>
+  readonly commands?: Iterable<string>
+}
+
+export interface ProfilePlan {
+  readonly status: ProfileApplyStatus
+  /** The framed instructions block to add after local instructions (absent: none to apply). */
+  readonly instructions?: string
+  readonly skills: readonly ProfileSkill[]
+  readonly commands: readonly ProfileCommand[]
+  readonly model?: string
+  readonly notes: readonly string[]
+}
+
+/** A note within the protocol's bounds: plain text of at most noteChars characters. */
+export function profileNote(text: string): string {
+  const clean = text.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ")
+  return clean.length <= PROFILE_APPLY_LIMITS.noteChars ? clean : `${clean.slice(0, PROFILE_APPLY_LIMITS.noteChars - 1)}…`
+}
+
+/** At most PROFILE_APPLY_LIMITS.notes notes (the last one says how many were left out). */
+export function boundedNotes(notes: readonly string[]): string[] {
+  const max = PROFILE_APPLY_LIMITS.notes
+  const clean = notes.map(profileNote)
+  return clean.length <= max ? clean : [...clean.slice(0, max - 1), `… ${clean.length - max + 1} more notes`]
+}
+
+/** The profile instructions as adapters add them: after local instructions, which take precedence. */
+export function profileInstructionsBlock(req: Pick<ProfileApplyRequest, "profileID" | "version" | "content">): string {
+  return [
+    `<!-- hub profile ${req.profileID} v${req.version} (session-scoped) -->`,
+    `Hub agent profile ${req.profileID} version ${req.version}, applied to this session only. Where it conflicts with local project or user instructions, the local instructions take precedence.`,
+    "",
+    req.content.instructions ?? "",
+  ].join("\n")
+}
+
+/** Secret names a template references. */
+export function templateSecrets(template: string): string[] {
+  const parts = profileTemplateParts(template)
+  if (typeof parts === "string") return []
+  return [...new Set(parts.flatMap((p) => ("secret" in p ? [p.secret] : [])))]
+}
+
+/** What to apply of a profile version, by the precedence rule above. */
+export function planProfileApplication(req: ProfileApplyRequest, options: { readonly capabilities: ProfileCapabilities; readonly local?: ProfileLocalNames }): ProfilePlan {
+  const { capabilities: can } = options
+  const { content } = req
+  const localSkills = new Set(options.local?.skills ?? [])
+  const localCommands = new Set(options.local?.commands ?? [])
+  const notes: string[] = []
+  let offered = 0
+  let usable = 0
+
+  let instructions: string | undefined
+  if (content.instructions !== undefined && content.instructions.trim() !== "") {
+    offered++
+    if (can.instructions) {
+      instructions = profileInstructionsBlock(req)
+      usable++
+    } else notes.push("instructions not supported by this harness adapter")
+  }
+
+  const skills: ProfileSkill[] = []
+  if (content.skills.length) {
+    offered++
+    if (!can.skills) notes.push("skills not supported by this harness adapter")
+    else
+      for (const skill of content.skills) {
+        if (localSkills.has(skill.name)) notes.push(`skill ${skill.name} skipped: a local skill of that name takes precedence`)
+        else skills.push(skill)
+      }
+    if (skills.length) usable++
+  }
+
+  const commands: ProfileCommand[] = []
+  if (content.commands.length) {
+    offered++
+    if (!can.commands) notes.push("commands not supported by this harness adapter")
+    else
+      for (const command of content.commands) {
+        const secrets = templateSecrets(command.template)
+        if (localCommands.has(command.name)) notes.push(`command ${command.name} skipped: a local command of that name takes precedence`)
+        else if (secrets.length && !can.renderAtInvocation) notes.push(`command ${command.name} skipped: it needs secrets (${secrets.join(", ")}) and this adapter cannot render at invocation`)
+        else commands.push(command)
+      }
+    if (commands.length) usable++
+  }
+
+  let model: string | undefined
+  if (content.model !== undefined) {
+    offered++
+    if (can.model) {
+      model = content.model
+      usable++
+    } else notes.push("model ignored: this harness adapter cannot change the model")
+  }
+
+  const status: ProfileApplyStatus = offered > 0 && usable === 0 ? "unsupported" : !can.live ? "restart_required" : notes.length ? "partial" : "applied"
+  return { status, ...(instructions !== undefined ? { instructions } : {}), skills, commands, ...(model !== undefined ? { model } : {}), notes: boundedNotes(notes) }
+}
+
+/** What an adapter's apply may report; its status (if any) and notes replace or extend the plan's. */
+export interface ProfileApplyOutcome {
+  readonly status?: ProfileApplyStatus
+  readonly notes?: readonly string[]
+}
+
+export interface ProfileApplyHandlerOptions {
+  readonly capabilities: ProfileCapabilities
+  /** The session's local skill and command names (they win over the profile's). */
+  readonly local?: (sessionID: string) => ProfileLocalNames | undefined
+  /** Writes the plan to the session's own (session-scoped) state. Throwing answers `rejected` with the reason. */
+  readonly apply: (plan: ProfilePlan, req: ProfileApplyRequest) => Promise<ProfileApplyOutcome | void>
+  /** Sessions whose last applied digest is remembered (default 1000). */
+  readonly remembered?: number
+}
+
+/** The answer to a profileApply request, echoing what it was asked to apply. */
+export function profileApplyResult(req: ProfileApplyRequest, status: ProfileApplyStatus, notes: readonly string[] = []): ProfileApplyResult {
+  const bounded = boundedNotes(notes)
+  return { sessionID: req.sessionID, profileID: req.profileID, version: req.version, digest: req.digest, status, ...(bounded.length ? { notes: bounded } : {}) }
+}
+
+/**
+ * The `profileApply` op handler for HarnessSpoke (`handlers: { profileApply: handler.handle }`, which announces the
+ * feature): checks the digest, plans by precedence, calls the adapter, and answers a valid result. A repeated
+ * request for the digest a session already applied (applied or partial) answers the same result without
+ * re-applying; restart_required, rejected and unsupported are tried again.
+ */
+export class ProfileApplyHandler {
+  private readonly options: ProfileApplyHandlerOptions
+  private readonly done = new Map<string, ProfileApplyResult>()
+
+  constructor(options: ProfileApplyHandlerOptions) {
+    this.options = options
+  }
+
+  readonly handle = async (req: ProfileApplyRequest): Promise<ProfileApplyResult> => {
+    if (profileDigest(req.content) !== req.digest) return profileApplyResult(req, "rejected", ["digest does not match the content; nothing applied"])
+    const previous = this.done.get(req.sessionID)
+    if (previous && previous.profileID === req.profileID && previous.version === req.version && previous.digest === req.digest) return previous
+    const plan = planProfileApplication(req, { capabilities: this.options.capabilities, ...(this.options.local ? { local: this.options.local(req.sessionID) ?? {} } : {}) })
+    if (plan.status === "unsupported") return profileApplyResult(req, "unsupported", plan.notes)
+    let outcome: ProfileApplyOutcome | void
+    try {
+      outcome = await this.options.apply(plan, req)
+    } catch (cause) {
+      return profileApplyResult(req, "rejected", [`adapter failed: ${cause instanceof Error ? cause.message : String(cause)}`])
+    }
+    const result = profileApplyResult(req, outcome?.status ?? plan.status, [...plan.notes, ...(outcome?.notes ?? [])])
+    this.done.delete(req.sessionID)
+    if (result.status === "applied" || result.status === "partial") {
+      this.done.set(req.sessionID, result)
+      while (this.done.size > (this.options.remembered ?? 1000)) this.done.delete(this.done.keys().next().value!)
+    }
+    return result
+  }
+
+  /** Forgets a session (it ended, or its applied state was lost). */
+  forget(sessionID: string): void {
+    this.done.delete(sessionID)
+  }
+}
+
+/** A command's secret references are not available on this machine (names only, never values). */
+export class ProfileSecretMissingError extends Error {
+  constructor(readonly missing: readonly string[]) {
+    super(`missing secret(s) ${missing.join(", ")} on this machine`)
+    this.name = "ProfileSecretMissingError"
+  }
+}
+
+/** Secrets from the spoke's environment: `{{secret:NAME}}` reads `<prefix>NAME` (default HUB_SECRET_NAME). */
+export function envSecrets(env: Readonly<Record<string, string | undefined>> = process.env, prefix = "HUB_SECRET_"): (name: string) => string | undefined {
+  return (name) => {
+    const value = env[`${prefix}${name}`]
+    return value === undefined || value === "" ? undefined : value
+  }
+}
+
+/**
+ * Renders a command at invocation on the spoke: each `{{param}}` once, literally (a value is never parsed again),
+ * each `{{secret:NAME}}` from `secret`. Exactly the template's parameters must be given.
+ */
+export function renderProfileCommand(template: string, params: Readonly<Record<string, string>>, secret: (name: string) => string | undefined): string {
+  const parts = profileTemplateParts(template)
+  if (typeof parts === "string") throw new Error(`template: ${parts}`)
+  const wanted = [...new Set(parts.flatMap((p) => ("param" in p ? [p.param] : [])))]
+  const missing = wanted.filter((name) => !Object.hasOwn(params, name))
+  if (missing.length) throw new Error(`missing parameter(s) ${missing.join(", ")}`)
+  const unknown = Object.keys(params).filter((name) => !wanted.includes(name))
+  if (unknown.length) throw new Error(`unknown parameter(s) ${unknown.map((n) => (/^[a-z][a-z0-9_]{0,39}$/.test(n) ? n : "?")).join(", ")}`)
+  const absent = [...new Set(parts.flatMap((p) => ("secret" in p && secret(p.secret) === undefined ? [p.secret] : [])))]
+  if (absent.length) throw new ProfileSecretMissingError(absent)
+  return parts.map((p) => ("text" in p ? p.text : "param" in p ? params[p.param]! : secret(p.secret)!)).join("")
+}

package/src/central/actions.ts

@@ -73,6 +73,13 @@ export interface PromptInput {
   readonly images?: readonly PromptImage[]
   /** True for the user's own prompts; agent prompts never reset the hop chain (decision wvqeuis0 §8). */
   readonly resetHops: boolean
+  /**
+   * (CON-09a) false: the user did not write this text (a Concierge proposal run as the user), so it is never the
+   * source of the session's first-prompt intent. (CON-10) "first": it is the session's first prompt by construction
+   * (a launch's prompt, even when the launch already gave the session its name as title). Absent: it is the first
+   * prompt only when the session has no real title yet.
+   */
+  readonly intent?: false | "first"
 }
 
 /** Typed input steered into the running tree. */

package/src/central/agent/acting-routes.ts

@@ -14,6 +14,7 @@ import { DELIVER_ID_MAX, DELIVERY_MODES, type DeliveryMode, type FormAnswer, for
 import type { Acting } from "./acting"
 import { AgentError } from "./errors"
 import type { AgentRoute } from "./routes"
+import { AGENT_JSON_BODY_MAX, boundedText } from "./body"
 
 // A literal: routes.ts imports this module (AGENT_PREFIX is not initialised yet when it loads).
 const PREFIX = "/api/agent/sessions/:addr"
@@ -27,7 +28,7 @@ const invalid = (message: string) => new AgentError("invalid", message)
 type Body = Record<string, unknown>
 
 async function bodyOf(request: Request, optional = false): Promise<Body> {
-  const raw = await request.text()
+  const raw = await boundedText(request, AGENT_JSON_BODY_MAX)
   if (!raw.trim() && optional) return {}
   const value: unknown = JSON.parse(raw)
   if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalid("Body must be a JSON object")

package/src/central/agent/acting-switch.ts

@@ -6,6 +6,7 @@
 //   (agent/acting.ts) calls ensureActing() first and again before the spoke request; it answers 423 paused.
 //   Reading and messaging keep working (messaging has its own switch, AgentData.messagingPaused).
 // - hubNever(): hub.json `agents.never` (already validated by config.ts), checked before every grant.
+import { boundedJson } from "./body"
 import type { Store } from "../store"
 import type { AgentActor } from "./actor"
 import type { AgentAudit } from "./audit"
@@ -82,7 +83,7 @@ export function actingSwitchRoutes(acting: ActingSwitch): AgentRoute[] {
       path: `${AGENT_PREFIX}/acting`,
       allow: {},
       async handle({ request, user, actor }) {
-        const body: unknown = await request.json()
+        const body: unknown = await boundedJson(request)
         const enabled = typeof body === "object" && body !== null && !Array.isArray(body) ? (body as Record<string, unknown>).enabled : undefined
         if (typeof enabled !== "boolean") throw new AgentError("invalid", "enabled must be true or false")
         await acting.setUserActing(user.id, actor, enabled)

package/src/central/agent/acting.ts

@@ -19,6 +19,9 @@
 // - Every outcome after the address resolves is in the agent audit: decision (allow, needs_user, forbidden,
 //   paused, rate_limited) and outcome (ok, gone, offline, unsupported, escalated, refused, failed).
 // - Races: the request answered elsewhere first is gone (410).
+// - (CON-06) preflight: a Concierge proposal is checked exactly like the act verb would check the agent, short of
+//   its grant (kill switch, tenancy, the Concierge guard, pending request/form, self-tree, prompt rules); nothing is
+//   consumed, audited or sent. When the user says go, the verb runs as the user (no grant, tenancy re-checked).
 import {
   DELIVER_TEXT_MAX,
   type Delivered,
@@ -35,7 +38,8 @@ import {
 import { type Actions, type Unsupported, unsupportedMessage } from "../actions"
 import { BusyError, type Registry } from "../registry"
 import { SpokeError } from "../spoke-ws"
-import type { PermissionRequest } from "../../status"
+import type { FormFieldSpec, PermissionRequest } from "../../status"
+import { formAnswerFieldProblem } from "./form-check"
 import type { ActingSwitch } from "./acting-switch"
 import type { AgentActor } from "./actor"
 import type { AgentAudit, AuditDecision, AuditOutcome, AuditTarget } from "./audit"
@@ -51,7 +55,9 @@ import { evaluatePermission, formatPattern, type GrantVerb, parsePattern, type P
 export type ActingRegistry = Pick<
   Registry,
   "sessionTenant" | "session" | "rootOf" | "permissionRequest" | "permissionTargets" | "formTargets" | "owner" | "supports" | "harnessOf"
->
+> &
+  /** (CON-13) The tree's live status: a pending form's fields (its schema). Without it no answer is checked. */
+  Partial<Pick<Registry, "status">>
 
 /** Why a request needs the user, as the policy saw it. */
 export interface Evaluation {
@@ -97,8 +103,20 @@ export interface ActingDeps {
   readonly newMessageID?: () => string
   /** Longest prompt a user sends (the console's limit); agents' prompts are at most DELIVER_TEXT_MAX. */
   readonly maxPromptChars?: number
+  /** (CON-04) Sessions only the user acts on (the Concierge's): agents get forbidden {policy: "concierge"}. */
+  readonly protect?: (userID: string, sessionID: string) => Promise<boolean>
+  /**
+   * (CON-13 decision, design §11.4) Whether the acting session is a Concierge session (current or past). Such an
+   * actor never executes a tap-tier approval (shell, outside folders, MCP and unknown tools, near-never) or an
+   * "always", even inside its grant: needs_user, a tap Decision. A failed read counts as yes (fail closed).
+   */
+  readonly conciergeActor?: (userID: string, sessionID: string) => Promise<boolean>
 }
 
+/** (CON-13 decision) Why the Concierge escalates a covered request. */
+export const CONCIERGE_TAP_REASON = "Shell, outside folders and tools always need the user's tap"
+export const CONCIERGE_ALWAYS_REASON = "The Concierge never answers “always”: the user decides"
+
 /** Who acts, for which user. */
 export interface Caller {
   readonly actor: AgentActor
@@ -162,6 +180,8 @@ export interface PromptInput {
   /** Agents' prompts always wake the session: false is refused. */
   readonly wake?: boolean
   readonly why?: string
+  /** (CON-09a) false: not the user's own text (a proposal run as the user): never the session's first-prompt intent. */
+  readonly intent?: false
 }
 
 /** An agent's prompt, admitted by the spoke under its provenance header. */
@@ -176,6 +196,28 @@ export interface AgentPrompted {
 /** The user's prompt: steered into the running tree, or a new turn (its reply streams to the console). */
 export type UserPrompted = { readonly sessionID: string; readonly mode: "steer"; readonly inboxID: string } | { readonly sessionID: string; readonly mode: "turn" }
 
+/** (CON-13) A pending form's schema, as an agent may read it: the fields it takes (bounded by the spoke). */
+export interface PendingForm {
+  readonly sessionID: string
+  readonly formID: string
+  /** The session in the tree that asked (a subagent's form is answered through its root). */
+  readonly askedBy: string
+  readonly title: string
+  readonly question?: true
+  readonly fields: readonly FormFieldSpec[]
+}
+
+/** (CON-06) The verbs a Concierge proposal covers, and what preflight answers about the target. */
+export type ProposalVerb = "stop" | "deny" | "prompt" | "answer"
+export interface Preflighted {
+  readonly sessionID: string
+  readonly rootID: string
+  /** The target's @name. */
+  readonly name?: string
+  /** deny: the pending request's details (when known). */
+  readonly request?: PermissionRequest
+}
+
 /** The console's prompt limit (http.ts MAX_PROMPT_CHARS; Central passes it). */
 const DEFAULT_MAX_PROMPT_CHARS = 100_000
 
@@ -258,9 +300,10 @@ export class Acting {
     const origin = this.pendingPermission(target, input.requestID)
     const always = input.always === true
     const decision: PermissionDecision = always ? "always" : "once"
+    const concierge = await this.isConcierge(caller)
     return this.act(caller, "approve", target, { requestID: input.requestID }, input.why, {
       selfTree: true,
-      choose: (usable) => this.choosePermission(usable, origin.request, always),
+      choose: (usable) => this.choosePermission(usable, origin.request, always, concierge),
       escalation: (evaluation) => ({
         verb: "approve",
         target: target.sessionID,
@@ -281,6 +324,39 @@ export class Acting {
     })
   }
 
+  /**
+   * (CON-06) Checks an agent's proposed act as the verb would, short of its grant: kill switch (paused), tenancy
+   * (not_found/offline), the Concierge guard (forbidden {policy: concierge}), the pending request or form
+   * (not_found), self-tree (forbidden), the prompt rules (invalid). Consumes, audits and sends nothing.
+   */
+  async preflight(caller: Caller, verb: ProposalVerb, addr: string, ids: { readonly requestID?: string; readonly formID?: string; readonly text?: string; readonly answer?: FormAnswer }): Promise<Preflighted> {
+    const { actor, userID } = caller
+    if (actor.kind !== "user") this.deps.acting.ensureActing(userID)
+    if (verb === "prompt" && actor.kind !== "user") {
+      const text = (ids.text ?? "").trim()
+      if (!text) throw invalid("Empty prompt")
+      if (text.length > DELIVER_TEXT_MAX) throw invalid(`Prompt longer than ${DELIVER_TEXT_MAX} characters`)
+    }
+    const target = this.locate(userID, addr)
+    if (actor.kind !== "user") await this.guard(userID, target)
+    let request: PermissionRequest | undefined
+    if (verb === "deny") request = this.pendingPermission(target, ids.requestID ?? "").request
+    if (verb === "answer" && !this.deps.registry.formTargets(target.rootID, ids.formID ?? "").length) throw new AgentError("not_found", `No pending form ${ids.formID} in this session's tree`)
+    if (verb === "answer" && ids.answer !== undefined && actor.kind !== "user") this.checkAnswer(target, ids.formID ?? "", ids.answer)
+    if ((verb === "deny" || verb === "answer") && actor.kind === "session" && (this.deps.registry.rootOf(actor.sessionID) ?? actor.sessionID) === target.rootID) {
+      throw forbidden("A session never answers requests in its own session tree")
+    }
+    if (verb === "prompt" && actor.kind !== "user") {
+      if (target.parentID) throw invalid("Prompts go to root sessions, not subagent sessions")
+      if (actor.kind === "session" && actor.sessionID === target.sessionID) throw invalid("A session never prompts itself")
+    }
+    let name: string | undefined
+    try {
+      name = this.deps.directory.resolveOne(userID, target.sessionID).name
+    } catch {}
+    return { sessionID: target.sessionID, rootID: target.rootID, ...(name ? { name } : {}), ...(request ? { request } : {}) }
+  }
+
   /** Rejects a pending permission request (any request: a reject is always safe), with an optional reason. */
   async deny(caller: Caller, addr: string, input: DenyInput): Promise<Denied> {
     const target = this.locate(caller.userID, addr)
@@ -306,6 +382,8 @@ export class Acting {
     if (!this.deps.registry.formTargets(target.rootID, input.formID).length) throw new AgentError("not_found", `No pending form ${input.formID} in this session's tree`)
     return this.act(caller, "answer", target, { formID: input.formID }, input.why, {
       selfTree: true,
+      // (CON-13) Checked after the grant's checks (a holder without the verb learns nothing of the form), before it runs.
+      check: () => (input.cancel || caller.actor.kind === "user" ? undefined : this.checkAnswer(target, input.formID, input.answer)),
       run: async (grant) => {
         const form = input.cancel
           ? { rootID: target.rootID, formID: input.formID, cancel: true as const }
@@ -318,6 +396,88 @@ export class Acting {
     })
   }
 
+  /**
+   * (CON-13) A pending form's schema in the addressed session's tree: its title and fields (keys, types, options,
+   * required…), never anything else of the session. Checked like the answer verb short of its grant: kill switch,
+   * tenancy, the Concierge guard, the pending form, self-tree. Consumes, audits and sends nothing.
+   */
+  async form(caller: Caller, addr: string, formID: string): Promise<PendingForm> {
+    const { actor, userID } = caller
+    if (actor.kind !== "user") this.deps.acting.ensureActing(userID)
+    const target = this.locate(userID, addr)
+    if (actor.kind !== "user") await this.guard(userID, target)
+    if (!this.deps.registry.formTargets(target.rootID, formID).length) throw new AgentError("not_found", `No pending form ${formID} in this session's tree`)
+    if (actor.kind === "session" && (this.deps.registry.rootOf(actor.sessionID) ?? actor.sessionID) === target.rootID) throw forbidden("A session never answers requests in its own session tree")
+    const found = this.formBlocker(target, formID)
+    return {
+      sessionID: target.sessionID,
+      formID,
+      askedBy: found?.sessionID ?? target.sessionID,
+      title: found?.blocker.summary ?? "question",
+      ...(found?.blocker.question ? { question: true as const } : {}),
+      fields: found?.blocker.fields ?? [],
+    }
+  }
+
+  /**
+   * (CON-13) Whether the agent's grant would approve this pending request once, as approve() decides it: kill switch,
+   * tenancy, the Concierge guard, pending in the tree, self-tree, a usable grant with approve, then every never rule
+   * and the allow rules (choosePermission). Never acts, consumes, audits or escalates; any refusal is false. The
+   * hourly cap is not counted (the act may still be rate limited). The board's `inGrant` (the model never decides).
+   */
+  async covers(caller: Caller, addr: string, requestID: string): Promise<boolean> {
+    const { actor, userID } = caller
+    if (actor.kind === "user") return false
+    try {
+      this.deps.acting.ensureActing(userID)
+      const target = this.locate(userID, addr)
+      await this.guard(userID, target)
+      const { request } = this.pendingPermission(target, requestID)
+      if (actor.kind === "session" && (this.deps.registry.rootOf(actor.sessionID) ?? actor.sessionID) === target.rootID) return false
+      const usable = await this.deps.grants.usable(actor, "approve", { directory: target.directory })
+      if (!usable.length) return false
+      this.choosePermission(usable, request, false)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * (CON-13 decision) The board's facts for a pending request: `inGrant` (covers(): the policy's truth) and `auto`:
+   * inGrant and not the tap risk tier, i.e. the Concierge may approve it once without the user.
+   */
+  async coverage(caller: Caller, addr: string, requestID: string): Promise<{ inGrant: boolean; auto: boolean }> {
+    const inGrant = await this.covers(caller, addr, requestID)
+    if (!inGrant) return { inGrant, auto: false }
+    try {
+      const target = this.locate(caller.userID, addr)
+      const { request } = this.pendingPermission(target, requestID)
+      if (!request) return { inGrant, auto: false }
+      const usable = await this.deps.grants.usable(caller.actor, "approve", { directory: target.directory })
+      const never = [...this.deps.acting.hubNever(), ...usable.flatMap((g) => patterns(g.permissions.never))]
+      return { inGrant, auto: riskTier(request, never) !== "tap" }
+    } catch {
+      return { inGrant, auto: false }
+    }
+  }
+
+  /** The form's blocker in the target's tree (with the session that shows it), when the registry reports it. */
+  private formBlocker(target: Located, formID: string) {
+    for (const s of this.deps.registry.status?.(target.rootID) ?? []) {
+      const blocker = s.blockers.find((b) => b.kind === "form" && b.id === formID)
+      if (blocker) return { sessionID: s.id, blocker }
+    }
+    return undefined
+  }
+
+  /** (CON-13) 400 invalid with the precise problem when an agent's answer does not fit the form's fields. */
+  private checkAnswer(target: Located, formID: string, answer: FormAnswer): void {
+    const fields = this.formBlocker(target, formID)?.blocker.fields
+    const problem = fields ? formAnswerFieldProblem(fields, answer) : undefined
+    if (problem) throw new AgentError("invalid", problem, { hint: "Read the form's fields first (concierge_form, or show) and answer with their keys and option values" })
+  }
+
   /** Stops the addressed session's tree. */
   async stop(caller: Caller, addr: string, input: StopInput): Promise<StoppedSession> {
     const target = this.locate(caller.userID, addr)
@@ -361,16 +521,16 @@ export class Acting {
     }
     return this.act(caller, "prompt", target, {}, input.why, {
       run: async (grant) => {
-        if (!grant) return this.userPrompt(target.sessionID, text, images)
+        if (!grant) return this.userPrompt(target.sessionID, text, images, input.intent)
         return this.agentPrompt(caller, addr, target.sessionID, text, grant, input.delivery)
       },
     })
   }
 
-  private async userPrompt(sessionID: string, text: string, images: readonly PromptImage[] | undefined): Promise<UserPrompted> {
+  private async userPrompt(sessionID: string, text: string, images: readonly PromptImage[] | undefined, intent?: false): Promise<UserPrompted> {
     let started
     try {
-      started = await this.deps.actions.prompt({ sessionID, text, ...(images ? { images } : {}), resetHops: true })
+      started = await this.deps.actions.prompt({ sessionID, text, ...(images ? { images } : {}), resetHops: true, ...(intent === false ? { intent } : {}) })
     } catch (cause) {
       if (cause instanceof BusyError) throw new AgentError("rate_limited", "Another turn is starting in this session", { hint: "Try again", extra: { retryAfter: 1 } })
       throw cause
@@ -427,6 +587,8 @@ export class Acting {
       /** The grant to act under (default: the newest usable); throws NeedsUser or forbidden. */
       readonly choose?: (usable: Grant[]) => Grant
       readonly escalation?: (evaluation: Evaluation) => Omit<Escalation, "userID" | "actor">
+      /** (CON-13) Input checks that need the target (throw invalid): after the grant's checks, before it is consumed. */
+      readonly check?: () => void
       readonly run: (grant: Grant | undefined) => Promise<T>
     },
   ): Promise<T> {
@@ -446,16 +608,21 @@ export class Acting {
     try {
       if (actor.kind !== "user") {
         acting.ensureActing(userID)
+        await this.guard(userID, target)
         const usable = await grants.usable(actor, verb, { directory: target.directory })
         if (!usable.length) throw forbidden(`No grant lets this ${actor.kind} ${verb} in this session`)
         if (plan.selfTree && actor.kind === "session" && (this.deps.registry.rootOf(actor.sessionID) ?? actor.sessionID) === target.rootID) {
           throw forbidden("A session never answers requests in its own session tree")
         }
         grant = plan.choose ? plan.choose(usable) : usable[0]!
+        plan.check?.()
         await grants.consume(grant)
         acting.ensureActing(userID)
       }
-      const result = await plan.run(grant)
+      // (CON-13) What the spoke said when it refused, never a bare 500.
+      const result = await plan.run(grant).catch((cause: unknown) => {
+        throw refusedBySession(cause)
+      })
       await record("allow", "ok", why)
       return result
     } catch (cause) {
@@ -474,6 +641,13 @@ export class Acting {
     }
   }
 
+  /** (CON-04) Sessions only the user acts on (the Concierge's): agents are forbidden {policy: concierge}. */
+  private async guard(userID: string, target: Located): Promise<void> {
+    if (this.deps.protect && ((await this.deps.protect(userID, target.rootID)) || (await this.deps.protect(userID, target.sessionID)))) {
+      throw new AgentError("forbidden", "Only the user acts on the Concierge", { extra: { policy: "concierge" } })
+    }
+  }
+
   /** Hands the escalation to the hook: undefined when there is none or it failed. */
   private async escalate(caller: Caller, escalation: Omit<Escalation, "userID" | "actor"> | undefined): Promise<{ decisionID?: string } | undefined> {
     if (!this.deps.escalate || !escalation) return undefined
@@ -485,10 +659,25 @@ export class Acting {
     }
   }
 
-  /** The grant that covers the request, after every never rule; NeedsUser when none does. */
-  private choosePermission(usable: Grant[], request: PermissionRequest | undefined, always: boolean): Grant {
+  /** (CON-13 decision) The actor is a Concierge session (current or past); a failed read counts as yes. */
+  private async isConcierge(caller: Caller): Promise<boolean> {
+    const { actor } = caller
+    if (actor.kind !== "session" || !this.deps.conciergeActor) return false
+    try {
+      return await this.deps.conciergeActor(caller.userID, actor.sessionID)
+    } catch {
+      return true
+    }
+  }
+
+  /**
+   * The grant that covers the request, after every never rule; NeedsUser when none does. (CON-13 decision)
+   * `concierge`: a Concierge actor's "always", or a covered request of the tap risk tier, is NeedsUser at tap tier.
+   */
+  private choosePermission(usable: Grant[], request: PermissionRequest | undefined, always: boolean, concierge = false): Grant {
     const hubNever = this.deps.acting.hubNever()
     const ids = usable.map((g) => g.id)
+    if (concierge && always) throw new NeedsUser({ verdict: "outside", reason: CONCIERGE_ALWAYS_REASON, tier: "tap", grants: ids })
     if (!request) throw new NeedsUser({ verdict: "outside", reason: "The request's details are unknown", tier: "tap", grants: ids })
     const rules = usable.map((g) => ({ grant: g, allow: patterns(g.permissions.allow), never: patterns(g.permissions.never) }))
     for (const form of neverForms(request)) {
@@ -504,7 +693,10 @@ export class Acting {
     let reason: string | undefined
     for (const { grant, allow, never } of rules) {
       const verdict = evaluatePermission(request, { grant: { allow, never }, hubNever, always, allowAlways: grant.allowAlways })
-      if (verdict.verdict === "allow") return grant
+      if (verdict.verdict === "allow") {
+        if (concierge && riskTier(request, allNever) === "tap") throw new NeedsUser({ verdict: "outside", reason: CONCIERGE_TAP_REASON, tier: "tap", grants: ids })
+        return grant
+      }
       if (verdict.verdict === "outside") reason ??= verdict.reason
     }
     throw new NeedsUser({ verdict: "outside", reason: reason ?? "Outside the grant", tier: riskTier(request, allNever), grants: ids })
@@ -570,12 +762,25 @@ function bounded(text: string, max: number): string {
 }
 
 const gone = () => new AgentError("gone", "Already answered, expired or ended")
+
+/**
+ * (CON-13) The session's harness refused the act (OpenCode said why, e.g. "Unknown form field: Questions"): 400
+ * invalid with its words (bounded, one line), never a 500 "Internal error" a model would repeat to the user. The
+ * audit keeps it as allowed · failed. A disconnect stays offline; hub errors pass through.
+ */
+export function refusedBySession(cause: unknown): unknown {
+  if (cause instanceof AgentError || cause instanceof NeedsUser || cause instanceof BusyError) return cause
+  if (cause instanceof SpokeError && /disconnected/i.test(cause.message)) return new AgentError("offline", "The session's spoke disconnected")
+  const said = sanitizeText(cause instanceof Error ? cause.message : String(cause)).replace(/\s+/g, " ").trim().slice(0, 300) || "no reason given"
+  return new AgentError("invalid", `The session refused it: ${said}`, { extra: { refusedBy: "session" } })
+}
 /** The spoke lacks the core op: unsupported {feature, harness}, as the read routes answer. */
 const unsupported = ({ feature, harness }: Unsupported) => new AgentError("unsupported", unsupportedMessage({ feature, harness }), { extra: { feature, harness } })
 
 /** An error's audit decision and outcome (shared with the launch routes). */
 export function auditOf(cause: unknown): [AuditDecision, AuditOutcome] {
   if (!(cause instanceof AgentError)) return ["allow", "failed"]
+  if (cause.options.extra?.refusedBy === "session") return ["allow", "failed"]
   switch (cause.code) {
     case "paused":
       return ["paused", "refused"]