@adhdev/mesh-shared 1.0.60-rc.4 → 1.0.60-rc.41

package/dist/mesh-tool-names.d.ts

@@ -18,7 +18,7 @@
  * Order mirrors mcp-server `ALL_MESH_TOOLS` for easy visual diffing, but the consistency
  * checks are set-based (order-insensitive).
  */
-export declare const CANONICAL_MESH_TOOL_NAMES: readonly ["mesh_status", "mesh_route_preview", "mesh_list_nodes", "mesh_enqueue_batch", "mesh_enqueue_task", "mesh_view_queue", "mesh_graph_view", "mesh_graph_gate_claim", "mesh_graph_gate_release", "mesh_graph_gate_abandon", "mesh_graph_node_patch", "mesh_queue_cancel", "mesh_queue_requeue", "mesh_send_task", "mesh_read_chat", "mesh_read_debug", "mesh_read_terminal", "mesh_send_keys", "mesh_launch_session", "mesh_git_status", "mesh_read_node_logs", "mesh_fast_forward_node", "mesh_restart_daemon", "mesh_checkpoint", "mesh_approve", "mesh_answer_question", "mesh_list_pending_approvals", "mesh_plan_onboarding", "mesh_create", "mesh_add_node", "mesh_clone_node", "mesh_remove_node", "mesh_cleanup_worktree_nodes", "mesh_refine_node", "mesh_refine_batch", "mesh_refine_config", "mesh_change_impact_config", "mesh_init", "mesh_reinit", "mesh_write_mesh_json_config", "mesh_refine_plan", "mesh_cleanup_sessions", "mesh_prune_stale_direct", "mesh_task_history", "mesh_ledger_query", "mesh_record_note", "mesh_forget_note", "mesh_reconcile_ledger", "mesh_requeue_held_events", "mesh_mission_upsert", "mesh_mission_list", "mesh_review_inbox", "mesh_magi_review", "mesh_magi_collect", "mesh_magi_kind_panel_set", "mesh_magi_kind_panel_list", "mesh_node_slots_set", "mesh_node_slots_list", "mesh_node_slots_propose", "mesh_coordinator_prompt_append_get", "mesh_coordinator_prompt_append_set"];
+export declare const CANONICAL_MESH_TOOL_NAMES: readonly ["mesh_status", "mesh_route_preview", "mesh_list_nodes", "mesh_enqueue_batch", "mesh_enqueue_task", "mesh_view_queue", "mesh_graph_view", "mesh_graph_gate_claim", "mesh_graph_gate_release", "mesh_graph_gate_abandon", "mesh_graph_node_patch", "mesh_queue_cancel", "mesh_queue_requeue", "mesh_send_task", "mesh_read_chat", "mesh_read_debug", "mesh_read_terminal", "mesh_send_keys", "mesh_launch_session", "mesh_git_status", "mesh_read_node_logs", "mesh_fast_forward_node", "mesh_restart_daemon", "mesh_checkpoint", "mesh_approve", "mesh_answer_question", "mesh_list_pending_approvals", "mesh_plan_onboarding", "mesh_create", "mesh_add_node", "mesh_clone_node", "mesh_remove_node", "mesh_cleanup_worktree_nodes", "mesh_refine_node", "mesh_refine_batch", "mesh_refine_config", "mesh_change_impact_config", "mesh_init", "mesh_reinit", "mesh_write_mesh_json_config", "mesh_refine_plan", "mesh_cleanup_sessions", "mesh_prune_stale_direct", "mesh_task_history", "mesh_ledger_query", "mesh_record_note", "mesh_forget_note", "mesh_reconcile_ledger", "mesh_mission_upsert", "mesh_mission_list", "mesh_review_inbox", "mesh_magi_review", "mesh_magi_collect", "mesh_magi_kind_panel_set", "mesh_magi_kind_panel_list", "mesh_node_slots_set", "mesh_node_slots_list", "mesh_node_slots_propose", "mesh_coordinator_prompt_append_get", "mesh_coordinator_prompt_append_set"];
 export type CanonicalMeshToolName = typeof CANONICAL_MESH_TOOL_NAMES[number];
 /** The count the `NN tools` barrel doc comments and consistency test assert against. */
