README.md改訂

1 files changed, 229 insertions, 104 deletions

diff --git a/README.md b/README.md
index d1bde9f..96f08f7 100644
--- a/README.md
+++ b/README.md
@@ -1,62 +1,146 @@
-# AI Agent Sandbox MCP Server v1
+# AI Agent Sandbox MCP Server
 
-Windows 11上でOllamaを利用し、利用者が確認したWorkspace、Mount、Executable、Network、Resourceの範囲だけをLPAC内で実行するMCP Serverです。MCP `2026-07-28`のstateless HTTPと公式Tasks Extensionに対応し、MCP公開Toolは `agent_run` と `agent_status` の2つです。
+Windows上でローカルのOllamaを利用し、AIエージェントのファイル操作とプロセス実行を、利用者が確認した範囲に閉じ込めるMCP Serverです。
 
-## 動作要件
+MCP Clientには `agent_run` と `agent_status` だけを公開します。エージェントが内部で行うファイル操作・プロセス実行は、Workspace、Mount、承認済みExecutable、Network、Resourceの設定とWindowsの強制機構によって制限されます。
 
-- Windows 11 x64
-- 管理者権限（TaskごとのWFP filter追加・削除に必要）
-- Base Filtering Engine (BFE)が実行中
-- Ollama。tested versionは実測した `0.32.6`。minimum supported versionは未確定です。
-- Release既定model: `deepseek-v4-flash:cloud`（native Internal Tool calling対応）
+## 主な機能
 
-サービス、常駐helper、恒久Firewall ruleは使用しません。WFP objectはdynamic sessionだけに作成されます。AppContainerからlocalhostへ接続するTaskでは、固定AppContainer SIDのloopback exemptionをTask中だけ追加し、終了時または次回起動Recoveryで削除します。
+- Ollamaモデルによる、計画・コード作成・ファイル編集・コマンド実行の自動化
+- MCPのstdioとStreamable HTTP（stateless）への対応
+- MCP Tasks Extensionによる非同期Taskの取得・キャンセル
+- WorkspaceとMountを分けた、読み取り・書き込み・削除・実行の権限設定
+- 実行前に人間が確認するExecutable AliasとSHA-256承認
+- LPAC、NTFS ACL、Job Object、WFPによるSandbox Process Treeの制限
+- 日本語・英語のメッセージ、監査ログ、異常終了後の自動Recovery
+- `agent.yaml`と、環境ごとの差分を置ける`agent.local.yaml`のマージ
+
+## 動作環境
+
+| 項目 | 要件 |
+| --- | --- |
+| OS | Windows 11 x64 |
+| 権限 | 管理者権限のPowerShell。TaskごとのWFP設定に必要です。 |
+| Windowsサービス | Base Filtering Engine（BFE）が起動していること |
+| LLM | Ollama。Release既定モデルは`deepseek-v4-flash:cloud`です。 |
+| MCP Client | stdioまたはStreamable HTTPを利用できるClient |
+
+Ollamaへの通信はBroker側で行われます。Sandbox内プロセスのNetwork許可とは別に設定されます。
+
+## インストール
+
+Release Bundleを任意のディレクトリへ展開します。以降の例では、展開先を`<install-dir>`と表記します。
+
+```text
+<install-dir>/
+  agent-mcp.exe
+  agent.yaml
+  prompts/
+  skills/
+```
+
+`agent.yaml`は配布時の共通設定です。利用者固有の設定は、同じディレクトリに`agent.local.yaml`を作成して記載してください。publishやupgradeは`agent.local.yaml`、`local/`、`logs/`、`state/`、ユーザーごとの承認・確認情報を上書きしません。
 
 ## 初回セットアップ
 
-管理者としてPowerShellを起動し、Release Bundleへ移動します。
+### 1. Ollamaを準備する
+
+Ollamaをインストール後、モデルを取得して起動します。
 
 ```powershell
-ollama --version
 ollama pull deepseek-v4-flash:cloud
 ollama serve
 ```
 
