One canonical fiber id (realpath → enclosing .felt → slug) across /fibers and /state

The /fibers list and /state runtime keys disagreed on a fiber's id whenever
the file was reached through a symlinked store. /fibers (FiberDocuments) emitted
felt's *traversal* id — loom walking through `loom/.felt/shapepipe → project/.felt`
yields `shapepipe/review-ngmix-v2-pr740` — while the runtime keyed the same fiber
by the project-relative slug `review-ngmix-v2-pr740` (realpath against the project
.felt). The kanban joins card→runtime by id, so a *running* worker went unmatched:
the card sat in Drafts and any drag to In-flight snapped back.

Unify on one rule, everywhere an id is assigned:

    canonical id = realpath(fiber file) → enclosing .felt → store-relative slug

Because realpath resolves every symlink, the resolved path holds exactly one
.felt segment — the store where the file physically lives — so the rule is
host-invariant for git-synced stores (loom) and store-prefix-free for project-
resident fibers, with no per-store identity. The Elixir mirror of Portolan's
canonicalStoreRelativeId.

- New Shuttle.FiberId owns the rule (ref_from_path/1, canonical_id/1,
  canonical_host_path/1, resolve_realpath/1). The poller's three private copies
  (fiber_ref_from_path, fiber_id_from_tail, resolve_realpath, canonical_host_path)
  collapse into it (-110 lines).
- FiberDocuments canonicalizes each entry's `id` from the realpath of its md
  file; `felt_store` + `path` stay store-relative so remote clients still open
  the file by path. /fibers ids now equal /state runtime keys.
- Fix a latent realpath bug surfaced by the new tests: the "never revisit a
  symlink" loop guard mis-flagged benign re-traversal of a shared prefix symlink
  (macOS `/tmp → /private/tmp`) as a loop. Replaced with OS-style hop-counting.
- Fix FiberDocuments folding felt's stderr into stdout: a stray non-fiber .md
  (SPEC.md) made `felt ls` warn on stderr, corrupting the JSON and 500ing the
  whole /fibers endpoint. Parse stdout only.

project_dir reverts to being only the worker's cwd; it never participates in id
derivation. Tests pin the rule across loom-resident, project-resident-via-symlink,
and portolan (symlink-into-loom-subpath) topologies. mix test green (241).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: cailmdaley

lib/shuttle/fiber_documents.ex

@@ -46,7 +46,13 @@ defmodule Shuttle.FiberDocuments do
     args = ["ls", "-s", "all", "-j"]
     args = if with_body?, do: args ++ ["--body"], else: args
 
-    case System.cmd("felt", args, cd: store, stderr_to_stdout: true) do
+    # Do NOT fold stderr into stdout: felt prints `warning: failed to parse …`
+    # for stray non-fiber `.md` files (SPEC.md, README.md) to stderr while still
+    # emitting valid JSON on stdout and exiting 0. Capturing stderr would prepend
+    # those warnings to the JSON and break Jason.decode for the whole store —
+    # 500ing the entire /fibers endpoint. Felt's warnings land in the daemon log
+    # instead; only stdout is parsed.
+    case System.cmd("felt", args, cd: store) do
       {output, 0} ->
         decode_store(store, output)
 
@@ -65,13 +71,21 @@ defmodule Shuttle.FiberDocuments do
   end
 
   defp entry_for(store, %{"id" => id} = fiber) when is_binary(id) and id != "" do
+    # `path` (and thus the physical file location) is derived from felt's
+    # traversal id *before* we overwrite `id` — it stays store-relative so
+    # remote clients open the file via `felt_store` + `path`. The card's logical
+    # `id`, by contrast, is canonicalized: realpath → enclosing .felt → slug,
+    # the one rule shared with /state runtime keying. For a fiber physically
+    # rooted in this store the two coincide; for a symlink-traversed fiber (loom
+    # walking through `loom/.felt/shapepipe → project/.felt`) the canonical id
+    # drops the store prefix to match the project-relative runtime key.
     path = relative_felt_path(fiber)
     full_path = Path.join([store, ".felt", path])
 
     entry = %{
       felt_store: store,
       path: path,
-      fiber: fiber
+      fiber: Map.put(fiber, "id", canonical_id(full_path, id))
     }
 
     report_path = full_path |> Path.dirname() |> Path.join("report.html")