-export declare const CANONICAL_MESH_TOOL_COUNT: 61;
+export declare const CANONICAL_MESH_TOOL_COUNT: 60;

package/dist/mesh-vocabulary.d.ts

@@ -0,0 +1,70 @@
+/**
+ * mesh-vocabulary — the ONE declaration of every mesh enum.
+ *
+ * Wiring-unification Phase A3 (docs/design/2026-09-23-wiring-unification.md).
+ *
+ * Before this file `MeshTaskStatus` was declared twice in daemon-core with
+ * different members (one carried `in_progress`, which no task row ever held),
+ * a third time in `repo-mesh-types.ts`, and loosened to `| string` in web-core;
+ * the MCP tool schemas hand-copied the task-mode list six times. Every enum a
+ * mesh tool, ledger row, queue entry or dashboard view branches on is declared
+ * here once, as a `const` tuple, and the type is derived from it. JSON-schema
+ * producers use `enumOf()` so the published schema cannot drift from the code.
+ *
+ * `MeshTaskDifficulty` / `MESH_TASK_DIFFICULTIES` already live in
+ * ./brain-routing.ts and are re-exported here for one-stop discovery.
+ */
+export { MESH_TASK_DIFFICULTIES, type MeshTaskDifficulty } from './brain-routing';
+export declare const MESH_TASK_STATUSES: readonly ["pending", "assigned", "completed", "failed", "cancelled"];
+export type MeshTaskStatus = typeof MESH_TASK_STATUSES[number];
+export declare const MESH_TERMINAL_TASK_STATUSES: readonly ["completed", "failed", "cancelled"];
+export type MeshTerminalTaskStatus = typeof MESH_TERMINAL_TASK_STATUSES[number];
+export declare const MESH_TASK_MODES: readonly ["code_change", "validation", "live_debug_readonly", "launch_app", "convergence"];
+export type MeshTaskMode = typeof MESH_TASK_MODES[number];
+export declare const MESH_TASK_PRIORITIES: readonly ["low", "normal", "high"];
+export type MeshTaskPriority = typeof MESH_TASK_PRIORITIES[number];
+export declare const MESH_THINKING_LEVELS: readonly ["low", "medium", "high"];
+export type MeshThinkingLevel = typeof MESH_THINKING_LEVELS[number];
+/**
+ * How a message is delivered to a session that may be busy.
+ *
+ *   'when_idle'  — DEFAULT. Never disturbs a running turn; a busy session's task
+ *                  is queued and auto-delivered on its next idle transition.
+ *   'interrupt'  — Abort the in-flight turn (the provider's own stop control),
+ *                  then deliver once the session settles to idle. The name is
+ *                  deliberately blunt: the unfinished work is LOST. `immediate`
+ *                  was rejected as a name because it reads like a gentle overlay.
+ */
+export declare const MESH_DELIVERY_MODES: readonly ["when_idle", "interrupt"];
+export type MeshDeliveryMode = typeof MESH_DELIVERY_MODES[number];
+/**
+ * What to do with a node's sessions when the node is removed or a MAGI fan-out
+ * settles. Declared here so daemon-core (`RepoMeshSessionCleanupMode`), the
+ * web dashboard picker and the MCP schemas all read one list.
+ */
+export declare const MESH_SESSION_CLEANUP_MODES: readonly ["preserve", "stop", "delete_stopped", "stop_and_delete"];
+export type MeshSessionCleanupMode = typeof MESH_SESSION_CLEANUP_MODES[number];
+/** Outcome a delegated worker may report through `report_completion`. */
+export declare const WORKER_REPORT_OUTCOMES: readonly ["completed", "blocked", "failed"];
+export type WorkerReportOutcome = typeof WORKER_REPORT_OUTCOMES[number];
+/** Final branch state a worker reports (see coordinator convergence rules). */
+export declare const WORKER_BRANCH_STATES: readonly ["merged_to_main", "pushed_feature_branch_needs_merge", "blocked_review", "cleanup_candidate", "not_mergeable"];
+export type WorkerBranchState = typeof WORKER_BRANCH_STATES[number];
+export declare const isMeshTaskStatus: (value: unknown) => value is "failed" | "pending" | "assigned" | "completed" | "cancelled";
+export declare const isMeshTerminalTaskStatus: (value: unknown) => value is "failed" | "completed" | "cancelled";
+export declare const isMeshTaskMode: (value: unknown) => value is "code_change" | "validation" | "live_debug_readonly" | "launch_app" | "convergence";
+export declare const isMeshTaskPriority: (value: unknown) => value is "low" | "high" | "normal";
+export declare const isMeshThinkingLevel: (value: unknown) => value is "medium" | "low" | "high";
+export declare const isMeshDeliveryMode: (value: unknown) => value is "when_idle" | "interrupt";
+export declare const isMeshSessionCleanupMode: (value: unknown) => value is "preserve" | "stop" | "delete_stopped" | "stop_and_delete";
+export declare const isWorkerReportOutcome: (value: unknown) => value is "failed" | "blocked" | "completed";
+export declare const isWorkerBranchState: (value: unknown) => value is "merged_to_main" | "pushed_feature_branch_needs_merge" | "blocked_review" | "cleanup_candidate" | "not_mergeable";
+/**
+ * JSON-schema fragment for a string enum, derived from the tuple. Use this in
+ * every MCP tool schema instead of spelling the member list again.
+ */
+export declare function enumOf<T extends readonly string[]>(values: T, description?: string): {
+    type: 'string';
+    enum: T[number][];
+    description?: string;
+};

