@zq-silk/yui 0.0.0

package/ARCHITECTURE.md

@@ -0,0 +1,141 @@
+# Yui architecture
+
+Yui is a single-user local control plane. FileTaskStore is the one authority for Yui state, tmux is the one authority for Agent terminal/process interaction, and Git is the authority for repositories and worktrees.
+
+## Components
+
+```mermaid
+flowchart LR
+  CLI[yui CLI] --> F[(schema.json + state.json)]
+  CLI -->|private Unix socket| C[Controller]
+  C --> F
+  C --> G[Git worktrees]
+  C --> T[tmux]
+  T --> A[Codex / Claude]
+```
+
+- The CLI owns parsing, interactive selection, setup/completion, and foreground attach.
+- FileTaskStore owns all persisted domain records and atomic mutations.
+- One background Controller per `YUI_HOME` owns automatic Git/tmux effects.
+- tmux receives all automated input and exclusively owns interactive terminal input after attach.
+- Native Agent transcript stores remain outside Yui. Only explicit messages, inputs, Run state, and summaries enter `state.json`.
+
+The Controller socket uses a private discovery file, random token, strict JSON-line protocol, and local file permissions. It is transport, not a second persistence system.
+
+## Persistent layout
+
+```text
+YUI_HOME/
+  schema.json
+  state.json
+  .state.lock
+  runtime/
+    controller.json
+    controller.sock
+  worktrees/
+    <task-id>/
+      <role-name>/
+```
+
+`schema.json` records storage-layout version 5, aggregate-schema version 2, and a reserved `activeGeneration` pointer. `state.json` is one aggregate containing:
+
+- configuration and completion installation records;
+- configured Agents;
+- Repositories;
+- global Roles and their per-Agent session sets;
+- Tasks, Task Roles, RoleWorkspaces, messages, WorkItems, AgentRuns, append-only events, Task Briefs, Decisions, and Milestones;
+- pending Leader wakes, Leader failures, and Operator notifications.
+
+Every persisted domain record has its own schema version and is validated when read. Unsupported aggregate or record shapes fail explicitly; Yui does not silently repair them.
+
+Writes acquire a cross-process lock, reread the latest aggregate, apply the mutation once, and commit one replacement. The durable write path creates a mode-`0600` temporary file, flushes it, renames it over `state.json`, and flushes the containing directory. Compound workflow operations use the same transaction callback and produce one aggregate write.
+
+The layout and aggregate migration registries are intentionally empty in this release. Their boundaries validate complete sequential plans before applying any mutation. A reserved generation pointer allows a later layout to write and validate a new immutable generation before atomically switching the manifest; generation storage is not implemented in version 5.
+
+## Domain model and invariants
+
+- A Task is `draft`, `active`, `completed`, or `archived`. Completion is a reversible execution fence; archive is terminal.
+- Creating a Task also creates its Leader Role.
+- Repository-backed active Tasks use one deterministic worktree per Role at `<YUI_HOME>/worktrees/<task-id>/<role-name>`.
+- Common Role names map directly to `yui/<task-id>/<role-name>` branches; names that are not valid Git ref segments use a deterministic encoded branch segment without changing their worktree directory.
+- `Task.cwd` marks the Task worktree root; each Task Role workspace agrees with its persisted RoleWorkspace path.
+- A Role may bind multiple Agents but has one active Agent.
+- Each `(Role, Agent)` binding has its own native session record. Switching preserves dormant sessions.
+- A Role has at most one active AgentRun.
+- A WorkItem has at most one active Run.
+- A Worker yield atomically completes its Run/WorkItem, appends its summary, and merges a Leader wake.
+- A Leader yield never creates a self-wake, but it releases any already-pending wake for the next Controller pass.
+- Completing a Task requires no active Worker Run or running WorkItem, clears pending wakes and recovery failures, and rejects later execution until an explicit reopen.
+- A Leader control Run may atomically yield itself while completing the Task. Reopen returns the Task to active and queues one `task-reopened` wake.
+- Completed Tasks retain their Role sessions and worktrees; archived Tasks stop tmux and clean only clean worktrees.
+- Archived Tasks reject new messages, Roles, work, dispatch, enter, and recovery actions.
+
+FileTaskStore validates cross-record references after every transaction, including Repository ownership, Task/Role ownership, active-run pointers, and session-set ownership.
+
+## Controller pass
+
+The Controller runs a non-overlapping full reconciliation pass every 30 seconds by default. `reconciliationIntervalSeconds` may be set from 5 to 300 in Yui config. Durable state changes request an immediate pass through the Controller socket, and concurrent scan requests coalesce into one follow-up pass.
+
+`controller restart` stops only this process and waits for its private socket/discovery state to disappear before starting the currently installed runtime. tmux sessions are external durable runtime state and are never stopped by Controller restart.
+
+```text
+prepare active workspaces
+  -> stop archived Task tmux sessions
+  -> clean archived workspaces when clean
+  -> deliver queued Role Runs
+  -> reconcile exited active Role Runs
+  -> dispatch pending Leader wakes
+```
+
+Repository preparation precedes delivery. A Repository path and base ref are validated by Git. Each Role derives the path `<YUI_HOME>/worktrees/<task-id>/<role-name>` and branch `yui/<task-id>/<role-name>`. The minimal RoleWorkspace record retains its Repository, path, branch, base ref, and starting commit; it is not a ref ledger. Existing worktrees must resolve to the expected path, branch, and Git common directory.
+
+Archive stops tmux before worktree cleanup. Each clean Role worktree is removed idempotently and recorded independently. A dirty Role worktree and its RoleWorkspace record are preserved; they are never force-removed. A Git failure is isolated to its Task so other Task reconciliation continues.
+
+## Durable wake and Run behavior
+
+Task activation/reopen, an Operator/user message, Worker yield, and exited Role failure can merge a `PendingWakeup`. Reasons are de-duplicated while request count and first/last timestamps remain durable. Completed Tasks never dispatch a pending wake.
+
+If the Leader is busy, the Controller does not touch tmux and leaves the wake pending. When idle, it prepares the fixed Role session, then atomically claims the unchanged wake as a durable, not-yet-delivered Leader AgentRun before any tmux input. The claim clears that wake; later requests form a new pending wake. A confirmed receipt marks the Run delivered. A send failure fails the claim and restores its wake, while a Controller crash can resume the same Run with the same `agent-run:<run-id>` receipt.
+
+A dispatched Worker WorkItem creates a durable AgentRun before any terminal effect. The Controller is the only automatic delivery path. Delivery uses `agent-run:<run-id>` as its receipt and persists `deliveredAt` plus successful session/Role state after tmux confirms the send. Completion and yield reject a Run whose delivery is still pending.
+
+If an active Role's tmux window disappears before yield, the Controller fails the AgentRun and running WorkItem, clears the active-run pointer, stops its session record, and merges a failure wake for the Leader. A failed Leader recovery records `LeaderFailure` plus `OperatorNotification`; `jobs retry leader-recovery:<task-id>` clears those records and queues a recovery wake.
+
+`jobs list` is a compatibility projection over pending wakes and recovery failures. There is no generic Job table or retry queue.
+
+## tmux ownership and delivery
+
+Foreground attach is a hard terminal handoff:
+
+1. close any readline interface;
+2. leave raw mode;
+3. pause Yui stdin;
+4. run `tmux attach-session` synchronously with inherited stdio.
+
+Yui does not read stdin, draw UI, or relay bytes while attached.
+
+Automatic delivery never reads stdin. It requires an adapter-specific readiness probe: Codex and Claude have separate composer markers. Before waiting for readiness, the Controller checks for an existing pane receipt, so a busy Agent does not cause a retry scan to block. Receipt check/write, literal input, and Enter execute in one tmux server command queue.
+
+## Native session identity
+
+Claude receives a preallocated session ID at new launch and resumes that fixed ID later.
+
+Codex discovers its thread ID at runtime. Managed launches add a structured Codex `notify` argv configuration. After each completed turn, Codex invokes:
+
+```text
+yui internal session-notify <codex-json-payload>
+```
+
+The hidden command validates the payload and Yui provenance environment, then records the fixed task/global Role session through the Controller. No session-binding text is placed in a model prompt.
+
+## Deliberate exclusions
+
+This version does not restore:
+
+- backup/restore, import/export, trash, or general maintenance commands;
+- native storage extensions, derived indexes, or recovery journals;
+- runtime claims, leases, fencing generations, permission fingerprints, or identity ledgers;
+- inactivity TTL, cooldown, review-time, recurring schedules, or offline resolution;
+- Web APIs, Web UI, or remote multi-user coordination.
+
+Those systems are not required for the retained single-user workflow. Future storage-schema migration is the one explicit extension boundary kept in the design.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+<p align="right"><strong>English</strong> | <a href="./i18n/README.zh-CN.md">简体中文</a></p>
+
+# Yui
+
+Yui is a local orchestrator for long-running Codex and Claude work. It keeps its control state in inspectable JSON files, lets tmux own every Agent terminal, and creates deterministic Git worktrees for repository-backed Tasks.
+
+The current implementation restores the useful Role/Agent/session and CLI framework without restoring the later data-maintenance, lease, schedule, and recovery-ledger systems.
+
+## Requirements
+
+- Node.js 20.17+, 22.9+, or 24.x
+- Git
+- tmux
+- Codex CLI or Claude Code CLI
+
+## Setup
+
+```sh
+npm install -g @zq-silk/yui
+yui setup
+yui doctor
+```
+
+`setup` is interactive. It detects installed Agent CLIs, asks which Agents to configure, selects the default and Operator Agent, confirms the Operator workspace, and offers shell-completion setup. Running it again preserves existing Tasks and Roles while allowing configuration changes.
+
+`completion` is also interactive, with or without an explicit shell:
+
+```sh
+yui completion
+yui completion zsh
+```
+
+Both forms confirm the generated script, installation path, and shell startup-file change. The installed completion is generated from the command catalog, including nested subcommands.
+
+Yui uses `~/.yui` by default. Set `YUI_HOME` to use an isolated home:
+
+```sh
+export YUI_HOME=/absolute/path/to/yui-home
+yui setup
+```
+
+The home contains `schema.json`, the authoritative `state.json`, Controller discovery files, and managed worktrees. The current storage version is exact and fresh-only; the migration registry exists for future versions, but this release does not migrate older formats.
+
+## Quick start
+
+Register a repository and create a Draft Task:
+
+```sh
+yui repository add app /absolute/path/to/app --base main
+yui repository list
+
+yui task create "Ship CSV export" --repository <repository-id> --base main
+yui task update <task-id> --priority high --tags release,csv --due-at 2026-08-01T00:00:00Z
+yui task update <task-id> --clear-priority --clear-tags --clear-due-at
+yui task show <task-id>
+yui task context <task-id>
+yui task activate <task-id>
+```
+
+Use `task context` as the first detailed read of an existing Task. It combines the Task, Brief, active Decisions, recent Milestones, Roles, current and recent WorkItems with their Runs, recent Messages, open and resolved InputRequests, and recent Events. Terminal output keeps histories and long text compact; `yui --json task context <task-id>` returns the complete records in the top-level `data` field.
+
+Activation queues the first durable Leader wake. For a repository-backed Task, the Controller first creates one worktree per Role at `<YUI_HOME>/worktrees/<task-id>/<role-name>` on `yui/<task-id>/<role-name>`, then starts the Leader. Roles added later receive their own worktree before delivery.
+
+Submit information through Operator:
+
+```sh
+yui operator submit "Compare CSV and JSON compatibility" --task <task-id>
+yui operator submit "Investigate a smaller cache design"
+yui operator enter
+```
+
+Without `--task`, `operator submit` creates a new Draft. Drafts accept planning changes but must be activated before Agent execution.
+
+Add a Worker and dispatch a WorkItem:
+
+```sh
+yui task role add <task-id> implementer --agent codex
+yui task role list <task-id>
+
+yui task work create <task-id> "Implement the exporter" --role implementer
+yui task work dispatch <work-item-id> --input "Implement and run focused tests"
+```
+
+The Worker completes its current Run explicitly:
+
+```sh
+yui task run yield <run-id> --summary "Implemented the exporter; focused tests pass"
+```
+
+Yield atomically completes the Run and WorkItem, appends the result message, and queues the Leader. A Leader never wakes itself; any already-pending Operator or Worker wake remains durable until the Leader is idle.
+
+When an active Leader Run cannot continue without a user decision, it can create a durable InputRequest and yield its Run:
+
+```sh
+yui task input request <task-id> --question "Which format should be the default?" \
+  --choice csv="CSV" --choice json="JSON" --blocks work-item:<work-item-id>
+yui task input list
+yui task input show <input-id>
+yui task input answer <input-id> --choice csv
+```
+
+Requests are user-required by default and remain open until answered or cancelled. When the Agent has a safe recommendation, it may attach a choice fallback and explicit timeout:
+
+```sh
+yui task input request <task-id> --question "Which format should be the default?" \
+  --choice csv="CSV" --choice json="JSON" \
+  --recommend csv --timeout-seconds 300
+```
+
+The recommendation is shown to the user. If no answer arrives, the first Controller scan at or after the deadline atomically applies that exact choice and queues the fixed Leader session to resume. Free-text and user-required requests never auto-resolve.
+
+`task input list` is the authoritative global open-input Inbox; add a Task ID to scope it, or `--all` to include answered and cancelled requests. The Controller also makes one receipt-backed, best-effort delivery to an already-running Operator composer. It never starts or interrupts an Operator for this notification; an absent or busy Operator falls back to the durable Inbox and is reconsidered on a later Controller scan. Answers may be submitted by the user or Operator. An open request prevents unrelated pending wakes and Task completion or archival. The originating Leader may instead run `yui task input cancel <task-id> <input-id> --reason "..."`; cancellation does not self-wake it.
+
+Inspect the result:
+
+```sh
+yui task context <task-id>
+```
+
+Use the narrower `task work`, `task message`, `task run`, and Task Knowledge commands when you need one collection or record.
+
+When the requested outcome is finished, complete the Task to stop automatic Leader wakes without deleting its sessions or Role worktrees:
+
+```sh
+yui task complete <task-id> --summary "CSV export shipped and verified"
+yui task reopen <task-id>
+```
+
+Completed Tasks reject messages, dispatch, enter, retry, and late yields until explicitly reopened. Archive remains terminal and performs tmux/worktree cleanup.
+Task lifecycle completion/selection only suggests valid source states: Draft for activate, active for complete, and completed for reopen.
+
+## Sessions and tmux
+
+Yui never proxies an interactive Agent terminal. Before `operator enter`, `role enter`, or `task enter` attaches, Yui closes readline, leaves raw mode, pauses its stdin, and synchronously hands the terminal to tmux. As a result, native Codex features such as `/model`, slash-command suggestions, full-screen rendering, and key handling remain available.
+
+```sh
+yui role enter <global-role>
+yui task enter <task-id> [role]
+yui task role enter <task-id> <role>
+```
+
+Each Role can bind multiple configured Agents, has one active Agent, and keeps a separate native session per Agent binding. Switching Agents preserves dormant sessions; switching is blocked while that Role has an active Run or native process.
+
+Claude session IDs are preallocated at launch. Managed Codex launches use Codex's structured `notify` callback; after a completed turn, the callback records the native thread ID without injecting a session-binding prompt into the model conversation.
+
+## Controller and failure handling
+
+One background Controller runs per `YUI_HOME`:
+
+```sh
+yui controller status
+yui controller stop
+yui controller restart
+```
+
+`controller restart` replaces the Controller process and its scheduler/socket services with the currently installed Yui version. It does not stop or restart managed tmux/Agent sessions.
+
+Its full reconciliation pass runs every 30 seconds by default; durable state changes still request an immediate pass. The retained loop is:
+
+1. prepare active repository workspaces;
+2. stop archived Task tmux sessions and clean only clean worktrees;
+3. deliver queued Worker Runs;
+4. detect exited active Role processes;
+5. dispatch pending Leader wakes when the Leader is idle.
+
+Automated input is sent only through tmux, after an Agent-specific readiness check. A pane-local receipt prevents the same Run from being typed twice after a Controller retry.
+
+If a Role process exits before yielding, the Controller fails that Run and running WorkItem and queues the Leader. Recovery failures are exposed through the small compatibility Jobs view:
+
+```sh
+yui jobs list
+yui jobs retry leader-recovery:<task-id>
+yui task reconcile <task-id>
+yui task run retry <failed-run-id>
+```
+
+`jobs` is not a restored generic queue: it presents durable pending Leader wakes and Leader recovery failures only.
+
+Completion is the reversible execution fence. Archiving is terminal: it fails active Runs, stops the Task's tmux session, and removes each clean Role worktree. Dirty Role worktrees are preserved for deliberate cleanup.
+
+## Management commands
+
+The restored management surface includes:
+
+```sh
+yui update
+yui agent add|list|show|update|remove
+yui role add|list|show|update|remove|bind|enter
+yui role session record|replace
+yui repository add|list
+```
+
+Agent environment bindings store process-environment variable names, never secret values. Adapter-owned lifecycle arguments cannot be overridden through raw arguments.
+
+## Scope
+
+Yui targets one trusted local user on one machine. It intentionally omits Web/API surfaces, distributed coordination, backup/import/export commands, trash/restore, derived indexes, recovery journals, runtime leases, inactivity TTLs, cooldowns, and recurring schedules.
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for persistence and scheduling details.
+
+## Development
+
+```sh
+npm run build
+npm test
+npm run lint
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/agent/adapterCatalog.js

@@ -0,0 +1,10 @@
+export const AGENT_ADAPTER_CATALOG = Object.freeze([
+    Object.freeze({ id: "codex", label: "Codex" }),
+    Object.freeze({ id: "claude", label: "Claude" })
+]);
+export function supportedAgentAdapterIds() {
+    return AGENT_ADAPTER_CATALOG.map(({ id }) => id).sort();
+}
+export function isAgentAdapterId(value) {
+    return value === "codex" || value === "claude";
+}

package/dist/agent/agent.js

@@ -0,0 +1,89 @@
+import { isAgentAdapterId } from "./adapterCatalog.js";
+import { validateAgentBaseArguments } from "./argumentPolicy.js";
+export function createConfiguredAgent(id, adapterId, command, baseArgs, environment, now) {
+    const normalizedId = requireSafeIdentity(id, "Agent id");
+    if (!isAgentAdapterId(adapterId))
+        throw new Error(`Agent adapter is unsupported: ${adapterId}.`);
+    const normalizedCommand = requireText(command, "Agent command");
+    validateAgentBaseArguments(adapterId, baseArgs);
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: 2,
+        id: normalizedId,
+        adapterId,
+        command: normalizedCommand,
+        baseArgs: [...baseArgs],
+        environment: environment.map(validateEnvironmentBinding),
+        createdAt: timestamp,
+        updatedAt: timestamp
+    };
+}
+export function configuredAgentToDefinition(agent) {
+    validateConfiguredAgent(agent);
+    return {
+        ...agent,
+        baseArgs: [...agent.baseArgs],
+        environment: agent.environment.map((binding) => ({ ...binding })),
+        source: "custom"
+    };
+}
+export function resolveAgentEnvironment(agent, processEnvironment = process.env) {
+    return Object.fromEntries(agent.environment.flatMap((binding) => {
+        const normalized = validateEnvironmentBinding(binding);
+        const value = processEnvironment[normalized.sourceName];
+        if (value === undefined) {
+            if (normalized.required) {
+                throw new Error(`Required Agent environment is missing: ${normalized.sourceName}.`);
+            }
+            return [];
+        }
+        return [[normalized.target, value]];
+    }));
+}
+export function validateConfiguredAgent(agent) {
+    if (agent.schemaVersion !== 2)
+        throw new Error("Agent schema version is invalid.");
+    requireSafeIdentity(agent.id, "Agent id");
+    if (!isAgentAdapterId(agent.adapterId))
+        throw new Error(`Agent adapter is unsupported: ${agent.adapterId}.`);
+    requireText(agent.command, "Agent command");
+    validateAgentBaseArguments(agent.adapterId, agent.baseArgs);
+    if (!Array.isArray(agent.environment))
+        throw new Error("Agent environment must be an array.");
+    agent.environment.forEach(validateEnvironmentBinding);
+    requireText(agent.createdAt, "Agent creation timestamp");
+    requireText(agent.updatedAt, "Agent update timestamp");
+}
+function validateEnvironmentBinding(binding) {
+    if (binding === null || typeof binding !== "object" || Array.isArray(binding)) {
+        throw new Error("Agent environment binding must be an object.");
+    }
+    if (binding.source !== "process" || typeof binding.required !== "boolean"
+        || !isEnvironmentName(binding.target) || !isEnvironmentName(binding.sourceName)) {
+        throw new Error("Agent environment binding is invalid.");
+    }
+    return {
+        target: binding.target,
+        source: "process",
+        sourceName: binding.sourceName,
+        required: binding.required
+    };
+}
+function isEnvironmentName(value) {
+    return typeof value === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function requireSafeIdentity(value, label) {
+    const normalized = requireText(value, label);
+    if (["__proto__", "prototype", "constructor"].includes(normalized) || /[\/\\\0]/.test(normalized)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid.`);
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}

