feat(codex): improve session search and workspace tooling

Author: nikivdev

.gitignore

@@ -74,6 +74,8 @@ desktop/.tauri-dev.json
 .ai/review-log.jsonl
 .rise/
 .ai/state.json
+.ai/docs/session-changes/
+.ai/docs/session-changes-promoted/
 .ai/tasks/**/.mooncakes/
 .ai/tasks/**/_build/
 bench/moon_ffi_boundary/_build/
@@ -90,3 +92,6 @@ docs/commits/*
 !docs/commits/
 !docs/commits/readme.md
 !docs/commits/.gitkeep
+
+# local workspace bootstrap stamp
+.flow-workspace-bootstrap.json

Cargo.toml

@@ -29,6 +29,10 @@ path = "src/main.rs"
 name = "lin"
 path = "src/bin/lin.rs"
 
+[[bin]]
+name = "flow-workspace-bootstrap"
+path = "src/bin/flow-workspace-bootstrap.rs"
+
 [dependencies]
 axum = { version = "0.8", default-features = false, features = ["http1", "json", "query", "tokio"] }
 tower-http = { version = "0.6", features = ["cors"] }

docs/codex-interface.md

@@ -0,0 +1,285 @@
+# Flow Codex Interface
+
+## Short Answer
+
+Partly.
+
+Flow does **not** use `codex app-server` for every Codex command.
+There are multiple Codex lanes:
+
+- the normal Flow session lane uses the regular Codex CLI through the Flow wrapper
+- the run-owned agent lane uses `codex app-server`
+- the native commit review lane uses `codex app-server`
+- a few runtime-management helpers also use `codex app-server`
+
+So the right model is:
+
+- `f codex ...` is the user-facing interface
+- underneath, Flow chooses either:
+  - wrapped Codex CLI execution
+  - or direct `codex app-server` JSON-RPC
+
+## Main Pieces
+
+### 1. Flow wrapper
+
+File:
+
+- `scripts/codex-flow-wrapper`
+
+Role:
+
+- launches the real `codex` binary
+- materializes temporary runtime skills from Flow state
+- cleans those temporary symlinks up after the Codex process exits
+
+Important point:
+
+- this is still the normal Codex CLI, not app-server
+
+### 2. Flow Codex command layer
+
+Primary file:
+
+- `src/ai.rs`
+
+Role:
+
+- implements `f codex open`
+- implements `f codex resolve`
+- implements `f codex doctor`
+- implements session recovery, reference expansion, and runtime-skill planning
+- implements the Flow bridge into run-owned agents
+
+Important point:
+
+- most of this layer is orchestration and context shaping
+- it does not imply app-server by itself
+
+### 3. Flow codexd daemon
+
+Primary file:
+
+- `src/codexd.rs`
+
+Role:
+
+- local Flow daemon for fast repo/session intelligence
+- caches recent queryable state
+- serves project-ai and related lightweight repo intelligence
+
+Important point:
+
+- `codexd` is a Flow daemon
+- it is **not** the Codex app-server
+
+### 4. Run-owned agent runtime
+
+Primary files:
+
+- `~/run/scripts/agent-router.sh`
+- `~/run/scripts/agent-codex-app-server.py`
+
+Role:
+
+- executes spec-backed agents such as `planner`, `commit`, `input`, and `migration-planner`
+- opens or resumes threads
+- sends turns through `codex app-server`
+- persists artifacts, traces, and per-agent state
+
+Important point:
+
+- this lane is app-server-based by design
+
+## Which Paths Use App-Server
+
+### Uses the normal Codex CLI through the Flow wrapper
+
+- `f codex open`
+- `f codex resume`
+- `f codex continue`
+- `f codex connect`
+- normal interactive Codex sessions launched by Flow
+
+How it works:
+
+1. Flow resolves the repo/path and any compact context to inject.
+2. Flow may prepare runtime skill state.
+3. Flow launches the configured Codex binary, usually `scripts/codex-flow-wrapper`.
+4. The wrapper exposes runtime skills and then execs the real `codex`.
+
+### Uses `codex app-server`
+
+- `f codex agent run ...`
+- Flow native commit review
+- Codex skill reload / force-rescan helper paths
+- run-owned spec agents in `~/run`
+
+How it works:
+
+1. Flow or `~/run` spawns `codex app-server`.
+2. It performs the initialize handshake over stdio JSON-RPC.
+3. It creates or resumes a thread.
+4. It sends structured requests such as:
+   - `thread/start`
+   - `turn/start`
+   - `review/start`
+   - `skills/list`
+5. It consumes structured events and results.
+
+## Command Surface Breakdown
+
+### `f codex open`
+
+Primary behavior:
+
+- session recovery
+- compact reference expansion
+- runtime-skill activation
+- normal Codex CLI launch
+
+Transport:
+
+- wrapper + standard Codex CLI
+
+Notable files:
+
+- `src/ai.rs`
+- `scripts/codex-flow-wrapper`
+
+### `f codex doctor`
+
+Primary behavior:
+
+- inspect effective Codex config for a repo/path
+- report wrapper/runtime readiness
+- report run-agent bridge readiness
+
+Transport:
+
+- local Flow inspection only
+
+Important point:
+
+- doctor does not require app-server to explain the current configuration
+
+### `f codex agent list` / `show`
+
+Primary behavior:
+
+- inspect the run-owned agent corpus from `~/run`
+
+Transport:
+
+- Flow shells into `~/run/scripts/agent-router.sh`
+- no app-server turn is needed for `list` or `show`
+
+### `f codex agent run <agent-id> ...`
+
+Primary behavior:
+
+- execute a run-owned agent from Flow
+
+Transport:
+
+- Flow -> `~/run/scripts/agent-router.sh run-json`
+- `agent-router.sh` -> `agent-codex-app-server.py`
+- Python runner -> `codex app-server`
+
+Important point:
+
+- this is the main place where the new Flow-to-run bridge is explicitly app-server-based
+
+### `f commit` Codex review lane
+
+Primary behavior:
+
+- review staged or uncommitted changes using the Codex native review path
+
+Transport:
+
+- direct `codex app-server`
+- uses built-in `review/start`
+
+Important point:
+
+- this is a stronger primitive than sending a freeform review prompt through a normal chat turn
+
+## Why Flow Uses More Than One Lane
+
+Because the best transport depends on the job:
+
+- interactive coding sessions are best served by the normal Codex CLI with Flow-managed runtime context
+- structured agent execution needs thread control, event streaming, and durable artifacts, so app-server is the better substrate
+- native code review has a dedicated app-server method, so Flow should use that instead of imitating review in plain text
+
+## Current Mental Model
+
+Use this rule:
+
+- if you are opening or resuming a normal Codex coding session, think "wrapped Codex CLI"
+- if you are running a reusable Flow/run agent or a native review lane, think "`codex app-server`"
+
+That is the current architecture.
+
+It is intentionally hybrid:
+
+- Flow keeps the common path lightweight
+- app-server is reserved for the places where structured threads, structured review, or structured artifacts materially improve the result
+
+## Concrete Examples
+
+### Example 1: normal coding turn
+
+```bash
+f codex open --path ~/code/flow "continue the codex agent rollout"
+```
+
+Expected transport:
+
+- Flow orchestration
+- wrapper
+- normal Codex CLI
+
+### Example 2: run-owned planning agent
+
+```bash
+f codex agent run planner --path ~/code/flow "make a 3 phase rollout plan"
+```
+
+Expected transport:
+
+- Flow bridge
+- `~/run` agent router
+- `codex app-server`
+
+### Example 3: commit review
+
+```bash
+f commit --slow --context --codex
+```
+
+Expected transport:
+
+- Flow review pipeline
+- direct `codex app-server`
+- native `review/start`
+
+## Non-Goals
+
+What this interface is not doing today:
+
+- it is not making every Flow Codex command app-server-only
+- it is not using `codexkit` as the main Flow executor
+- it is not duplicating run-owned agent specs inside Flow
+
+## Summary
+
+Flow's Codex interface is a control-plane interface, not a single transport.
+
+The stable split today is:
+
+- default session UX: wrapped Codex CLI
+- structured agent execution: `codex app-server`
+- native review: `codex app-server`
+- repo intelligence and readiness checks: Flow-local logic plus `codexd`

docs/commands/ai.md

@@ -6,6 +6,10 @@ Flow reads local session stores, filters by current project path, and gives you
 When you need to reopen a repo's session from another working directory, use `--path <project-root>` on `resume` or provider-specific `continue`.
 Cursor transcripts are supported for reading only.
 
+Architecture note:
+
+- for the underlying transport split between wrapped Codex CLI, `codexd`, and `codex app-server`, see `docs/codex-interface.md`
+
 ## Quick Start
 
 ```bash
@@ -27,6 +31,12 @@ f ai claude resume <session-id-or-name>
 f ai codex resume <session-id-or-name>
 f ai codex resume --path ~/work/example-project
 f ai codex continue --path ~/work/example-project
+f ai codex find --path ~/repos/openai/codex "where does codex store"
+f ai codex find --all-history --path ~/repos/openai/codex "older migration plan"
+f ai codex find --recent-days 30 --path ~/repos/openai/codex "thread/read"
+f ai codex find --json --limit 5 --path ~/repos/openai/codex "thread/read"
+f codex connect --path ~/repos/openai/codex --exact-cwd --json "app-server"
+f codex connect --all-history --path ~/repos/openai/codex "old designer cutover"
 f ai cursor context - /path/to/repo 3
 f cursor copy
 
@@ -101,6 +111,39 @@ Behavior:
 This keeps prompt cost flat unless Flow has a strong reason to recover or unroll context.
 Use `f codex doctor` to confirm whether wrapper transport, runtime skills, and context budgets are actually active for the current repo.
 
+### Codex connect and find
+
+`f codex connect` and `f ai codex find` now use a Flow-managed local session-search index before
+falling back to direct SQLite/transcript scans. The index is repo-scoped at query time, rebuilt
+from the Codex state DB when needed, and keeps transcript snippets for better recall on natural
+language queries.
+
+By default, search now prefers sessions from roughly the last 7 days for faster and more accurate
+ranking on active work, then automatically widens back to the full session history when the recent
+window looks weak or sparse.
+
+Useful commands:
+
+```bash
+f codex connect --path ~/repos/openai/codex --exact-cwd "app-server"
+f codex connect --path ~/repos/openai/codex --exact-cwd --json "thread/read"
+f codex connect --all-history --path ~/repos/openai/codex "old migration plan"
+f ai codex find --path ~/repos/openai/codex "where does codex store"
+f ai codex find --recent-days 30 --path ~/repos/openai/codex "thread/read"
+f ai codex find --json --limit 5 --path ~/repos/openai/codex "where does codex store"
+```
+
+Behavior:
+
+- `connect` stays the interactive handoff path and returns the exact session match
+- `connect --json` prints the selected session instead of attaching
+- `find` still resumes the top hit
+- `find --json` is read-only and prints ranked candidates for inspection/eval work
+- by default both commands prefer the last 7 days first, then widen if the recent window is weak
+- use `--recent-days <N>` to widen the preferred recent window without fully disabling recency bias
+- use `--all-history` to search the full history immediately
+- if confidence is weak or the index misses, Flow still falls back to the older metadata and transcript paths instead of silently opening an arbitrary session
+
 ### Codex sessions after a crash or restart
 
 If your Mac restarts and you lose the live Codex terminals, use:
@@ -234,8 +277,8 @@ cat <<'EOF' | f codex runtime write-plan --title "Example Plan"
 EOF
 ```
 
-By default this writes to today's `~/plan/<day-of-month>/` bucket, for example
-`~/plan/23/` on the 23rd day of the month.
+By default this writes to today's `~/docs/plan/<day-of-month>/` bucket, for
+example `~/docs/plan/23/` on the 23rd day of the month.
 
 ### Run-owned agent bridge