package/dist/mission-brief.d.ts

@@ -0,0 +1,62 @@
+/**
+ * mission-brief — the goal/constraints/done-criteria/handoff a coordinator
+ * attaches to a mission at `mesh_mission_upsert` time, and the deterministic
+ * rendering of that brief into a dispatched task's worker-protocol footer
+ * (wiring-unification Phase H2, `docs/design/2026-09-23-wiring-unification.md`
+ * §7c).
+ *
+ * `mesh_mission_upsert` today carries only a free-text `goal` string — no
+ * structured constraints, done-criteria or handoff notes, and nothing from a
+ * mission ever reaches a dispatched worker's task body. This module is the
+ * pure, dependency-free core: a normalized `MissionBrief` shape with length
+ * caps (mirrors `report_completion.summary`'s "prefer specifics" discipline —
+ * a brief is meant to be read by a worker mid-task, not skimmed by a human),
+ * and a deterministic Markdown renderer capped at 1,200 chars so a mission
+ * with many/long fields cannot blow a dispatched task's token budget.
+ *
+ * This module does NOT decide where the rendered block is inserted (that is
+ * `worker-protocol.ts`'s `renderWorkerProtocolFooter`, which places it above
+ * the marker line — see that file), and does NOT touch storage (H2's proposal
+ * keeps `mesh_missions` as the row source; this is the shape callers upsert
+ * into/read out of that row's `goal`/new `brief` columns).
+ */
+/** Total rendered-block cap (design doc H2 "bounded payload" discipline, mirrored from `listMeshMissionsForTool`). */
+export declare const MISSION_BRIEF_RENDER_MAX_CHARS = 1200;
+export interface MissionBrief {
+    /** What this mission is trying to accomplish. Required — an empty brief is not meaningful. */
+    goal: string;
+    /** Hard constraints a worker must respect (e.g. "do not touch daemon-core", "no npm install"). */
+    constraints?: string[];
+    /** How to know the mission is actually done. */
+    doneCriteria?: string[];
+    /** Standing notes for whoever picks up mission work next. */
+    handoffNotes?: string[];
+    /** Paths this mission's tasks collectively own (H1 integration point — surfaced, not enforced here). */
+    ownedPaths?: string[];
+}
+export interface NormalizeMissionBriefResult {
+    /** `null` when the input had no usable `goal` — callers should treat this as "no brief", not an empty one. */
+    readonly brief: MissionBrief | null;
+    /** What was trimmed/dropped, for a caller that wants to warn (never thrown). */
+    readonly truncated: ReadonlyArray<{
+        field: string;
+        reason: 'field_too_long' | 'list_too_long' | 'item_too_long';
+    }>;
+}
+/**
+ * Normalize a caller-supplied brief. Never throws. Returns `brief: null` when
+ * there is no non-empty `goal` — the caller (e.g. `mesh_mission_upsert`'s
+ * handler) decides whether that means "reject" or "no brief attached", this
+ * module only normalizes shape.
+ */
+export declare function normalizeMissionBrief(input: unknown): NormalizeMissionBriefResult;
+/**
+ * Deterministic Markdown rendering of a brief, capped at
+ * `MISSION_BRIEF_RENDER_MAX_CHARS`. Same field order every call (goal,
+ * constraints, done criteria, owned paths, handoff notes) so a snapshot test
+ * or a worker reading two renders of the same brief sees no drift. If the
+ * assembled text exceeds the cap, trailing sections are dropped whole (never
+ * mid-line) until it fits, and a final `(brief truncated)` marker is appended
+ * — a worker should never receive a block cut off mid-sentence.
+ */
+export declare function renderMissionBriefBlock(brief: MissionBrief): string;

