@sema-agent/core 7.6.0 → 7.6.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 7.6.1 — 2026-09-07
+
+Patch: three bug fixes from the 7.6.0 field and black-box rounds (#608 P1, #609, #610) and the first refactor wave (design/393 S0, #594, #598), all byte-invariant on the runtime except where named. One public d.ts narrowing is called out below.
+
+### Fixed
+- **#608 (P1)** — the file store's single-writer directory lock judged its owner by pid number alone, so a dead holder's pid recycled to an unrelated process kept the lock "in use" and every engine start failed with `store.dir_in_use` until an operator deleted the lock by hand (the cli production shape: two LOCK files reading `79814`, no trailing newline). The lock record now carries a process fingerprint `{pid, startedAtMs, startedSinceBootMs, host, v: 2}`; liveness is "pid alive AND not falsified by BOTH clocks" (a wall-clock start and an uptime-relative start — each unreliable exactly where the other is sound); a record from another host, or one without a comparable measure, keeps the pre-fingerprint verdict (a false "dead" reclaims a working writer's directory; a false "live" costs one refusal an operator can act on); a reboot the host has outlived is the uptime measure's second way of saying gone. Bare-pid locks are read by pid and rewritten on reclaim. What the guards cannot see (a same-boot backward clock correction hiding a genuine reuse; a reboot the machine has since outlived with no comparable measure) falls back to the pre-existing refusal, never a wrong reclaim — a boot-scoped kernel start token is the design-level fix (#612).
+- **#609** — a resume of a parked policy ask that still spells the retired decision facts (`settledBy` / `approver` as top-level keys) is refused before the CAS with a coded error naming the `hostDecision` shape, instead of having the keys silently ignored (found by the 7.6.0 black-box round, G2.b).
+- **#610** — every connect-phase MCP failure reports `delivered: "no"` — the dial has dispatched nothing of the caller's, so the verdict is a fact, not the in-flight guess; the two kinds a server itself answered (`protocol`, `http_status`) keep the table verdict. One verdict table (`DELIVERED_BY_KIND`, fenced over the closed set) replaces the per-row spellings. A stdio child that exits before the handshake is now `connection_closed / no` (was `unknown`); a 401 endpoint stays `http_status / unknown`; the request phase is unchanged. The dial's `no` promises that no call of the caller's was dispatched — it does not promise that no user data crossed the line during the handshake's elicitation (#611).
+- **#594-b** — the #594 station relocation had put one microtask between the fold and the lanes (and one more inside the screening wrapper), so an org rule cleared on that tick was read as absent and a call 7.6.0 denied was let through; the three station-group seams (screening→fold, fold→lanes, lanes→exit) are back to the one-body form's await boundaries — the next group runs inside the previous group's continuation via a `GatePass.afterFold` seat. Five boundary pins record the microtask counts against the 7.6.0 tree.
+- 7.6.0 carry-over disclosure: the D-8 refusal text `Resume it via checkpointToken` became `Resume it via the pause's token` (wording only).
+
+### BREAKING (d.ts face only — runtime unchanged)
+- Option types and orchestration entry points that used to name the `Runner` CLASS for their `runner` member / parameter (`TaskServerOptions`, `SubagentToolOptions`, `SendMessageToolOptions`, `RunWorkflowToolDeps`, `warmResume`, `runGoal`, `runCascade`, `runRepairLoop`, `verify*`, `runWithTeacher`, `startWorkflow`, `runWorkflow`) now name **`RunnerSelfSeat`** — the one seat the Runner implements and every consumer names (`sessions`, `runTask`, `runTaskStream`, `resume`, `resumeStream`, `agentCatalog`, `emitTaskOutcome`, `gateBaseline`). A host that read `opts.runner.swapModels` or `opts.runner.sideQuery` THROUGH an option type no longer type-checks; call them on the Runner instance it constructed. No shipped consumer does (server calls `swapModels` on its own instances). Passing a `Runner` where a seat is expected still compiles.
+
+### Changed (refactor wave 1 — byte-invariant on the runtime)
+- **design/393 S0** — the run loop's seven contract declarations move down to `contracts.ts`; runtask.ts takes its contracts from their declaring modules (orchestrator contract edges 2→0; G2 exemptions 3→1); the G5 phase-api gate is driven by a `PHASE_FAMILIES` table; LAYERING gains the "run lanes" stratum. runtask.ts 12 215 → 11 946 lines. dist `runtask.js` differs only in import lines.
+- **#594** — the 23 gate stations (+4 exits) leave hooks.ts for the three-layer shape: `gate-fold.ts` (L1, the policy fold), `gate-lanes.ts` (L1, the org + ask-resolution lanes), `runner/gate-exit.ts` (L0, the exits + the one mint); hooks.ts keeps only the hook machinery and a six-call dispatch; `GatePass` is the one record the three read and write. hooks.ts 4 047 → 2 291 lines. Station-file closed-set pin + wiring pin. Words, order, deny layers, settlement kinds: unchanged and pinned.
+- **#598** — the 7 721-line public type hub `types.ts` becomes a 54-line re-export hub over fourteen layer-0 domain modules (`model-seat`, `task-spec`, `tool-spec`, `hands-band`, `agent-definition`, `mcp-server-spec`, `task-limits`, `task-result`, `task-event`, `task-stream`, `runtime-caps`, `delegation-frames`, `runner-deps`, `engine-notice`); every import path and the public export surface are byte-identical; a re-export closed-set pin refuses a declaration re-appearing in the hub.
+
+### Added
+- `processFingerprint(pid?)`, `isProcessLive(record)`, `type ProcessFingerprint` — the file store's process-identity pair, exported for a host's own liveness arm.
+- `type RunnerSelfSeat`.
+
+### Unchanged and pinned
+- Public export surface: 7.6.0's 2 098 names plus the four above, zero removed. Wire frames, the durable park row, the 23 gate stations, `TaskResult.terminal`, the MCP failure record's kinds: unchanged.
+
 ## 7.6.0 — 2026-09-07
 
 **BREAKING.** design/390 S6 (three slices, merged): the tool gate's settlement/origin words become ONE `GateOutcome` record, `TaskResult` becomes ONE terminal record, MCP failures become ONE structural record with a delivery verdict, and the durable off switch becomes a word. Every consumer that read the retired keys must migrate (server 7.64.0, cli/client-core, web-admin, desktop — the criteria post lists the frames old→new).

package/dist/agents/agent-transcript-tool.d.ts

@@ -1,10 +1,10 @@
 import { Type } from "typebox";
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 /** Model-facing name of the child-transcript read tool (residual lane C). */
 export declare const AGENT_TRANSCRIPT_TOOL_NAME = "AgentTranscript";
 export interface AgentTranscriptToolOptions {
     /** Runner whose `sessions` store holds the child's persisted history. */
-    runner: Runner;
+    runner: RunnerSelfSeat;
     /** The unified registry the background Agent lane registered its a* handles in (scopes reads to lineage). */
     registry: import("../core/task-registry.js").TaskRegistry;
     /** design/151 S1b: the durable ledger — when the live row/retain entry is gone (restart, terminal GC,

package/dist/agents/cascade.d.ts

@@ -1,5 +1,4 @@
-import type { Runner } from "../core/runner/runtask.js";
-import type { RunInternals } from "../core/runner/prepare-task.js";
+import type { RunInternals, RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { ModelRef, TaskResult, TaskSpec, TaskStatus } from "../core/types.js";
 /**
  * Quality-gate cascade (design/27). Run the SAME task across a ladder of models (cheapest → strongest);
@@ -154,7 +153,7 @@ export interface CascadeRunResult extends TaskResult {
  * (`effect: "write"`), those execute once PER rung — ensure idempotency, or gate before the side effect
  * (e.g. a structured-output gate). `TaskSpec` never guaranteed idempotency; cascade makes it explicit.
  */
-export declare function runCascade(runner: Runner, spec: TaskSpec, config: CascadeConfig, 
+export declare function runCascade(runner: RunnerSelfSeat, spec: TaskSpec, config: CascadeConfig, 
 /**
  * The TRUSTED, run-scoped internals channel — the same object `Runner.runTask` takes as its second
  * argument — forwarded to EVERY rung under the composition forward contract (identity, with the one

package/dist/agents/repair-loop.d.ts

@@ -1,4 +1,4 @@
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { TaskSpec } from "../core/types.js";
 import type { ExecutionEnv } from "../internal/harness-types.js";
 import type { VerificationResult } from "./verify.js";
@@ -278,4 +278,4 @@ export declare function terminalForTier(oracle: OracleResult): RepairTerminal |
  * SAFE-tier: the projection caps every PASS at `candidate_only` — this NEVER auto-accepts. `runRepairLoop` is a
  * SIBLING of {@link verifyCompleted}: it composes over `runner.runTask` and never touches the Runner core.
  */
-export declare function runRepairLoop(runner: Runner, implSpec: TaskSpec, config: RepairLoopConfig): Promise<RepairResult>;
+export declare function runRepairLoop(runner: RunnerSelfSeat, implSpec: TaskSpec, config: RepairLoopConfig): Promise<RepairResult>;

package/dist/agents/retain-ledger.d.ts

@@ -1,6 +1,5 @@
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunInternals, RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { TaskSpec } from "../core/types.js";
-import type { RunInternals } from "../core/runner/prepare-task.js";
 /** design/122 D2 — per-child resume cap (default 8): a child can be revived at most this many times. */
 export declare const SUBAGENT_RESUME_CAP = 8;
 /**
@@ -25,7 +24,7 @@ export interface SubagentRetainEntry {
      * resume.evicted, the 1.283 ruling). Lifetime: the entry's `release` closure already captures the same
      * runner, so this adds no new retention class.
      */
-    runner?: Runner;
+    runner?: RunnerSelfSeat;
     agentName?: string;
     /** fix-C5: PER-ENTRY retain TTL override (ms). A SESSION-scoped ledger is shared by two purposes with
      *  different windows (failure-evidence retain = FAILED_SESSION_RETAIN_TTL_MS vs a session-scoped bg

package/dist/agents/send-message-tool.d.ts

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
 import { type ToolCtxEnricher } from "../core/tools.js";
 import { type TaskAccess } from "../core/task-registry.js";
@@ -12,7 +12,7 @@ import { type PeerAdmissionConfig, type PeerInboundChainRef, type PeerSelfRef }
 export declare const SEND_MESSAGE_TOOL_NAME = "SendMessage";
 export interface SendMessageToolOptions {
     /** Runner used to execute the resumed child run (the design/122 resume face's delegation runner). */
-    runner: Runner;
+    runner: RunnerSelfSeat;
     /** The unified task registry the background Agent lane registered its a* handles in. */
     registry: import("../core/task-registry.js").TaskRegistry;
     /** design/122 D1 — the parent run's retain ledger (present only when `TaskSpec.retainSubagentSessions`

package/dist/agents/session-util.d.ts

@@ -1,7 +1,7 @@
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 /**
  * Release a throwaway session, swallowing errors — best-effort cleanup for the verifier/cascade-rung
  * sessions that agents spin up and discard. Always call this in a `finally` so a throwing `runTask`
  * result handler or caller hook (`onRung`/`onRound`) can't leak the session.
  */
-export declare function releaseSession(runner: Runner, sessionId: string): Promise<void>;
+export declare function releaseSession(runner: RunnerSelfSeat, sessionId: string): Promise<void>;

package/dist/agents/subagent.d.ts

@@ -1,7 +1,6 @@
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunInternals, RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { AgentDefinition, Model, ModelRef, TaskLimits, TerminalCause, ToolSpec } from "../core/types.js";
 import { type ExecutionEnv } from "../internal/harness.js";
-import type { RunInternals } from "../core/runner/prepare-task.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
 import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js";
 /**
@@ -433,7 +432,7 @@ export declare function markerFragment(): string;
 export declare function createSubagentResume(deps: {
     ledger: SubagentRetainLedger | undefined;
     parentToolCallId: string;
-    runner: Runner;
+    runner: RunnerSelfSeat;
     notify?: (n: TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;
@@ -616,7 +615,7 @@ export interface SubagentToolOptions {
      * .jsonl` + a `.meta.json` sidecar), so "the child conversation is readable afterwards" is a
      * property CC never makes conditional on a store tier.
      */
-    runner: Runner;
+    runner: RunnerSelfSeat;
     /**
      * design/115 P3 — background sub-agents (CC `run_in_background`). When set, the tool exposes the
      * `run_in_background` parameter: the call returns an `a*` task_id immediately, the child runs

package/dist/agents/teacher.d.ts

@@ -1,4 +1,4 @@
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import { type StrategyOrigin, type StrategyStore, type StrategyStoreIncident } from "../core/strategy-store.js";
 import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
 /**
@@ -156,4 +156,4 @@ export declare function parseTeacherAdvice(text: string): TeacherAdvice;
  * completed output (catches "passes but semantically wrong"). Correction-then-takeover, with hard
  * cost guards (escalation cap, teacher-spend ratio, bounded teacher turns).
  */
-export declare function runWithTeacher(runner: Runner, studentSpec: TaskSpec, teacher?: TeacherConfig): Promise<TeacherRunResult>;
+export declare function runWithTeacher(runner: RunnerSelfSeat, studentSpec: TaskSpec, teacher?: TeacherConfig): Promise<TeacherRunResult>;

package/dist/agents/team.d.ts

@@ -1,4 +1,4 @@
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { McpServerSpec, ModelRef, ModelRole, TaskSpec, ToolSpec } from "../core/types.js";
 import type { CheckpointGate, CheckpointToken } from "../core/checkpoint-store.js";
 export interface TeamMember {
@@ -59,7 +59,7 @@ export type TeamEvent = {
     type: "done";
 };
 export interface TeamDiscussionOptions {
-    runner: Runner;
+    runner: RunnerSelfSeat;
     /** Default model for members / synthesizer without their own. If omitted, members resolve the
      *  `team` role and the synthesizer the `synthesize` role (both fall back to `default`). */
     model?: ModelRef;

package/dist/agents/verify.d.ts

@@ -1,6 +1,5 @@
 import { Type, type Static } from "typebox";
-import type { Runner, ResumeTaskConfig } from "../core/runner/runtask.js";
-import type { RunInternals } from "../core/runner/prepare-task.js";
+import type { ResumeTaskConfig, RunInternals, RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { CheckpointGate, CheckpointToken, ResumeOutcome } from "../core/checkpoint-store.js";
 import type { ModelRef, TaskResult, TaskSpec, TaskStatus, ToolSpec } from "../core/types.js";
 /**
@@ -242,7 +241,7 @@ export interface VerificationResult extends TaskResult {
  * override is given, the verifier uses {@link STATIC_VERIFICATION_PROMPT} (read the diff/results; don't try
  * to execute — that was L2's job), avoiding the "PARTIAL on everything" failure in a read-only sandbox.
  */
-export declare function verifyCompleted(runner: Runner, result: TaskResult, specBase: ResumeTaskConfig, objective: string, config: VerifyConfig, 
+export declare function verifyCompleted(runner: RunnerSelfSeat, result: TaskResult, specBase: ResumeTaskConfig, objective: string, config: VerifyConfig, 
 /**
  * The TRUSTED, run-scoped internals channel — the same object `Runner.runTask` takes as its second
  * argument — forwarded to EVERY leg this gate drives under the composition forward contract (identity,
@@ -303,7 +302,7 @@ internals?: RunInternals): Promise<VerificationResult>;
  * failed-with-token (verdict `unverified`); the caller approves and calls {@link resumeWithVerification}
  * to resume AND verify (design/51 P1-b: the durable + HITL + verify integration).
  */
-export declare function runWithVerification(runner: Runner, implSpec: TaskSpec, config?: VerifyConfig, 
+export declare function runWithVerification(runner: RunnerSelfSeat, implSpec: TaskSpec, config?: VerifyConfig, 
 /** The trusted run-scoped internals channel, forwarded UNCHANGED to every leg this entry drives —
  *  the implementation run, then (on completion) the verifier + fix legs of the gate. Full contract,
  *  including the attribution and forwarded-whole rules, on {@link verifyCompleted}. Absent ⇒ every
@@ -324,7 +323,7 @@ internals?: RunInternals): Promise<VerificationResult>;
  * after approval, so a pre-suspend diff would grade stale code. The verifier already verifies the current working
  * tree (verifierObjective), so dropping the stale diff closes the timing window.
  */
-export declare function resumeWithVerification(runner: Runner, token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, objective: string, config?: VerifyConfig, 
+export declare function resumeWithVerification(runner: RunnerSelfSeat, token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, objective: string, config?: VerifyConfig, 
 /** The trusted run-scoped internals channel, forwarded UNCHANGED to every leg this entry drives —
  *  `Runner.resume`'s own internals argument for the RESUMED implementation leg, then (on completion)
  *  the verifier + fix legs of the gate. Note that this seat carries the resume-path duty of the same
@@ -344,7 +343,7 @@ export interface DeveloperTaskConfig extends VerifyConfig {
  * Pair with a role map that gives a strong implementation model and cheaper helper/verifier models for
  * "auto model selection" (design/28 §3.2): `roles: { default: strong, subagent: cheap, verifier: strong }`.
  */
-export declare function runDeveloperTask(runner: Runner, spec: TaskSpec, config?: DeveloperTaskConfig, 
+export declare function runDeveloperTask(runner: RunnerSelfSeat, spec: TaskSpec, config?: DeveloperTaskConfig, 
 /** The trusted run-scoped internals channel, forwarded UNCHANGED to every leg this entry drives — in
  *  BOTH arms: the lone implementation run when `verify: false`, and the whole gate otherwise. The two
  *  arms differ in ONE respect: the gate's door refusal of `isolation` (see {@link verifyCompleted})

package/dist/core/agent-definition.d.ts

@@ -0,0 +1,172 @@
+/**
+ * A delegated AGENT's definition and the skills it may mount: `AgentDefinition` (the agent a subagent
+ * tool spawns), `SkillManifest` (a skill's on-disk front matter) and `SkillSpec` (the wired form the
+ * runner mounts). Layer 0 vocabulary; `types.ts` re-exports the three, so no consumer's import changes.
+ */
+import type { ThinkingLevel } from "../internal/harness.js";
+import type { ModelRef } from "./model-seat.js";
+import type { TaskSpec } from "./task-spec.js";
+/**
+ * A declarative, reusable named sub-agent (design/38 1B). Hand a set to {@link createSubagentTool} and the
+ * model picks one (by `whenToUse`) to delegate to; the chosen definition's config builds the child task.
+ *
+ * **Deployment-side config, NOT user input** — `systemPrompt`/`allowTools` shape what the sub-agent can do
+ * and see, so they must be set by the deployment, never taken from an end-user message.
+ */
+export interface AgentDefinition {
+    /** Stable identifier + the value the delegation tool's `agent` parameter selects. Must be unique. */
+    name: string;
+    /** Guidance shown to the model for WHEN to pick this agent (listed in the delegation tool's description). */
+    whenToUse?: string;
+    /**
+     * F4 (CC 2.1.198 parity, `whenToUseLean` — 锚 pretty.js:409174 `rbm` + selection `tIl` :453029
+     * `(lean && e.whenToUseLean) || e.whenToUse`): a SHORT variant of {@link whenToUse} preferred on
+     * lean-prompt surfaces. sema posture: the engine runs the CC lean-prompt arm wholesale (web.ts
+     * lean-card precedent), so roster listings/descriptions prefer this text whenever present;
+     * {@link whenToUse} remains the fallback. Optional — a single-text agent behaves exactly as before.
+     */
+    whenToUseLean?: string;
+    /** Tool allowlist over the delegation pool (`["*"]` = all). Replaces (does not merge with) the tool's
+     *  own `allowTools`/`denyTools` when this agent is selected. F1 (CC parity): unlike the TOOL-level
+     *  allow/deny (which never filters the nested delegation tool — that stays `maxDepth`-governed), a
+     *  PER-AGENT allow/deny ALSO governs the nested delegation tool: an agent whose allow/deny excludes
+     *  the delegation tool's name cannot re-delegate (CC Explore/Plan `disallowedTools` include Agent,
+     *  pretty.js:409189/486948). */
+    allowTools?: string[];
+    /** Tool denylist (a deny always wins). See {@link allowTools} for the per-agent delegation-tool note. */
+    denyTools?: string[];
+    /**
+     * F7 (CC 2.1.198 parity, per-agent `skills` — 锚 pretty.js:422126 `e.skills ?? []`, GA/ungated in 198:
+     * CC preloads each named skill's prompt content into the child's opening messages, warning on misses).
+     * sema shape: full {@link SkillSpec} objects (sema has no ambient skill registry to resolve bare names
+     * against) threaded into the chosen child's `TaskSpec.skills` — disclosed in its `<skills>` block +
+     * invocable via the `skill` tool. Deployment-trusted, same trust tier as `systemPrompt`.
+     */
+    skills?: SkillSpec[];
+    /**
+     * F7 (CC 2.1.198 parity, per-agent `background` — 锚 pretty.js:453611 `H.background===!0` OR-ed into
+     * the background predicate, GA/ungated): `true` = this agent ALWAYS launches on the background lane
+     * (an omitted `run_in_background` no longer means sync, and the per-call parameter cannot force sync —
+     * CC-same OR semantics). Requires the delegation tool's `background` surface; without one the child
+     * runs synchronously (CC-same quiet fallback — CC's env kill-switch arm, :453611 `&& !sJt`).
+     */
+    background?: boolean;
+    /**
+     * F7 (CC 2.1.198 parity, per-agent `isolation` — 锚 pretty.js:453599 `z = a ?? H.isolation`, GA):
+     * default isolation for this agent; an explicit per-call `isolation` argument wins. sema supports
+     * `"worktree"` (CC's `"remote"` arm is a claude.ai-session concern, not ported).
+     */
+    isolation?: "worktree";
+    /** Model for this agent. **Omit to INHERIT the caller's current model** (design/38 1B finding 7) — the
+     *  recommended default; a concrete `ModelRef` pins it instead. */
+    model?: ModelRef;
+    /** Thinking level for this agent. **Omit to INHERIT the caller's current thinking level** (the model
+     *  companion above — a mid-run degrade/boost on the parent carries into new children); a concrete
+     *  level pins it instead. */
+    thinking?: ThinkingLevel;
+    /** System prompt / persona for this agent. Falls back to the delegation tool's `systemPrompt`. */
+    systemPrompt?: string;
+    /** Per-agent turn cap. Falls back to the delegation tool's `limits.maxTurns`. Must be POSITIVE: a
+     *  non-positive/non-finite value is ignored (CLS-A-3) rather than folded in, because downstream an
+     *  explicit `0` DISABLES the turn cap — the opposite of the tightening this field expresses. */
+    maxTurns?: number;
+    /** Long-term memory scope for this agent (same shape as {@link TaskSpec.memory}). */
+    memory?: TaskSpec["memory"];
+    /**
+     * This agent's own {@link TaskSpec.memoryPersistenceCapable} declaration — the same three-state
+     * statement, made per definition: an agent whose closure tools persist memory declares `true`
+     * (suppressing the read-only-memory disclosure no roster inference can clear), one whose roster
+     * looks write-capable but reaches no durable store declares `false` (forcing the disclosure).
+     * Arbitration with the spawning run's declaration: a parent's explicit `false` is a FLOOR and wins
+     * over a definition `true` (the disclosure is about the deployment's storage, which choosing this
+     * agent does not change); otherwise a declared definition value wins over the parent's; absent
+     * both, the child spec carries no value and the child's own roster inference decides.
+     * On the workflow lane (`agent(…, {agentType})`) the definition value fills an ABSENT governed-spec
+     * value only — a base/spec declaration of either polarity wins (the lane's spec-pinned-fields rule).
+     */
+    memoryPersistenceCapable?: boolean;
+    /**
+     * Observer agents (CC 2.1.206 parity — 逐字锚 docs/CC206-OBSERVER-ANCHORS-2026-07-11.md, schema
+     * 面 C @28385708): "Agent type auto-spawned as a background observer whenever this agent runs.
+     * The observer receives read-only activity digests and reports via the ObserverReport tool; it
+     * never participates in the task." Resolution is warn-and-unobserved on an unknown type and
+     * refuses chaining (an observer's own `observer` declaration is ignored). Gated by
+     * {@link RuntimeCaps.allowObservers} — EXPLICIT opt-in, default OFF (the sema seat of CC's
+     * default-unset env `CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS` + default-true statsig pair).
+     */
+    observer?: string;
+    /**
+     * CC 面 C: "Supplemental postamble appended (after the harness-owned default) to each activity
+     * digest sent to the observer. Blank values are ignored."
+     */
+    observerMessage?: string;
+}
+/**
+ * A per-skill runtime capability manifest (design/77 §3 Gate-3). When present, loading the skill
+ * SCOPES the rest of the invocation to ONLY these tools/paths via runtime deny-narrowing: a tool call
+ * not in `allowTools` (intersected across nested skill frames) is DENIED, and a write whose canonical
+ * target falls outside `allowPaths` is DENIED — regardless of how permissive the task policy is.
+ *
+ * 🔴 **Safe-by-construction:** a manifest can only SUBTRACT capability. The narrowing composes via the
+ * `deny > ask > allow` fold (`combinePolicies`) where `deny` short-circuits, so a manifest can never
+ * *grant* a tool the task policy withheld — whoever sets a manifest can only restrict further.
+ * Worst case (the model never pops the frame) = no narrowing, never widening — still ⊆ task policy.
+ *
+ * The manifest is CALLER-provided here (same trust level as the rest of `SkillSpec`); deriving it
+ * automatically (the auto-promote pipeline) is a separate, deferred concern (design/77 §5).
+ */
+export interface SkillManifest {
+    /** The ONLY tool names the invocation may call while this skill's frame is active. */
+    allowTools: string[];
+    /**
+     * Optional path allowlist for WRITE tools (`write_file`/`edit_file`): a write whose canonicalized
+     * target is not inside one of these (path-segment-aware) prefixes is DENIED. Omit = no path narrowing
+     * (only `allowTools` applies). Reads are never path-narrowed (this gate restricts capability, not visibility).
+     *
+     * 🔴 **Fail-closed (MAJOR-2):** `allowPaths` can only confine tools whose write target is a parseable `path`
+     * argument (`write_file`/`edit_file`). While an `allowPaths` constraint is active, any OTHER mutating
+     * (effect:write/idempotent) allowlisted tool — notably `bash`, whose command can write anywhere — is DENIED
+     * outright, because its target cannot be path-confined. So a manifest that lists `bash` together with
+     * `allowPaths` does NOT let bash write/egress anywhere: bash is denied while the path constraint is active.
+     * Confine writes to specific paths via `write_file`/`edit_file` only.
+     */
+    allowPaths?: string[];
+    /** Reserved (design/77 §3): whether egress is permitted under this manifest. Carried through; v1 does
+     *  not act on it beyond the allowTools intersection (egress tools must also be in `allowTools`). */
+    egress?: boolean;
+    /** Stable lineage id of the artifact this manifest came from — used in deny reasons + as the scope key. */
+    lineageId: string;
+}
+/** A skill made available to this task (passed as an object; not loaded from disk). */
+export interface SkillSpec {
+    name: string;
+    description: string;
+    content: string;
+    /** Optional Gate-3 runtime capability manifest (design/77 §3) — see {@link SkillManifest}. */
+    manifest?: SkillManifest;
+    /**
+     * Optional attachments bundled with the skill (additive) — the CC bundled-skill shape (a SKILL.md whose
+     * body references sibling files by relative path) translated to sema's brain-outside posture, where the
+     * ruling is: **core never writes to disk.** CC extracts a bundle and lets the body reference files on
+     * the filesystem; sema core has no filesystem authority of its own, so materializing attachments into a
+     * working directory (making `Read`-by-path work) is the DEPLOYMENT's half. What core owns is exactly two
+     * faces, both bounded:
+     * 1. **disclosure** — each attachment's relative `path` is listed on the skill's `<skills>`-block line
+     *    (metadata only, capped like the rest of the block), so the model knows the material exists before
+     *    it loads the skill;
+     * 2. **delivery** — a `Skill` invoke appends an `## Attachments` section after the body (which is
+     *    itself delivered untruncated): each file as `### <path>` + its content, under a SEPARATE total
+     *    cap (`SKILL_ATTACHMENTS_MAX_CHARS`, 50k chars — an attachments-face budget; truncation/omission
+     *    is always disclosed in-band). Without deployment-side materialization this inline delivery is the
+     *    attachment's ONLY reachable face — that is the deliberate minimal shape, not an oversight.
+     *
+     * `path` is a relative, display-oriented identifier (how the body refers to the file); core never
+     * resolves it against a filesystem. `content` carries the SAME trust contract as {@link content}: skill
+     * material is CALLER-trusted instructions by design (see the skills module note) — a caller forwarding
+     * end-user skills is responsible for vetting attachments exactly like the body.
+     */
+    files?: Array<{
+        path: string;
+        content: string;
+    }>;
+}

package/dist/core/agent-definition.js

@@ -0,0 +1 @@
+export {};