fix(fn-20): address 4 iter-2 adversarial review findings

1. [REQUIRED] TCP daemon port discovery (server.rs) —
   serve_tcp now writes the bound port to .flow/.state/flowctl.port
   on startup and removes it on shutdown. CLI approval clients can
   now find the TCP endpoint instead of silently falling back to
   direct DB writes. Uses listener.local_addr() so port=0 ephemeral
   binds also publish their real port.

2. [IMPORTANT] Browser approvals drop resolver (handlers/approvals.rs) —
   daemon approve/reject handlers now default resolver to "dashboard"
   when the client omits it, so every browser-driven resolution has a
   non-null audit trail entry. CLI callers passing --resolver still win.

3. [IMPORTANT] epic audit receipts bypass archive (epic.rs) —
   added review_belongs_to_epic() helper matching both the legacy
   "-{id}." infix pattern and the new "epic-audit-{id}-*" prefix.
   Both archive and clean paths now use it, so audit receipts are
   moved with the rest of the epic's review artifacts.

4. [NICE-TO-HAVE] orphan approvals (approvals.rs) —
   ApprovalStore::create() now validates the referenced task_id
   exists before inserting. Typos return ValidationError instead of
   creating ghost records that show up in the UI with no real work
   to reconcile to. Added create_rejects_nonexistent_task test +
   updated in-mem/server tests to seed epic+task rows.

Tests: 285 passed, 0 failed. Clippy clean.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

flowctl/crates/flowctl-cli/src/commands/epic.rs