package/dist/outbound-message.d.ts

@@ -0,0 +1,202 @@
+/**
+ * outbound-message — the one send-side unit crossing every transport.
+ *
+ * Wiring-unification Phase D (docs/design/2026-09-23-wiring-unification.md §6,
+ * D1) / workstream D-web. Full type derivation in the scratchpad
+ * `phase-D-plan.md` §1.1-§1.2 (`OutboundMessage`/`SendPolicy`/`SubmitOutcome`/
+ * `SendRefusal`). `SendRefusal` is imported from here by Phase C1's
+ * `turn-evidence.ts` (`RECLAIMING_SEND_REFUSALS`) — this file owns the type,
+ * C1 owns which of its members reclaim a mesh dispatch attempt.
+ *
+ * Before this type, a chat send was represented by twelve different loose
+ * request shapes (`{message, sendNow?, interrupt?}`, `{message, input}`,
+ * mesh `agent_command` args, MCP tool args, ...) and parked messages had no
+ * identity at all — the driver queue was keyed by exact text, so send-now,
+ * cancel, interrupt and the web echo-retirement all recovered identity by
+ * string matching. `OutboundMessage.messageId` is minted once, at the
+ * ORIGIN, and is the identity every layer keys on afterwards: the wire
+ * field in the `send_chat` command payload, the driver's queue key (daemon
+ * side, Phase D-daemon), the web pending-store key (`pendingQueuedMessages.ts`)
+ * and the echo-retirement key (`conversation-message-snapshot.ts`).
+ *
+ * This file is dependency-free by construction (mesh-shared leaf rule):
+ * `InputEnvelopeWire`/`InputPartWire` are STRUCTURAL MIRRORS of daemon-core's
+ * `InputEnvelope`/`InputPart` (`oss/packages/daemon-core/src/providers/
+ * io-contracts.ts`), not re-exports — daemon-core assigns its richer type
+ * into this one, never the other way round, so this package's published
+ * `.d.ts` never references a package that depends on it.
+ */
+export interface ContentAnnotationsWire {
+    audience?: ('user' | 'assistant')[];
+    priority?: number;
+}
+export interface TextInputPartWire {
+    type: 'text';
+    text: string;
+}
+export interface ImageInputPartWire {
+    type: 'image';
+    mimeType: string;
+    uri?: string;
+    data?: string;
+    alt?: string;
+}
+export interface AudioInputPartWire {
+    type: 'audio';
+    mimeType: string;
+    uri?: string;
+    data?: string;
+    transcript?: string;
+}
+export interface VideoInputPartWire {
+    type: 'video';
+    mimeType: string;
+    uri?: string;
+    data?: string;
+    transcript?: string;
+    posterUri?: string;
+}
+export interface ResourceInputPartWire {
+    type: 'resource';
+    uri: string;
+    mimeType?: string;
+    name?: string;
+    text?: string;
+    data?: string;
+}
+export interface ResourceLinkInputPartWire {
+    type: 'resource_link';
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+    annotations?: ContentAnnotationsWire;
+}
+export type InputPartWire = TextInputPartWire | ImageInputPartWire | AudioInputPartWire | VideoInputPartWire | ResourceLinkInputPartWire | ResourceInputPartWire;
+export interface InputEnvelopeWire {
+    parts: InputPartWire[];
+    textFallback: string;
+    metadata?: {
+        source?: 'dashboard' | 'shortcut_api' | 'provider_script' | 'session_replay';
+        clientTimestamp?: number;
+    };
+}
+/**
+ * Who minted this `OutboundMessage`. Determines default policy and refusal
+ * surface — 'mesh' origins get the mesh-specific `SendRefusal` reasons,
+ * interactive origins get the interactive ones.
+ *
+ * `'api'`/`'cli'` are carried per the design doc's D1 type even though no
+ * current call site produces them distinct from `'dashboard'`/`'mcp'`/
+ * `'mesh'` (flagged as an open question in phase-D-plan.md §7.3 risk 5) —
+ * kept here unchanged pending an owner decision; dropping a union member is
+ * a decision for whoever lands D-daemon/D2, not this workstream.
+ */
+export type OutboundMessageOrigin = 'dashboard' | 'mcp' | 'mesh' | 'api' | 'cli';
+/**
+ * How this message should be admitted when the session is not idle.
+ * Replaces the loose `sendNow`/`interrupt`/`force`/`forceSend` booleans (and
+ * mesh `delivery_mode`) with one closed union. `'queue'` is the default for
+ * every origin.
+ */
+export type SendPolicy = {
+    mode: 'queue';
+} | {
+    mode: 'send_now';
+} | {
+    mode: 'interrupt';
+};
+/**
+ * Every reason `submit()` can refuse a message, closed so callers branch on it
+ * instead of matching free text.
+ *
+ * ★ This is THE `SendRefusal` (docs/design/2026-09-23-wiring-unification.md
+ * §6 D1) — Phase C1's `turn-evidence.ts` imports `SendRefusal`/
+ * `SEND_REFUSAL_REASONS` from this file (`RECLAIMING_SEND_REFUSALS`, the
+ * subset that means a mesh dispatch attempt must be reclaimed rather than
+ * retried) rather than declaring its own copy. Do not fork this vocabulary —
+ * a member renamed or removed here must be re-checked against
+ * `RECLAIMING_SEND_REFUSALS`'s three members (`session_exited`, `no_target`,
+ * `unsupported_input`), which `satisfies readonly SendRefusal[]` there keeps
+ * honest at compile time.
+ */
+export type SendRefusal = 'not_ready' | 'send_in_flight' | 'not_generating' | 'not_supported' | 'platform_unsupported' | 'modal_parked' | 'interrupt_not_implemented' | 'interrupt_refused' | 'idle_timeout' | 'session_exited' | 'unsupported_input' | 'no_target' | 'bootstrap_pending' | 'duplicate_dispatch' | 'internal_error';
+/**
+ * Which write path carried a delivered/queued message (Phase D2, additive
+ * detail — callers branch on `kind`; `route` only refines the report):
+ *
+ *   `pty`         — the ordinary composer write (or the driver FIFO for `queued`);
+ *   `agent_queue` — the POSIX split write the CLI's OWN input queue takes while
+ *                   a turn is generating (`send_now`). Written, not yet answered;
+ *   `interrupt`   — the turn in flight was stopped first, then this body was
+ *                   written (or re-parked) as a new turn;
+ *   `acp`         — handed to an ACP agent's `session/prompt`.
+ */
+export type SubmitRoute = 'pty' | 'agent_queue' | 'interrupt' | 'acp';
+/** The stop key pressed by an `interrupt` submit (logs / operator display). */
+export interface SubmitInterruptDetail {
+    keyName: string;
+    /** 'declared' = spec-declared stop key whose busy→idle effect was never observed live. */
+    confidence: 'proven' | 'declared';
+}
+/**
+ * The one closed outcome shape every caller receives from `submit()`.
+ *
+ * The optional fields are additive DETAIL (Phase D2): `route`/`interrupt` say
+ * how a message was written, `message` is a human-readable refusal line and
+ * `restored` says whether a parked body that an out-of-band submit had claimed
+ * is back in the driver queue (`false` = nothing holds it any more). None of
+ * them changes what `kind` means.
+ */
+export type SubmitOutcome = {
+    kind: 'delivered';
+    route?: SubmitRoute;
+    interrupt?: SubmitInterruptDetail;
+} | {
+    kind: 'queued';
+    position: number;
+    route?: SubmitRoute;
+    interrupt?: SubmitInterruptDetail;
+} | {
+    kind: 'duplicate';
+    of: string;
+} | {
+    kind: 'refused';
+    reason: SendRefusal;
+    message?: string;
+    restored?: boolean;
+};
+/**
+ * The one send-side unit crossing every transport. `messageId` is minted at
+ * the ORIGIN (never by the daemon) — this is what makes cross-transport
+ * dedupe and identity-based claim/cancel/send-now possible.
+ */
+export interface OutboundMessage {
+    messageId: string;
+    sessionId: string;
+    input: InputEnvelopeWire;
+    origin: OutboundMessageOrigin;
+    policy: SendPolicy;
+    createdAt: number;
+    /**
+     * Present only for a mesh-dispatched message; lets the turn ledger
+     * (Phase C) bind the send to the attempt without the sender needing to
+     * know what an "attempt" is. Optional and inert until C lands.
+     */
+    meshAttemptRef?: string;
+}
+export declare function mintMessageId(now?: number): string;
+export declare function isMessageId(value: unknown): value is string;
+export declare const OUTBOUND_MESSAGE_ORIGINS: readonly ["dashboard", "mcp", "mesh", "api", "cli"];
+export declare function isOutboundMessageOrigin(value: unknown): value is OutboundMessageOrigin;
+export declare const SEND_POLICY_MODES: readonly ["queue", "send_now", "interrupt"];
+export declare function isSendPolicyMode(value: unknown): value is SendPolicy['mode'];
+export declare function isSendPolicy(value: unknown): value is SendPolicy;
+export declare const SEND_REFUSAL_REASONS: readonly ["not_ready", "send_in_flight", "not_generating", "not_supported", "platform_unsupported", "modal_parked", "interrupt_not_implemented", "interrupt_refused", "idle_timeout", "session_exited", "unsupported_input", "no_target", "bootstrap_pending", "duplicate_dispatch", "internal_error"];
+export declare function isSendRefusal(value: unknown): value is SendRefusal;
+export declare function isSubmitOutcome(value: unknown): value is SubmitOutcome;
+export declare function isInputEnvelopeWire(value: unknown): value is InputEnvelopeWire;
+/** Minimal structural check for the wire boundary — not a full decoder (mesh-shared stays a pure leaf; semantic validation stays with the handler that owns it). */
+export declare function isOutboundMessage(value: unknown): value is OutboundMessage;