package/dist/agent/agentRegistry.js

@@ -0,0 +1,10 @@
+import { configuredAgentToDefinition } from "./agent.js";
+export function resolveAgent(id, agents = []) {
+    return listAgentDefinitions(agents).find((agent) => agent.id === id) ?? null;
+}
+export function listAgentDefinitions(agents = []) {
+    return agents.map(configuredAgentToDefinition);
+}
+export function supportedAgentIds(agents = []) {
+    return listAgentDefinitions(agents).map((agent) => agent.id);
+}

package/dist/agent/argumentPolicy.js

@@ -0,0 +1,80 @@
+const OWNED_ARGUMENTS_BY_ADAPTER = {
+    codex: [
+        "resume", "fork", "exec", "e", "review",
+        "--model", "-m", "--config", "-c", "--sandbox", "-s",
+        "--ask-for-approval", "-a", "--search", "--profile", "-p",
+        "--add-dir", "--cd", "-C", "--full-auto",
+        "--dangerously-bypass-approvals-and-sandbox",
+        "--dangerously-bypass-hook-trust"
+    ],
+    claude: [
+        "--resume", "-r", "--continue", "-c", "--session-id", "--fork-session",
+        "--model", "--effort", "--permission-mode", "--allowed-tools", "--allowedTools",
+        "--disallowed-tools", "--disallowedTools", "--add-dir", "--settings",
+        "--setting-sources", "--worktree", "-w", "--tmux", "--print", "-p",
+        "--agents", "--bg", "--background", "--dangerously-skip-permissions",
+        "--allow-dangerously-skip-permissions", "--no-session-persistence", "--from-pr",
+        "--fallback-model", "--tools"
+    ]
+};
+export function ownedArgumentsForAdapter(adapterId) {
+    return OWNED_ARGUMENTS_BY_ADAPTER[adapterId];
+}
+export function findReservedAgentArgument(adapterId, argument) {
+    if (argument === "--")
+        return "--";
+    const owned = new Set(ownedArgumentsForAdapter(adapterId));
+    const equalsToken = argument.split("=", 1)[0];
+    if (owned.has(argument) || owned.has(equalsToken))
+        return equalsToken;
+    if (!argument.startsWith("-") || argument.startsWith("--"))
+        return null;
+    const shortOptions = new Set([...owned].filter((value) => /^-[^-]$/.test(value)));
+    for (const flag of argument.slice(1)) {
+        const token = `-${flag}`;
+        if (shortOptions.has(token))
+            return token;
+    }
+    return null;
+}
+/** Escape-hatch arguments cannot override fields or lifecycle owned by an adapter. */
+export function validateAgentAdvancedArguments(adapterId, rawArgs) {
+    validateArgumentList(rawArgs, "Advanced rawArgs");
+    for (const argument of rawArgs) {
+        const reserved = findReservedAgentArgument(adapterId, argument);
+        if (reserved !== null)
+            throw new Error(`Advanced rawArgs contains reserved argument: ${reserved}.`);
+    }
+}
+export const validateAgentRawArguments = validateAgentAdvancedArguments;
+export function validateAgentBaseArguments(adapterId, baseArgs) {
+    validateArgumentList(baseArgs, "Agent base arguments");
+    for (const argument of baseArgs) {
+        const reserved = findReservedAgentArgument(adapterId, argument);
+        if (reserved !== null) {
+            throw new Error(`Agent base argument is reserved by adapter ${adapterId}: ${reserved}.`);
+        }
+    }
+}
+function validateArgumentList(values, label) {
+    if (!Array.isArray(values))
+        throw new Error(`${label} must be an array.`);
+    for (const value of values) {
+        if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
+            throw new Error(`${label} entries must be non-empty strings without NUL bytes.`);
+        }
+        const option = value.split("=", 1)[0];
+        if (containsSecretMarker(option) || containsSecretJson(value) || looksLikeCredential(value)) {
+            throw new Error(`${label} cannot persist secret-bearing arguments.`);
+        }
+    }
+}
+function containsSecretMarker(value) {
+    return /(?:api[-_]?key|token|secret|password|credential|authorization)/i.test(value);
+}
+function containsSecretJson(value) {
+    return /["']?(?:api[-_]?key|token|secret|password|credential|authorization)["']?\s*:/i.test(value);
+}
+function looksLikeCredential(value) {
+    return /(?:^|[=:\s])(?:sk-[A-Za-z0-9_-]{8,}|gh[pousr]_[A-Za-z0-9]{8,}|Bearer\s+\S+)/i.test(value);
+}

package/dist/brief/taskBrief.js

@@ -0,0 +1,37 @@
+export function createTaskBrief(input, now) {
+    return {
+        schemaVersion: 1,
+        objective: requireText(input.objective, "Task objective"),
+        boundaries: normalizeBoundaries(input.boundaries),
+        currentFocus: requireText(input.currentFocus, "Current focus"),
+        leaderSummary: requireText(input.leaderSummary, "Leader summary"),
+        updatedAt: now.toISOString(),
+        updatedBy: requireText(input.updatedBy, "Task Brief updated by")
+    };
+}
+export function updateTaskBrief(brief, patch, updatedBy, now) {
+    return createTaskBrief({
+        objective: patch.objective ?? brief.objective,
+        boundaries: patch.boundaries ?? brief.boundaries,
+        currentFocus: patch.currentFocus ?? brief.currentFocus,
+        leaderSummary: patch.leaderSummary ?? brief.leaderSummary,
+        updatedBy
+    }, now);
+}
+function normalizeBoundaries(values) {
+    const normalized = values.map((value) => {
+        if (typeof value !== "string" || value.includes("\0")) {
+            throw new Error("Task boundary is invalid.");
+        }
+        return value.trim();
+    }).filter(Boolean);
+    return [...new Set(normalized)];
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid.`);
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}