@@ -965,7 +965,7 @@ fn cmd_archive(id: &str, force: bool, json_mode: bool) {
             for entry in review_entries {
                 let name = entry.file_name();
                 let name_str = name.to_string_lossy();
-                if name_str.contains(&format!("-{id}.")) {
+                if review_belongs_to_epic(&name_str, id) {
                     let dest = archive_dir.join(&*name);
                     let _ = fs::rename(entry.path(), &dest);
                     moved.push(format!("reviews/{name_str}"));
@@ -1081,7 +1081,8 @@ fn cmd_archive_silent(id: &str, flow_dir: &Path) {
         if let Ok(entries) = fs::read_dir(&reviews_dir) {
             for entry in entries.flatten() {
                 let name = entry.file_name();
-                if name.to_string_lossy().contains(&format!("-{id}.")) {
+                let name_str = name.to_string_lossy();
+                if review_belongs_to_epic(&name_str, id) {
                     let _ = fs::rename(entry.path(), archive_dir.join(&name));
                 }
             }
@@ -1288,6 +1289,19 @@ fn cmd_set_auto_execute(id: &str, pending: bool, done: bool, json_mode: bool) {
     }
 }
 
+// ── Shared helpers ─────────────────────────────────────────────────
+
+/// Returns true if a review filename belongs to the given epic.
+///
+/// Matches both naming schemes used in `.flow/reviews/`:
+/// - Task-suffixed reviews (plan/impl/cross-model): `*-{epic_id}.<task-num>-*.json`
+///   matched via the `-{id}.` infix
+/// - Epic-level audit receipts: `epic-audit-{id}-<timestamp>.json`
+///   matched via the `-{id}-` prefix
+fn review_belongs_to_epic(name: &str, id: &str) -> bool {
+    name.contains(&format!("-{id}.")) || name.starts_with(&format!("epic-audit-{id}-"))
+}
+
 // ── Audit command ───────────────────────────────────────────────────
 
 /// Find the most recent `epic-audit-<id>-*.json` receipt in `.flow/reviews/`.

flowctl/crates/flowctl-daemon/src/handlers/approvals.rs

@@ -79,9 +79,13 @@ pub async fn approve_approval_handler(
     Json(body): Json<Option<ResolveRequest>>,
 ) -> Result<Json<serde_json::Value>, AppError> {
     let body = body.unwrap_or_default();
+    // Browser clients typically don't send a resolver; fall back to
+    // "dashboard" so the audit trail still records *something* rather
+    // than a null. CLI callers should pass --resolver explicitly.
+    let resolver = body.resolver.or_else(|| Some("dashboard".to_string()));
     let store = LibSqlApprovalStore::new(state.db.clone());
     let resolved = store
-        .approve(&id, body.resolver)
+        .approve(&id, resolver)
         .await
         .map_err(service_error_to_app_error)?;
 
@@ -102,9 +106,11 @@ pub async fn reject_approval_handler(
     Json(body): Json<Option<ResolveRequest>>,
 ) -> Result<Json<serde_json::Value>, AppError> {
     let body = body.unwrap_or_default();
+    // Browser fallback (see approve_approval_handler for rationale).
+    let resolver = body.resolver.or_else(|| Some("dashboard".to_string()));
     let store = LibSqlApprovalStore::new(state.db.clone());
     let resolved = store
-        .reject(&id, body.resolver, body.reason)
+        .reject(&id, resolver, body.reason)
         .await
         .map_err(service_error_to_app_error)?;
 

flowctl/crates/flowctl-daemon/src/server.rs

@@ -157,20 +157,41 @@ pub async fn serve_tcp(
         .await
         .with_context(|| format!("failed to bind TCP: {addr}"))?;
 
-    info!("daemon API listening on http://{addr}");
+    // Resolve the bound port (honors port=0 ephemeral binds) and persist it
+    // to .flow/.state/flowctl.port so CLI clients can discover the TCP
+    // transport. Without this, `flowctl approval` CLIs silently fall back
+    // to direct DB writes and bypass the daemon event bus.
+    let bound_port = listener
+        .local_addr()
+        .map(|a| a.port())
+        .unwrap_or(port);
+    let port_file = runtime.paths.state_dir.join("flowctl.port");
+    if let Err(e) = std::fs::write(&port_file, bound_port.to_string()) {
+        tracing::warn!(
+            "failed to write port file {}: {} — CLI clients may bypass daemon",
+            port_file.display(),
+            e
+        );
+    }
+
+    info!("daemon API listening on http://127.0.0.1:{bound_port}");
 
     let (state, cancel) = create_state(runtime, event_bus).await?;
 
     let router = build_router(state);
 
-    axum::serve(listener, router)
+    let serve_result = axum::serve(listener, router)
         .with_graceful_shutdown(async move {
             cancel.cancelled().await;
             info!("HTTP server shutting down");
         })
         .await
-        .context("HTTP server error")?;
+        .context("HTTP server error");
+
+    // Best-effort cleanup of the port file on shutdown.
+    let _ = std::fs::remove_file(&port_file);
 
+    serve_result?;
     Ok(())
 }
 
@@ -445,6 +466,17 @@ mod tests {
         let (_tmp, runtime, event_bus) = test_setup();
         let mut event_rx = event_bus.subscribe();
         let (state, _cancel) = create_state(runtime, event_bus).await.unwrap();
+
+        // Seed epic+task so approval create() existence check passes.
+        state.db.execute(
+            "INSERT INTO epics (id, title, status, file_path, created_at, updated_at) VALUES ('fn-1', 'Test', 'open', 'epics/fn-1.md', '2025-01-01T00:00:00Z', '2025-01-01T00:00:00Z')",
+            (),
+        ).await.unwrap();
+        state.db.execute(
+            "INSERT INTO tasks (id, epic_id, title, status, file_path, created_at, updated_at) VALUES ('fn-1.1', 'fn-1', 'Test Task', 'todo', 'tasks/fn-1.1.md', '2025-01-01T00:00:00Z', '2025-01-01T00:00:00Z')",
+            (),
+        ).await.unwrap();
+
         let app = build_router(state);
 
         // Create
@@ -536,6 +568,17 @@ mod tests {
     async fn approval_reject_records_reason() {
         let (_tmp, runtime, event_bus) = test_setup();
         let (state, _cancel) = create_state(runtime, event_bus).await.unwrap();
+
+        // Seed epic+task so approval create() existence check passes.
+        state.db.execute(
+            "INSERT INTO epics (id, title, status, file_path, created_at, updated_at) VALUES ('fn-2', 'Test', 'open', 'epics/fn-2.md', '2025-01-01T00:00:00Z', '2025-01-01T00:00:00Z')",
+            (),
+        ).await.unwrap();
+        state.db.execute(
+            "INSERT INTO tasks (id, epic_id, title, status, file_path, created_at, updated_at) VALUES ('fn-2.1', 'fn-2', 'Test Task', 'todo', 'tasks/fn-2.1.md', '2025-01-01T00:00:00Z', '2025-01-01T00:00:00Z')",
+            (),
+        ).await.unwrap();
+
         let app = build_router(state);
 
         let req = axum::http::Request::builder()

flowctl/crates/flowctl-service/src/approvals.rs

@@ -123,6 +123,35 @@ fn row_to_approval(row: libsql::Row) -> ServiceResult<Approval> {
 #[async_trait::async_trait]
 impl ApprovalStore for LibSqlApprovalStore {
     async fn create(&self, req: CreateApprovalRequest) -> ServiceResult<Approval> {
+        // Reject orphan approvals: the referenced task must exist. Without
+        // this check a typo creates a ghost pending record with no way to
+        // reconcile it to real work.
+        let exists: i64 = {
+            let mut rows = self
+                .conn
+                .query(
+                    "SELECT COUNT(*) FROM tasks WHERE id = ?1",
+                    params![req.task_id.clone()],
+                )
+                .await
+                .map_err(|e| ServiceError::ValidationError(format!("task lookup: {e}")))?;
+            let row = rows
+                .next()
+                .await
+                .map_err(|e| ServiceError::ValidationError(format!("task lookup row: {e}")))?
+                .ok_or_else(|| {
+                    ServiceError::ValidationError("task lookup returned no rows".into())
+                })?;
+            row.get(0)
+                .map_err(|e| ServiceError::ValidationError(format!("task lookup value: {e}")))?
+        };
+        if exists == 0 {
+            return Err(ServiceError::ValidationError(format!(
+                "task {} does not exist",
+                req.task_id
+            )));
+        }
+
         let id = Self::new_id();
         let now = Utc::now().timestamp();
         let payload_str = serde_json::to_string(&req.payload)
@@ -248,11 +277,46 @@ mod tests {
 
     async fn in_mem_store() -> LibSqlApprovalStore {
         let (db, conn) = flowctl_db::open_memory_async().await.unwrap();
+        // Seed tasks referenced by the tests so the existence check passes.
+        let now = "2026-01-01T00:00:00Z";
+        for tid in &["fn-1.1", "fn-1.2"] {
+            let (epic_id, _num) = tid.split_once('.').unwrap();
+            conn.execute(
+                "INSERT OR IGNORE INTO epics
+                    (id, title, status, file_path, created_at, updated_at, body)
+                 VALUES (?1, ?1, 'open', ?1, ?2, ?2, '')",
+                params![epic_id.to_string(), now.to_string()],
+            )
+            .await
+            .expect("seed epic");
+            conn.execute(
+                "INSERT OR IGNORE INTO tasks
+                    (id, epic_id, title, status, file_path, created_at, updated_at, body)
+                 VALUES (?1, ?2, ?1, 'todo', ?1, ?3, ?3, '')",
+                params![tid.to_string(), epic_id.to_string(), now.to_string()],
+            )
+            .await
+            .expect("seed task");
+        }
         // Leak the db so conn stays valid for the test lifetime.
         Box::leak(Box::new(db));
         LibSqlApprovalStore::new(conn)
     }
 
+    #[tokio::test]
+    async fn create_rejects_nonexistent_task() {
+        let store = in_mem_store().await;
+        let err = store
+            .create(CreateApprovalRequest {
+                task_id: "fn-999.99".into(),
+                kind: ApprovalKind::FileAccess,
+                payload: serde_json::json!({}),
+            })
+            .await
+            .expect_err("should reject nonexistent task");
+        assert!(matches!(err, ServiceError::ValidationError(_)));
+    }
+
     #[tokio::test]
     async fn create_and_get() {
         let store = in_mem_store().await;