package/dist/path-ownership.d.ts

@@ -0,0 +1,101 @@
+/**
+ * path-ownership — declared file-ownership sets for `code_change` mesh tasks
+ * (wiring-unification Phase H1, `docs/design/2026-09-23-wiring-unification.md`
+ * §7c).
+ *
+ * Today two `code_change` tasks on two different nodes (two worktrees of the
+ * same branch, or main + a worktree) can silently touch the same file with
+ * zero warning — the only existing isolation is node-level ("one active write
+ * task per node"), never path-level. This module is the pure, dependency-free
+ * core of the fix: normalizing a caller-declared `owned_paths` list, and
+ * comparing declared sets for overlap. It has NO opinion on enforcement policy
+ * (refuse vs warn, which axis a caller compares against) — that is the mesh
+ * runtime's job (`claimNextTask` / `claimNextQueueTask` in daemon-core); this
+ * module only answers "do these two declarations conflict" and "did the
+ * touched-files report stay inside the declaration".
+ *
+ * SCOPE DECISION (glob support): minimal, deliberately. A declaration entry is
+ * either an exact repo-relative path (`src/foo.ts`) or a directory prefix
+ * spelled with a trailing `/**` (`src/mesh/**`) meaning "this path and
+ * everything under it". No `*`/`?` mid-segment wildcards, no `!` negation, no
+ * brace expansion. Two `code_change` tasks racing on overlapping files is a
+ * coordination bug to catch, not a general glob engine to build — a full
+ * minimatch-style matcher would need its own test suite and still leave the
+ * same ambiguity (does `src/*.ts` "contain" `src/foo.ts`?) the design doc's
+ * risk list calls out. `src/` (no `**`) is treated as an exact single-path
+ * entry, i.e. it owns a literal file/dir node named `src`, NOT everything
+ * under it — callers who want subtree ownership must write `src/**`.
+ *
+ * Rejected inputs (absolute paths, `..` segments, backslash-only entries that
+ * still resolve outside the repo after normalization) are dropped rather than
+ * silently coerced — `normalizeOwnedPaths` reports what it dropped so the
+ * caller (enqueue-time validation) can decide whether to warn or refuse.
+ */
+/** One normalized ownership entry: a repo-relative path, optionally a `**` subtree prefix. */
+export interface OwnedPathEntry {
+    /** Repo-relative path with forward slashes, no leading `./`, no trailing slash. */
+    readonly path: string;
+    /** True when this entry was declared as `<path>/**` (owns the whole subtree). */
+    readonly subtree: boolean;
+}
+/** A caller's normalized ownership declaration. */
+export interface OwnedPathsDeclaration {
+    readonly paths: readonly OwnedPathEntry[];
+}
+export interface NormalizeOwnedPathsResult {
+    readonly declaration: OwnedPathsDeclaration;
+    /** Raw input entries that were dropped, with why — surfaced to the caller, never silently coerced. */
+    readonly rejected: ReadonlyArray<{
+        input: string;
+        reason: string;
+    }>;
+}
+/** Cap mirrors `depends_on`'s implicit list-size discipline (design doc H1 proposal). */
+export declare const MAX_OWNED_PATHS = 64;
+/**
+ * Normalize a caller-supplied `owned_paths` array. Never throws — invalid
+ * entries are dropped and reported in `rejected`; duplicates (after
+ * normalization) collapse to one entry (subtree wins if either declaration
+ * form is present for the same path). Entries beyond `MAX_OWNED_PATHS` (after
+ * dedup) are dropped with reason `over_cap`, preserving declaration order.
+ */
+export declare function normalizeOwnedPaths(input: unknown): NormalizeOwnedPathsResult;
+/** True when two declarations claim any overlapping path. Pure set comparison — no policy (refuse vs warn) here. */
+export declare function pathsOverlap(a: OwnedPathsDeclaration, b: OwnedPathsDeclaration): boolean;
+export interface InFlightOwnership {
+    readonly taskId: string;
+    readonly paths: OwnedPathsDeclaration;
+}
+export interface OwnershipConflict {
+    readonly taskId: string;
+    /** The specific overlapping paths, for a readable refusal message. */
+    readonly overlappingPaths: readonly string[];
+}
+/**
+ * Compare a candidate declaration against every other in-flight task's
+ * declaration and return every conflict found (not just the first), each
+ * naming the owning task id and the specific overlapping path(s) — so a
+ * refusal message can say exactly what collided, not just that it did.
+ *
+ * Backward compatibility (design doc risk #4): an EMPTY candidate declaration
+ * never conflicts (opt-in only — absent `owned_paths` performs no overlap
+ * check for that task), and an in-flight entry with an empty declaration is
+ * never reported as a conflict source either.
+ */
+export declare function findOwnershipConflicts(candidate: OwnedPathsDeclaration, inFlight: readonly InFlightOwnership[]): OwnershipConflict[];
+export interface TouchedFilesOutsideOwnershipResult {
+    /** Touched files not covered by any declared owned-path entry. */
+    readonly undeclaredTouched: readonly string[];
+    /** Declared entries that no touched file matched (informational only — under-reporting is not flagged as a mismatch by policy, just visible here). */
+    readonly unusedDeclarations: readonly string[];
+}
+/**
+ * Compare a worker's `report_completion.touched_files` against its task's
+ * declared `owned_paths`. Pure comparison only — per the design doc, a
+ * mismatch is "surfaced as evidence, not silently accepted"; this function
+ * does not decide whether that is an error. Each `touched` entry is
+ * normalized with the same rules as a declaration (invalid entries — e.g. an
+ * absolute path a worker reported by mistake — are treated as undeclared
+ * rather than silently dropped, since they cannot match anything).
+ */
+export declare function touchedFilesOutsideOwnership(touched: readonly string[], owned: OwnedPathsDeclaration): TouchedFilesOutsideOwnershipResult;