# FileRef / file tools の symlink 診断と外部参照導線

## 背景

insomnia 開発では、外部の参考プロジェクトを `ghq` のローカル clone として参照する運用がある。今回、workspace 内へ外部 clone を指す symlink を置き、`@tmp/<external-project>` として読ませようとしたが、参照側からは期待通りに読めなかった。

このような symlink は、壊れている場合、相対リンクの基準が利用者の期待と違う場合、または canonicalize 後の target が Pod の readable scope 外に出る場合がある。現状は `file not found` のように見えやすく、壊れた symlink なのか、scope 外なのか、Glob / FileRef が symlink directory を辿らない仕様なのか判断しにくい。

一方で、symlink を無条件に辿ると workspace scope の外へ読み書きできる escape になるため、単純に許可してはいけない。canonicalized target が effective scope 内かどうかを明確に検査し、失敗時は理由を出す必要がある。

## 要件

### symlink 診断

FileRef / completion / read 系の file handling で、対象 path または途中 component が symlink の場合に、失敗理由を区別して報告できるようにする。

最低限、以下を区別する。

- symlink target が存在しない（broken symlink）
- symlink target が Pod の readable scope 外に解決される
- target は scope 内だが directory traversal / glob 側が symlink directory を辿っていない
- target は scope 内だが file / directory 種別が期待と違う

エラー文には、可能な範囲で元 path と解決後 target を含める。

### scope safety

symlink は canonicalize 後の target で scope 判定する。

- read: canonicalized target が readable scope 内の場合のみ許可
- write: canonicalized target が writable scope 内の場合のみ許可
- scope 外の場合は拒否し、`read scope に target を追加する` / `workspace 内へコピーする` / `正しい symlink を作り直す` などの対処を示す

既存の symlink escape 防止テストは維持する。

### 外部 ghq 参照の導線

外部参考プロジェクトを `ghq` から読む運用に対して、推奨手順を明文化する。

候補:

- Pod 起動時 / spawn 時に ghq clone の実体 path を read scope に入れる
- workspace 内 symlink を使う場合も、target が readable scope 内に入っている必要があることを明記する
- broken relative symlink を検出した場合、絶対 symlink または正しい相対 symlink を促す

### 対象 surface

少なくとも以下のいずれか、または共通層を通じて同等の挙動になること。

- submit 時 `Segment::FileRef` の resolver
- TUI completion の file candidate 表示
- generic file read / glob 系 tool
- auto-read / fs view が同じ file handling を使う場合はその経路

## 範囲外

- readable scope 外 symlink を安全確認なしに自動許可すること
- symlink target を自動で scope に追加すること
- ghq clone の自動探索や自動 clone
- write scope の owner handoff / Pod sleep など権限モデル自体の変更
- Git submodule / worktree の設計変更

## 完了条件

- broken symlink、scope 外 symlink、scope 内 symlink directory の挙動が区別できる
- scope 外 symlink は canonicalized target で拒否され、明確なエラーになる
- scope 内 symlink file / directory は、仕様として許可するか拒否するかが明文化され、テストされている
- FileRef または file tool のテストで symlink 経路がカバーされる
- ghq など外部参照プロジェクトを読む場合の推奨手順が docs または ticket 内に記録されている

## 参照

- `crates/tools/src/scoped_fs.rs`
- `crates/tools/tests/edge_cases.rs`
- `crates/pod/src/pod.rs` `resolve_file_refs`
- `crates/pod/src/fs_view.rs`
- `crates/manifest/src/scope.rs`