-初回はUser Sandbox ConfigurationのLogical Pathを確認してから、別の管理者PowerShellで診断します。
+既にOllama Serviceまたは`ollama serve`が起動している場合、重複して起動する必要はありません。
+
+### 2. ローカル設定を作成する
+
+`agent.yaml`と同じディレクトリへ`agent.local.yaml`を作成します。最小例は次のとおりです。
+
+```yaml
+application:
+  language: ja
+
+agent:
+  user_system_prompt: local/prompts/user-system.md
+
+skills:
+  directory: local/skills
+
+sandbox:
+  profile: development
+  workspaces:
+    - C:/work/project
+  mounts: []
+  execution:
+    executables: [python]
+    shells: []
+```
+
+`agent.local.yaml`は、共通設定から変更したい項目だけを書きます。mapは再帰的にマージされ、scalarと配列はlocal側で置換されます。そのため、`workspaces`や`mounts`をlocal側に書く場合は、最終的に必要な要素をすべて列挙してください。
+
+相対パスは`agent.yaml`のあるディレクトリを基準に解決されます。マージ後の設定全体に対して検証が行われるため、未知のキーや矛盾した設定は起動前にエラーになります。
+
+### 3. Sandboxの対象を確認する
+
+管理者としてPowerShellを起動し、展開先へ移動します。
 
 ```powershell
+cd <install-dir>
 .\agent-mcp.exe sandbox resolve --config .\agent.yaml
-.\agent-mcp.exe executable resolve python --config .\agent.yaml
-.\agent-mcp.exe executable approve python --path C:\Python314\python.exe --runtime-root C:\Python314 --config .\agent.yaml
 .\agent-mcp.exe sandbox confirm --config .\agent.yaml
 .\agent-mcp.exe sandbox show --format text --config .\agent.yaml
-.\agent-mcp.exe check --config .\agent.yaml --lang ja
 ```
 
-`administrator=true`、`bfe_engine_open=true`、`wfp_write_transaction=true`、`wfp_filter_add_delete=true` が必要です。probeはdynamic WFP filterを追加後すぐ削除し、残留させません。
+`resolve`は設定されたパスを実体パスへ解決して表示するだけです。内容を確認した後、`confirm`で確認済み結果をユーザーごとのStoreへ保存します。Workspace、Mount、設定内容またはリンクの解決先が変わると、再確認するまで起動はfail-closedになります。
 
-`serve`も待受開始前に同じprobeを必ず実行します。失敗時はendpointをbindせず、失敗項目・Win32 error・対処方法をstderrと`logs/application.log`へ出してexit code 2で終了します。
+### 4. 使用するExecutableを承認する
 
-## User Sandbox Configuration
+設定したAliasごとに、実行ファイルの候補を確認し、使用する実体を明示して承認します。
 
-`schema_version: 1`のSandbox設定は利用者が理解できるsemantic単位で記述します。未指定capabilityはdenyです。
+```powershell
+.\agent-mcp.exe executable resolve python --config .\agent.yaml
+.\agent-mcp.exe executable approve python `
+  --path C:\Python314\python.exe `
+  --runtime-root C:\Python314 `
+  --config .\agent.yaml
+.\agent-mcp.exe executable list --config .\agent.yaml
+```
+
+承認時にはResolved PathとSHA-256が保存されます。実行ファイルのパスまたはハッシュが変わった場合は、自動では更新されず、再承認が必要です。
+
+最後に起動前診断を実行します。
+
+```powershell
+.\agent-mcp.exe check --config .\agent.yaml --lang ja
+```
+
+## Sandbox設定
+
+`schema_version: 1`の設定では、Sandboxを利用者が理解できる単位で指定します。未指定の権限は許可されません。
 
 ```yaml
 sandbox:
   profile: development
+
   workspaces:
     - C:/work/project
+
   mounts:
     - path: C:/data/reference
       access: read_only
+
   execution:
     executables: [python, git]
     shells: [powershell]
+
   network:
     access: local
     local_endpoints:
       - port: 11434
     restricted_endpoints: []
+
   resources:
     profile: normal
     # memory_mb: 4096