@@ -85,6 +99,13 @@ defmodule Shuttle.FiberDocuments do
 
   defp entry_for(_store, _fiber), do: []
 
+  defp canonical_id(full_path, fallback) do
+    case Shuttle.FiberId.canonical_id(full_path) do
+      {:ok, id} -> id
+      {:error, _} -> fallback
+    end
+  end
+
   defp relative_felt_path(%{"id" => id, "entry_point" => true}) do
     "#{Path.basename(id)}.md"
   end

lib/shuttle/fiber_id.ex

@@ -0,0 +1,188 @@
+defmodule Shuttle.FiberId do
+  @moduledoc """
+  The one canonical fiber-id rule, used everywhere Shuttle assigns an id.
+
+      canonical id = realpath(fiber file) → enclosing .felt → store-relative slug
+
+  Because `realpath` resolves every symlink, the resulting absolute path
+  contains exactly one `.felt` segment — the store where the file is
+  *physically* rooted. The slug below it is the id `felt ls` reports when run
+  from inside that store. The same string therefore names the fiber on every
+  daemon surface (`/api/v1/fibers` cards, `/api/v1/state` runtime keys,
+  tmux/lifecycle keying), and is host-invariant for git-synced stores like
+  loom — so cross-host dedup falls out for free, with no per-store identity.
+
+  This is the Elixir mirror of Portolan's `canonicalStoreRelativeId`
+  (`server/src/canonicalFiberRef.ts`); the two implementations must agree.
+
+  ## Symlink topologies it resolves uniformly
+
+    * **Loom-resident** (`loom/.felt/ai-futures/portolan/X`) → `ai-futures/portolan/X`.
+      A project whose `.felt` symlinks *into* a loom subpath (portolan shape:
+      `project/.felt → loom/.felt/ai-futures/portolan`) resolves to the same
+      loom-relative slug, because realpath collapses the symlink onto loom.
+    * **Project-resident** (shapepipe shape: `loom/.felt/shapepipe → project/.felt`)
+      → the project-relative slug `X`, because realpath collapses the loom
+      symlink onto the project's own `.felt`, which is the physically-enclosing
+      store.
+
+  In both cases the id is keyed against the store where the file physically
+  lives; `project_dir` never participates — it is only the worker's cwd.
+  """
+
+  @typedoc "Canonical `(host, id)` for a fiber file: the directory holding the owning `.felt/`, and the store-relative slug."
+  @type ref :: %{host: String.t(), id: String.t()}
+
+  @doc """
+  Canonical `(host, id)` for an on-disk fiber path.
+
+  `host` is the directory that physically contains the owning `.felt/`; `id`
+  is the store-relative slug. Returns `{:error, reason}` when the resolved path
+  sits under no `.felt/` directory (`:no_felt_store`) or isn't a fiber-container
+  `.md` file (`:not_markdown`, `:unexpected_layout`, `:empty_tail`).
+  """
+  @spec ref_from_path(String.t()) :: {:ok, ref()} | {:error, term()}
+  def ref_from_path(path) do
+    resolved =
+      case resolve_realpath(path) do
+        {:ok, real} -> real
+        {:error, _} -> Path.expand(path)
+      end
+
+    segments = Path.split(resolved)
+
+    case felt_index(segments) do
+      nil ->
+        {:error, :no_felt_store}
+
+      felt_idx ->
+        tail = Enum.drop(segments, felt_idx + 1)
+
+        with {:ok, fiber_id} <- id_from_tail(tail) do
+          host =
+            case Enum.take(segments, felt_idx) do
+              [] -> "/"
+              parts -> Path.join(parts)
+            end
+
+          {:ok, %{host: host, id: fiber_id}}
+        end
+    end
+  end
+
+  @doc """
+  Canonical store-relative id for an on-disk fiber path — the `id` of
+  `ref_from_path/1` without the host. Returns `{:error, reason}` on the same
+  conditions.
+  """
+  @spec canonical_id(String.t()) :: {:ok, String.t()} | {:error, term()}
+  def canonical_id(path) do
+    with {:ok, %{id: id}} <- ref_from_path(path), do: {:ok, id}
+  end
+
+  @doc """
+  Realpath of a felt store root (resolves symlinks; falls back to `Path.expand/1`).
+  Used to compare a candidate fiber's owning host against a configured store.
+  """
+  @spec canonical_host_path(String.t()) :: String.t()
+  def canonical_host_path(host) do
+    case resolve_realpath(host) do
+      {:ok, resolved} -> resolved
+      {:error, _} -> Path.expand(host)
+    end
+  end
+
+  # POSIX SYMLOOP_MAX is 8; Linux allows 40. We cap symlink *hops* rather than
+  # forbidding revisits, because a non-cyclic resolution legitimately re-traverses
+  # a shared prefix symlink (e.g. macOS `/tmp → /private/tmp`) on more than one
+  # pass — a "never revisit" guard mis-flags that as a loop. A genuine A→B→A
+  # cycle still blows past the cap.
+  @max_symlink_hops 40
+
+  @doc """
+  Pure-Elixir `realpath`: resolves every symlink along an expanded path,
+  segment by segment, capping total symlink hops to guard against cyclic links.
+  Returns the fully resolved absolute path.
+  """
+  @spec resolve_realpath(String.t()) :: {:ok, String.t()} | {:error, term()}
+  def resolve_realpath(path) do
+    expanded = Path.expand(path)
+
+    case Path.split(expanded) do
+      ["/" | rest] -> resolve_realpath_segments("/", rest, 0)
+      [first | rest] -> resolve_realpath_segments(first, rest, 0)
+      [] -> {:error, :empty_path}
+    end
+  end
+
+  # The enclosing `.felt` segment. After realpath there is exactly one, so the
+  # last-occurrence scan is unambiguous; it mirrors Portolan's `lastIndexOf`.
+  defp felt_index(segments) do
+    segments
+    |> Enum.with_index()
+    |> Enum.reduce(nil, fn
+      {".felt", idx}, _acc -> idx
+      _, acc -> acc
+    end)
+  end
+
+  defp id_from_tail([]), do: {:error, :empty_tail}
+
+  defp id_from_tail([file]) do
+    if String.ends_with?(file, ".md") do
+      {:ok, String.replace_suffix(file, ".md", "")}
+    else
+      {:error, :not_markdown}
+    end
+  end
+
+  defp id_from_tail(tail) do
+    file = List.last(tail)
+    parent = Enum.at(tail, -2)
+
+    cond do
+      not String.ends_with?(file, ".md") ->
+        {:error, :not_markdown}
+
+      String.replace_suffix(file, ".md", "") != parent ->
+        {:error, :unexpected_layout}
+
+      true ->
+        {:ok, tail |> Enum.take(length(tail) - 1) |> Path.join()}
+    end
+  end
+
+  defp resolve_realpath_segments(current, [], _hops), do: {:ok, current}
+
+  defp resolve_realpath_segments(_current, _segments, hops) when hops > @max_symlink_hops,
+    do: {:error, :symlink_loop}
+
+  defp resolve_realpath_segments(current, [segment | rest], hops) do
+    candidate = Path.join(current, segment)
+
+    case :file.read_link(String.to_charlist(candidate)) do
+      {:ok, target} ->
+        target_path = List.to_string(target)
+
+        expanded_target =
+          case Path.type(target_path) do
+            :absolute -> Path.expand(target_path)
+            _ -> Path.expand(target_path, Path.dirname(candidate))
+          end
+
+        case Path.split(expanded_target) do
+          ["/" | target_rest] ->
+            resolve_realpath_segments("/", target_rest ++ rest, hops + 1)
+
+          [first | target_rest] ->
+            resolve_realpath_segments(first, target_rest ++ rest, hops + 1)
+
+          [] ->
+            {:error, :empty_target}
+        end
+
+      {:error, _} ->
+        resolve_realpath_segments(candidate, rest, hops)
+    end
+  end
+end