@@ -64,153 +148,194 @@ sandbox:
     # execution_timeout_seconds: 1800
 ```
 
-`readonly` ProfileはWorkspaceをread-onlyにし、Workspace ArtifactのEntry起動を禁止します。`development`はWorkspaceのread/write/deleteとArtifact起動を許可します。Mountは`read_only`、`read_write`、`read_write_delete`から選び、Mount上のExecutableをEntry Processとして起動することはできません。
+### WorkspaceとMount
 
-Resource Profileは`constrained`（1024 MiB/4 Process/300秒）、`normal`（4096 MiB/16 Process/1800秒）、`extended`（8192 MiB/32 Process/3600秒）です。正数overrideを指定できます。
+| 設定 | 用途 | 実行 |
+| --- | --- | --- |
+| `workspaces` | エージェントが作業するプロジェクト領域 | `development`ではWorkspace内の成果物をEntry Processとして実行できます。 |
+| `mounts` | 参照データや追加の入出力領域 | Mount上のExecutableは直接起動できません。 |
 
-Network accessは`none`、`local`、`restricted`です。`none`はLoopbackを含め全deny、`local`は列挙portの`127.0.0.1`と`::1`だけ、`restricted`はTask開始時にIP snapshot化したhost/portだけを許可します。Ollama通信はBroker側から行うため、Sandbox Process TreeのNetwork設定とは独立です。
+`profile`には次を指定します。
 
-Workspace/Mountはreparse chainをResolved Pathへ解決します。`sandbox resolve`で差分を確認し、`sandbox confirm`でconfig別のResolution Storeへ保存してください。config fingerprintまたはResolved Pathが変わると`serve`は再確認までfail-closedになります。
+| Profile | Workspaceの権限 | Workspace ArtifactのEntry実行 |
+| --- | --- | --- |
+| `readonly` | read | 不可 |
+| `development` | read / write / delete | 可 |
 
-```powershell
-.\agent-mcp.exe sandbox resolve --config .\agent.yaml
-.\agent-mcp.exe sandbox confirm --config .\agent.yaml
-.\agent-mcp.exe sandbox show --format json --config .\agent.yaml
-```
+Mountの`access`には`read_only`、`read_write`、`read_write_delete`を指定します。`readonly` Profileでは`read_only`だけが使用できます。
 
-## Executable Approval
+### ExecutableとShell
 
-`sandbox.execution`には人間向けAliasを記載します。PATH候補は提示だけで自動選択されません。選んだResolved PathとSHA-256をuser-local Approval Storeへ固定します。
+`execution.executables`と`execution.shells`には、実行を許可したいAliasを記載します。Aliasを設定しただけでは実行できず、前節の`executable approve`で実体パスとハッシュを承認する必要があります。
 
-```powershell
-.\agent-mcp.exe executable resolve python --config .\agent.yaml
-.\agent-mcp.exe executable approve python --path C:\Python314\python.exe --runtime-root C:\Python314 --config .\agent.yaml
-.\agent-mcp.exe executable list --config .\agent.yaml
-.\agent-mcp.exe executable revoke python --config .\agent.yaml
-```
+- Executable: 例 `python`、`git`
+- Shell: `cmd.exe`、`powershell.exe`、`pwsh.exe`に対応するAlias
 
-Approved Entry Executable／Approved Shell ExecutableはAlias、Resolved Path、SHA-256一致が必要です。確認済みRuntime Root内のRuntime Componentと、development Workspace内のWorkspace ArtifactもEntry Processにできます。その他のExternal Unknown ExecutableをBrokerから直接起動することはできません。
+承認は最初にBrokerが直接起動するEntry Processにだけ適用されます。Entry Processから生成される子孫Processには個別承認を要求しませんが、同じLPAC、ACL、WFP、Job Objectの制限を継承します。未知の外部ExecutableやMount上のExecutableは、Brokerから直接起動できません。
 
-ApprovalはEntry Processにだけ適用されます。Descendant Processは個別Approvalを要求せず、Entry Processと同じLPAC token、Filesystem ACL、WFP、Job Objectを継承します。Jobからのbreakawayは禁止され、Process数・memory・timeout・`KILL_ON_JOB_CLOSE`はProcess Tree全体へ適用されます。
+### Network
 
-Sandbox Process Treeへは最小限のWindows/runtime環境変数だけを渡し、Brokerの任意token、password、SSH/API credential環境変数は継承しません。User profile等のpathが環境に含まれても、そのpathへFilesystem Capabilityは付与されません。
+| `access` | 許可内容 |
+| --- | --- |
+| `none` | localhostを含むすべてのネットワーク通信を拒否します。 |
+| `local` | `local_endpoints`に列挙したportへの`127.0.0.1`および`::1`だけを許可します。 |
+| `restricted` | `restricted_endpoints`に列挙したhost/portをTask開始時にIPへ固定して許可します。 |
 
-Executable Approval StoreとResolution Storeは`%LOCALAPPDATA%\AgentSandboxMcp`にuser-only DACL、WriteThrough、atomic replaceで保存されます。publishやupgradeはこれらのStoreを上書きしません。
+空のendpoint設定やmodeと矛盾する設定は拒否されます。
 
-## その他のagent.yaml設定
+### Resource
 
-MCP Taskの保持とlog出力は次のtyped settingで変更できます。
+`resources.profile`の既定値は以下です。個別の正数指定で上書きできます。
 
-```yaml
-mcp:
-  tasks:
-    time_to_live_hours: 24
-    poll_interval_ms: 1000
-logging:
-  directory: logs
-  level: information       # information / warning / error / fatal
-  http_requests: true
-  max_file_bytes: 10485760
-  retained_files: 5
-```
+| Profile | メモリ | Process数 | 実行時間 |
+| --- | ---: | ---: | ---: |
+| `constrained` | 1024 MiB | 4 | 300秒 |
+| `normal` | 4096 MiB | 16 | 1800秒 |
+| `extended` | 8192 MiB | 32 | 3600秒 |
 
-配布された`agent.yaml`と同じdirectoryに任意の`agent.local.yaml`を置くと、環境固有値だけを上書きできます。mapは再帰merge、scalarと配列はlocal側で置換され、merge後の全設定を通常どおり検証します。相対pathは`agent.yaml`のdirectory基準です。local設定から利用者固有のSystem PromptやSkill directoryを指定できます。`agent.local.yaml`と、その参照先prompt／SkillはRelease Bundleへ含まれず、publishでも上書きされません。雛形は`config/agent.local.example.yaml`です。
+## CLIリファレンス
 
-引数なし、または最初の引数がoptionの場合は`serve`として扱われます。次の2つは同じです。
+すべてのCLI commandは`agent-mcp.exe`から実行します。`serve`と`check`では`--config`を省略でき、その場合は実行ファイルと同じディレクトリの`agent.yaml`を使用します。`executable`および`sandbox`の管理commandでは`--config`が必須です。
 
-```powershell
-.\agent-mcp.exe serve --config .\agent.yaml
-.\agent-mcp.exe --config .\agent.yaml
-```
+| Command | 必須の位置引数 | 使用できるoption | 用途 | 設定・Storeの変更 |
+| --- | --- | --- | --- | --- |
+| `[serve]` | なし | `--config <file>`、`--lang <locale>`、`--transport <stdio\|http>` | MCP Serverを起動します。commandを省略した場合、または最初の引数がoptionの場合も`serve`として扱います。 | なし。ただしTask実行中には一時的なSandbox Resourceを適用します。 |
+| `check` | なし | `--config <file>`、`--lang <locale>` | 設定、Resolution、Approval、管理者権限、BFE、WFP操作を診断します。 | なし |
+| `executable resolve` | `<alias>` | `--path <path>`、`--config <file>`、`--lang <locale>` | Aliasに対応するPATH候補、または指定pathを解決して表示します。 | なし |
+| `executable approve` | `<alias>` | `--path <path>`、`--runtime-root <path>`または`--no-runtime`、`--yes`、`--config <file>`、`--lang <locale>` | ExecutableまたはShellの実体パスとSHA-256を承認します。 | Approval Storeを更新 |
+| `executable list` | なし | `--config <file>`、`--lang <locale>` | 承認済みExecutableを一覧表示します。 | なし |
+| `executable revoke` | `<alias>` | `--yes`、`--config <file>`、`--lang <locale>` | AliasのExecutable Approvalを取り消します。 | Approval Storeを更新 |
+| `sandbox resolve` | なし | `--config <file>`、`--lang <locale>` | WorkspaceとMountのLogical Pathを実体パスへ解決し、確認候補を表示します。 | なし |
+| `sandbox confirm` | なし | `--yes`、`--config <file>`、`--lang <locale>` | 現在のSandbox Environment Resolutionを確認済みとして保存します。 | Resolution Storeを更新 |
+| `sandbox show` | なし | `--format <text\|json>`、`--config <file>`、`--lang <locale>` | 現在のResolution、確認状態、Effective Sandbox Policyを表示します。 | なし |
+
+### 引数とoptionの意味
+
+| 引数・option | 値 | 説明 |
+| --- | --- | --- |
+| `<alias>` | 設定したAlias名 | `sandbox.execution.executables`または`sandbox.execution.shells`に宣言した名前です。Alias自体は承認を意味しません。 |
+| `--config <file>` | YAMLファイルのpath | base設定ファイルを指定します。同じディレクトリの`agent.local.yaml`は自動的にマージされます。 |
+| `--lang <locale>` | 例: `ja`、`en` | CLIおよび起動時の利用者向けメッセージの言語を、その実行に限って上書きします。 |
+| `--transport <stdio\|http>` | `stdio`または`http` | `serve`時だけ使用できます。設定ファイルの`mcp.transport`をその起動に限って上書きします。 |
+| `--path <path>` | Executable fileのpath | `executable resolve`では候補検索対象、`executable approve`では承認対象を明示します。候補が曖昧な場合は必須です。 |
+| `--runtime-root <path>` | Runtime directoryのpath | 承認するEntry ExecutableのRuntime Rootを明示します。存在するディレクトリでなければなりません。 |
+| `--no-runtime` | 値なし | Runtime Rootを登録しないことを明示します。`executable approve`では`--runtime-root`とのどちらか一方が必要です。 |
+| `--yes` | 値なし | `approve`、`revoke`、`confirm`の対話確認を省略します。非対話操作としてAudit Logに記録されます。 |
+| `--format <text\|json>` | `text`または`json` | `sandbox show`の出力形式です。既定値は`text`です。 |
 
-Task状態は`state/mcp-tasks/`へatomic保存されます。再起動時の未完了Taskは`failed/server_restarted`となり、自動再実行されません。
+`resolve`、`list`、`show`、`check`はread-onlyです。`approve`、`revoke`、`confirm`は差分表示後に確認を求めます。標準入力が対話的でない場合は、内容を確認したうえで明示的に`--yes`を指定してください。
 
-## Agent Skills
+## 起動と接続
 
-`skills/<skill-name>/SKILL.md`形式だけを読み込みます。legacyの`skills/*.md`は読み込みません。SkillはLLMへの補助指示であり、Sandbox capabilityは付与しません。Skillが使うHost ExecutableはAliasを設定し、Entry起動前に承認してください。
+`serve`は起動前に管理者権限、BFE、WFP、設定、Resolution、Executable Approvalを検査します。いずれかが失敗すると待受を開始せず、エラーと対処方法を表示します。
 
-## stdio
+### stdio
 
-WFP操作のため、stdioではMCP Client自体を管理者PowerShellから起動します。Client設定例:
+stdioを使う場合は、MCP Client自体を管理者権限で起動してください。
 
 ```json
 {
   "mcpServers": {
     "agent-sandbox": {
       "command": "C:\\tools\\agent-sandbox-mcp\\agent-mcp.exe",
-      "args": ["serve", "--config", "C:\\tools\\agent-sandbox-mcp\\agent.yaml", "--lang", "ja", "--transport", "stdio"]
+      "args": [
+        "serve",
+        "--config", "C:\\tools\\agent-sandbox-mcp\\agent.yaml",
+        "--lang", "ja",
+        "--transport", "stdio"
+      ]
     }
   }
 }
 ```
 
-`agent_run`へ自然言語の依頼を送り、返却されたUUIDを `agent_status` でterminal stateまでpollします。複数Taskはqueuedで受理しますが、planning/runningおよびTask Resource適用は全体で1件です。
+### Streamable HTTP
 
-## Streamable HTTP
-
-管理者PowerShellでserverを起動します。`MCPリクエストを受け付けられます`とendpointが表示されてから接続してください。
+管理者PowerShellでServerを起動します。
 
 ```powershell
 .\agent-mcp.exe serve --config .\agent.yaml --lang ja --transport http
 ```
 
-Client endpointは `http://127.0.0.1:8080/mcp` です。設定できるbindは `127.0.0.1` または `::1` だけです。HTTPはMCP `2026-07-28` statelessで`Mcp-Session-Id`を使用しません。SDKの旧initialize fallbackは維持しますが、GET SSE、`/sse`、`/message` Legacy SSEは利用できません。
+既定endpointは`http://127.0.0.1:8080/mcp`です。bind先には`127.0.0.1`または`::1`だけを設定できます。HTTPはstatelessであり、`Mcp-Session-Id`や旧SSE endpoint（`/sse`、`/message`）は使用しません。
+
+`serve`は既定commandなので、次も同じです。
+
+```powershell
+.\agent-mcp.exe --config .\agent.yaml
+```
+
+## MCPでの利用
+
+公開されるMCP Toolは次の2つです。
+
+| Tool | 用途 |
+| --- | --- |
+| `agent_run` | 自然言語の依頼を新規または既存のAgent Sessionへ登録します。非同期でTask IDとSession IDを返します。 |
+| `agent_status` | Taskの状態、進捗、token実績、最終結果または利用者向けエラーを取得します。 |
 
-Tasks対応clientは`agent_run`を公式MCP Taskとして受け取り、`tasks/get`と`tasks/cancel`を使用できます。非対応clientは従来どおりqueued textから`task_id`を取得し、`agent_status`でpollします。`session_id`はAgent会話IDでありHTTP transport sessionではありません。
+例えば、`agent_run`には「Workspace内にPythonプログラムとテストを作成し、実行して検証して」のような依頼を渡します。複数Taskは受付順にqueuedとなり、planning/runningとSandbox Resourceの適用は一度に1件だけです。
 
-## LogとRecovery
+Tasks Extension対応Clientでは、`agent_run`の結果をMCP Taskとして受け取り、`tasks/get`と`tasks/cancel`で追跡できます。非対応Clientでは、返された`task_id`を指定して`agent_status`を呼び出します。
 
-- `logs/application.log`: 起動・診断・管理event
-- `logs/llm.jsonl`: LLM request/response、token usage、tool result
-- `logs/audit.jsonl`: Task ID付きfile/process/policy/ACL/WFP/recovery event
-- `logs/http.jsonl`: connection/trace ID、実socketの接続元IP/port、method/path/status/duration、MCP routing header
-- `state/journals/`: crash recovery journal。正常終了後は空
-- `state/backups/`: 大容量file transaction backup。正常終了後は空
+## PromptとSkill
 
-log directoryは起動ユーザーだけがアクセスできるprotected DACLへ設定されます。起動時はMCP受付前にRecoveryを実行し、復旧不能なhash競合があれば起動しません。
+System Promptは`agent.user_system_prompt`、Skill directoryは`skills.directory`で指定します。Skillは次の形式で配置します。
+
+```text
+skills/
+  <skill-name>/
+    SKILL.md
+```
 
-HTTP logは`X-Forwarded-For`を接続元として信用せず、Authorization、Cookie、query、body、prompt、画像、Base64を保存しません。stateless HTTPでは永続接続を主張せず、request started/completedとして記録します。
+SkillはLLMに与える補助指示であり、Sandboxの権限を増やしません。Skillの記述に実行コマンドが含まれていても、Executable Alias、Approval、Filesystem権限、Network権限は通常どおり必要です。
 
-HTTP request処理はconsole/file出力と同期しません。運用logはbounded queue経由でbackground出力し、consoleが一時停止してもHTTP requestを停止させません。queue飽和時はrequest継続を優先し、drop件数をapplication logへ警告します。
+## ログ、監査、復旧
 
-LLM/Audit JSONLはtask、session、event、call単位で絞り込めます。
+| 場所 | 内容 |
+| --- | --- |
+| `logs/application.log` | 起動、診断、アプリケーションイベント |
+| `logs/llm.jsonl` | Ollama call、token使用量、Internal Tool結果 |
+| `logs/audit.jsonl` | ファイル・プロセス・Policy・ACL・WFP・Recoveryの監査イベント |
+| `logs/http.jsonl` | HTTPリクエストの接続情報と処理結果 |
+| `state/journals/` | 異常終了からの復旧用Journal |
+| `state/backups/` | 大容量ファイル編集のtransaction backup |
+
+ログは起動ユーザーだけがアクセスできるDACLで保護されます。HTTPログにはAuthorization、Cookie、request body、prompt、画像、Base64を記録しません。
+
+LLM/Audit JSONLを絞り込むには、付属のread-only scriptを使えます。
 
 ```powershell
 .\scripts\Read-AgentLog.ps1 -Path .\logs\llm.jsonl -TaskId <task-id> -Tail 100
 .\scripts\Read-AgentLog.ps1 -Path .\logs\audit.jsonl -Event policy.deny -Tail 100
 ```
 
-正常停止後、`agent-mcp.exe` descendant、追加ACL、WFP filter、loopback exemption、`state/backups`、`state/journals` が残っていないことを確認してください。loopback exemptionは `CheckNetIsolation.exe LoopbackExempt -s` で確認できます。
+起動時には未完了のJournalを復旧してからMCP受付を開始します。再起動時に未完了だったTaskは自動再実行されず、`failed/server_restarted`になります。
 
-## よくあるエラー
+## よくある問題
 
-- `error 5` / administrator=false: 管理者PowerShellから起動してください。
-- BFE open失敗: `Get-Service BFE` でBase Filtering Engineを確認してください。
-- Ollama接続失敗: `ollama list`、endpoint、model名を確認してください。
-- resolution未確認／変更: `sandbox resolve`のLogical/Resolved Path差分を確認し、`sandbox confirm`を実行してください。
-- Alias不明／Approval不足／hash変更: `executable resolve`で候補を確認し、明示したpathを`executable approve`で再承認してください。
-- Filesystem deny: 対象を適切なWorkspaceまたはMountとして設定し、Resolutionを再確認してください。
-- rollback拒否: Task中に外部processが同じfileを変更しています。Audit Logとjournalを確認し、手動reviewしてください。
+| 状況 | 対処 |
+| --- | --- |
+| 管理者権限またはWFP probeの失敗 | 管理者PowerShellから起動し、`Get-Service BFE`でBFEを確認します。 |
+| Ollama接続失敗 | `ollama list`、Ollama endpoint、model名を確認します。 |
+| Resolution未確認または変更 | `sandbox resolve`で差分を確認し、`sandbox confirm`を実行します。 |
+| Alias不明、Approval不足、hash変更 | `executable resolve`で候補を確認してから`executable approve`を実行します。 |
+| Filesystem拒否 | 対象を適切なWorkspaceまたはMountとして設定し、Resolutionを再確認します。 |
+| rollback拒否 | 外部Processが同じファイルを変更している可能性があります。Audit LogとJournalを確認し、手動で内容を確認します。 |
 
-## ソースからのbuild／release
+## 開発者向け
+
+ソースからbuild・test・releaseする場合は以下を実行します。
 
 ```powershell
 dotnet restore AgentSandboxMcp.slnx
 dotnet build AgentSandboxMcp.slnx -c Release --no-restore
 dotnet test AgentSandboxMcp.slnx -c Release --no-build --no-restore
-.\scripts\Acquire-McpConformance.ps1
-# 管理者権限でserverを起動後:
-.\scripts\Run-McpConformance.ps1 -Url http://127.0.0.1:8080/mcp
 .\scripts\Publish-Release.ps1
 ```
 
-生成物はすべてrepository rootの `build/` に集約されます。
-
-- `build/Debug/<ProjectName>/`: Debug build
-- `build/Release/<ProjectName>/`: Release build
-- `build/obj/<ProjectName>/`: restoreおよびcompiler中間生成物
-- `build/Release/publish/`: win-x64 self-contained Bundle、version付きZIP、checksum
+build成果物は`build/`、ローカル試験の証跡は`artifacts/`に作成されます。どちらもGit管理外です。
 
-`artifacts/` はローカルの試験証跡・デバッグログ用です。`artifacts/` と `build/` はどちらもGit管理外です。
+詳細な仕様と設計は[仕様書](doc/Specifications.md)、[設計書](doc/Design.md)を参照してください。
 
-Release scriptは再現可能な既定値だけを含むwin-x64 self-contained ZIP、checksum、publish manifestをstagingから生成し、ソースツリー外のfresh temporary directoryでBundleを検査します。deployment directory更新時は`agent.local.yaml`、`local/`、`logs/`、`state/`を削除・上書きしません。完全な `agent-mcp check` はResolution確認とExecutable Approval後に管理者PowerShellで実行してください。
+## ライセンス