{file.path}}
+ left={
+
+ {file.path}
+
+
+ }
right={
{
expect(upsertOpenFileTab(tabs, file)).toBe(tabs);
});
+ it.each([
+ [{ previous: "target.txt", next: undefined }, "symlink to regular file"],
+ [{ previous: undefined, next: "target.txt" }, "regular file to symlink"],
+ ] as const)("refreshes resolvedPath for an existing clean tab (%s)", (paths, _label) => {
+ const existing = { ...file, resolvedPath: paths.previous };
+ const refreshed = { ...file, resolvedPath: paths.next, content: "fresh content" };
+
+ expect(upsertOpenFileTab([existing], refreshed)).toEqual([refreshed]);
+ });
+
+ it("refreshes resolvedPath without clobbering a dirty tab", () => {
+ const existing = {
+ ...file,
+ content: "local edits",
+ isDirty: true,
+ resolvedPath: "old-target.txt",
+ };
+ const refreshed = { ...file, content: "disk content", resolvedPath: "new-target.txt" };
+
+ expect(upsertOpenFileTab([existing], refreshed)).toEqual([
+ { ...existing, resolvedPath: "new-target.txt" },
+ ]);
+ });
+
it("adds a new tab", () => {
expect(upsertOpenFileTab([], file)).toEqual([file]);
});
diff --git a/apps/web/components/task/task-center-panel-file-tabs.ts b/apps/web/components/task/task-center-panel-file-tabs.ts
index 1c46e37885..20331dadbd 100644
--- a/apps/web/components/task/task-center-panel-file-tabs.ts
+++ b/apps/web/components/task/task-center-panel-file-tabs.ts
@@ -4,14 +4,43 @@ export function getFileTabKey(file: Pick): string
return `${file.repo ?? ""}\u0000${file.path}`;
}
+const openFileTabKeys: (keyof OpenFileTab)[] = [
+ "resolvedPath",
+ "path",
+ "name",
+ "repo",
+ "content",
+ "originalContent",
+ "originalHash",
+ "isDirty",
+ "isBinary",
+ "renderedPreview",
+];
+
+function areOpenFileTabsEqual(left: OpenFileTab, right: OpenFileTab): boolean {
+ return openFileTabKeys.every((key) => Object.is(left[key], right[key]));
+}
+
export function upsertOpenFileTab(prev: OpenFileTab[], fileTab: OpenFileTab): OpenFileTab[] {
const fileKey = getFileTabKey(fileTab);
const existingIndex = prev.findIndex((tab) => getFileTabKey(tab) === fileKey);
if (existingIndex >= 0) {
- if (fileTab.renderedPreview === undefined) return prev;
- return prev.map((tab, index) =>
- index === existingIndex ? { ...tab, renderedPreview: fileTab.renderedPreview } : tab,
- );
+ const existing = prev[existingIndex];
+ const refreshed = existing.isDirty
+ ? {
+ ...existing,
+ resolvedPath: fileTab.resolvedPath,
+ ...(fileTab.renderedPreview !== undefined
+ ? { renderedPreview: fileTab.renderedPreview }
+ : {}),
+ }
+ : {
+ ...existing,
+ ...fileTab,
+ renderedPreview: fileTab.renderedPreview ?? existing.renderedPreview,
+ };
+ if (areOpenFileTabsEqual(existing, refreshed)) return prev;
+ return prev.map((tab, index) => (index === existingIndex ? refreshed : tab));
}
const maxTabs = 4;
return prev.length >= maxTabs ? [...prev.slice(1), fileTab] : [...prev, fileTab];
diff --git a/apps/web/components/task/task-center-panel-restoration.test.ts b/apps/web/components/task/task-center-panel-restoration.test.ts
index 82117a8640..2af0fb7e7c 100644
--- a/apps/web/components/task/task-center-panel-restoration.test.ts
+++ b/apps/web/components/task/task-center-panel-restoration.test.ts
@@ -139,6 +139,7 @@ describe("task center file restoration", () => {
path: "README.md",
content: "# README",
is_binary: false,
+ resolved_path: "docs/README.md",
});
const tabs = await loadSavedFileTabs("session", [
@@ -151,6 +152,7 @@ describe("task center file restoration", () => {
content: "# README",
originalContent: "# README",
originalHash: "hash:8",
+ resolvedPath: "docs/README.md",
isDirty: false,
isBinary: false,
renderedPreview: true,
diff --git a/apps/web/components/task/task-center-panel-restoration.ts b/apps/web/components/task/task-center-panel-restoration.ts
index 989f7e2b07..b67b760adc 100644
--- a/apps/web/components/task/task-center-panel-restoration.ts
+++ b/apps/web/components/task/task-center-panel-restoration.ts
@@ -52,6 +52,7 @@ export async function loadSavedFileTabs(sessionId: string, savedTabs: StoredFile
originalHash: hash,
isDirty: false,
isBinary: response.is_binary,
+ resolvedPath: response.resolved_path,
repo: savedTab.repo,
renderedPreview:
getFilePreviewKind(savedTab.path, response.is_binary) === "markdown"
diff --git a/apps/web/e2e/tests/git/mobile-symlink-identification.spec.ts b/apps/web/e2e/tests/git/mobile-symlink-identification.spec.ts
new file mode 100644
index 0000000000..8da18d1b8b
--- /dev/null
+++ b/apps/web/e2e/tests/git/mobile-symlink-identification.spec.ts
@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+import { test, expect } from "../../fixtures/test-base";
+import { SessionPage } from "../../pages/session-page";
+
+// @covers AC-WORKSPACES-SYMLINK-001.1, AC-WORKSPACES-SYMLINK-001.2, AC-WORKSPACES-SYMLINK-001.4
+test("identifies a symlink in Changes and the mobile file viewer", async ({
+ testPage,
+ apiClient,
+ seedData,
+ backend,
+}) => {
+ const repo = path.join(backend.tmpDir, "repos", "e2e-repo");
+ const name = "a-long-symbolic-link-filename-for-mobile-containment.txt";
+ fs.writeFileSync(path.join(repo, "symlink-target.txt"), "target content\n");
+ fs.symlinkSync("symlink-target.txt", path.join(repo, name));
+ const task = await apiClient.createTaskWithAgent(
+ seedData.workspaceId,
+ "Mobile symlink identity",
+ seedData.agentProfileId,
+ {
+ description: "/e2e:simple-message",
+ workflow_id: seedData.workflowId,
+ workflow_step_id: seedData.startStepId,
+ repository_ids: [seedData.repositoryId],
+ },
+ );
+ await testPage.goto(`/t/${task.id}`);
+ const session = new SessionPage(testPage);
+ await session.waitForLoad();
+ await session.waitForChatIdle();
+ await testPage.getByRole("button", { name: /Changes/ }).tap();
+ const row = testPage.getByTestId(`file-row-${name}`);
+ await expect(row).toBeVisible({ timeout: 20_000 });
+ await expect(row.getByTestId("symlink-indicator")).toBeVisible();
+ const edit = row.getByRole("button", { name: "Edit", exact: true });
+ expect((await edit.boundingBox())!.height).toBeGreaterThanOrEqual(44);
+ const rowBounds = (await row.boundingBox())!;
+ const markerBounds = (await row.getByTestId("symlink-indicator").boundingBox())!;
+ const editBounds = (await edit.boundingBox())!;
+ expect(markerBounds.x).toBeGreaterThanOrEqual(rowBounds.x);
+ expect(markerBounds.x + markerBounds.width).toBeLessThanOrEqual(editBounds.x);
+ await edit.tap();
+ const viewer = testPage.getByTestId("mobile-file-viewer-panel");
+ await expect(viewer).toBeVisible();
+ await expect(viewer.getByTestId("symlink-indicator")).toHaveText("Symlink");
+ expect(
+ await testPage.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth),
+ ).toBe(true);
+ await viewer.getByRole("button", { name: "Close", exact: true }).tap();
+ await testPage.getByRole("button", { name: "Files", exact: true }).tap();
+ await expect(session.fileTreeNode(name).getByTestId("symlink-indicator")).toBeVisible();
+ await expect(
+ session.fileTreeNode("symlink-target.txt").getByTestId("symlink-indicator"),
+ ).toHaveCount(0);
+ await session.fileTreeNode("symlink-target.txt").tap();
+ await expect(viewer).toBeVisible();
+ await expect(viewer.getByTestId("symlink-indicator")).toHaveCount(0);
+});
diff --git a/apps/web/e2e/tests/git/symlink-file.spec.ts b/apps/web/e2e/tests/git/symlink-file.spec.ts
index a97f9ddd55..1898b92630 100644
--- a/apps/web/e2e/tests/git/symlink-file.spec.ts
+++ b/apps/web/e2e/tests/git/symlink-file.spec.ts
@@ -102,6 +102,8 @@ test.describe("Symlink file handling", () => {
const linkDirRow = session.files.getByText("link-dir");
await expect(linkDirRow).toBeVisible({ timeout: 10_000 });
+ await expect(session.fileTreeNode("link-dir").getByTestId("symlink-indicator")).toBeVisible();
+
// Click to expand — if the fix is missing, this is classified as a file
// and would try to open it in the editor instead of expanding.
await linkDirRow.click();
@@ -111,42 +113,102 @@ test.describe("Symlink file handling", () => {
await expect(childFile).toBeVisible({ timeout: 10_000 });
});
- test("clicking a symlink to a file opens the file editor", async ({
- testPage,
- apiClient,
- seedData,
- backend,
- }) => {
- const repoDir = path.join(backend.tmpDir, "repos", "e2e-repo");
-
- fs.writeFileSync(path.join(repoDir, "real-file.txt"), "Hello from symlink target!\n");
- fs.symlinkSync("real-file.txt", path.join(repoDir, "link-file.txt"));
-
- const { session } = await seedSimpleTask(
+ for (const provider of ["monaco", "codemirror"] as const) {
+ test(`clicking a symlink identifies it in the ${provider} editor`, async ({
testPage,
apiClient,
seedData,
- "Symlink File Tree Test",
- );
+ backend,
+ }) => {
+ const initial = await apiClient.getUserSettings();
+ const initialLayout = initial.settings.changes_panel_layout === "tree" ? "tree" : "flat";
+ await apiClient.rawRequest("PATCH", "/api/v1/user/settings", {
+ changes_panel_layout: provider === "monaco" ? "flat" : "tree",
+ });
+ try {
+ await testPage.addInitScript((provider) => {
+ localStorage.setItem(
+ "kandev-editor-providers",
+ JSON.stringify({
+ version: 3,
+ state: {
+ providers: {
+ "code-editor": provider,
+ "diff-viewer": "pierre-diffs",
+ "chat-code-block": "shiki",
+ "chat-diff": "pierre-diffs",
+ "plan-editor": "tiptap",
+ },
+ },
+ }),
+ );
+ }, provider);
+ const repoDir = path.join(backend.tmpDir, "repos", "e2e-repo");
+ fs.rmSync(path.join(repoDir, "link-file.txt"), { force: true });
+ fs.writeFileSync(path.join(repoDir, "real-file.txt"), "Hello from symlink target!\n");
+ fs.symlinkSync("real-file.txt", path.join(repoDir, "link-file.txt"));
- // Open Files tab and click the symlink
- await session.clickTab("Files");
- await expect(session.files).toBeVisible({ timeout: 5_000 });
+ const { session } = await seedSimpleTask(
+ testPage,
+ apiClient,
+ seedData,
+ "Symlink File Tree Test",
+ );
- const fileRow = session.files.getByText("link-file.txt");
- await expect(fileRow).toBeVisible({ timeout: 10_000 });
- await fileRow.click();
+ await session.clickTab("Changes");
+ const changedLink = testPage.getByTestId("file-row-link-file.txt");
+ await expect(changedLink).toBeVisible({ timeout: 15_000 });
+ await expect(changedLink.getByTestId("symlink-indicator")).toBeVisible();
+ await changedLink.hover();
+ await expect(changedLink.getByTestId("symlink-indicator")).toBeVisible();
+ await expect(
+ testPage.getByTestId("file-row-real-file.txt").getByTestId("symlink-indicator"),
+ ).toHaveCount(0);
- // Assert editor tab opens for the symlink
- const editorTab = testPage.locator(".dv-default-tab:has-text('link-file.txt')");
- await expect(editorTab).toBeVisible({ timeout: 10_000 });
+ // Open Files tab and click the symlink
+ await session.clickTab("Files");
+ await expect(session.files).toBeVisible({ timeout: 5_000 });
- // Assert the file content is visible in the Monaco editor
- const editorContent = testPage.locator(".view-lines");
- await expect(editorContent).toContainText("Hello from symlink target", {
- timeout: 10_000,
+ await expect(
+ session.fileTreeNode("link-file.txt").getByTestId("symlink-indicator"),
+ ).toBeVisible();
+ await expect(
+ session.fileTreeNode("real-file.txt").getByTestId("symlink-indicator"),
+ ).toHaveCount(0);
+ const fileRow = session.files.getByText("link-file.txt");
+ await expect(fileRow).toBeVisible({ timeout: 10_000 });
+ await fileRow.click();
+
+ // Assert editor tab opens for the symlink
+ const editorTab = testPage.locator(".dv-default-tab:has-text('link-file.txt')");
+ await expect(editorTab).toBeVisible({ timeout: 10_000 });
+
+ // Assert the file content is visible in the Monaco editor
+ const editorContent = testPage.locator(
+ provider === "monaco" ? ".view-lines" : ".cm-content",
+ );
+ await expect(editorContent).toContainText("Hello from symlink target", {
+ timeout: 10_000,
+ });
+ await expect(
+ testPage
+ .locator('[data-testid="symlink-indicator"]:not([data-testid="files-panel"] *)')
+ .filter({ visible: true }),
+ ).toContainText("Symlink");
+ await session.files.getByText("real-file.txt", { exact: true }).click();
+ await expect(testPage.locator(".dv-default-tab:has-text('real-file.txt')")).toBeVisible();
+ await expect(
+ testPage
+ .locator('[data-testid="symlink-indicator"]:not([data-testid="files-panel"] *)')
+ .filter({ visible: true }),
+ ).toHaveCount(0);
+ } finally {
+ await apiClient.rawRequest("PATCH", "/api/v1/user/settings", {
+ changes_panel_layout: initialLayout,
+ });
+ }
});
- });
+ }
test("clicking a symlink target diff in the Changes panel opens the diff viewer", async ({
testPage,
diff --git a/apps/web/hooks/domains/session/git-change-facets.test.ts b/apps/web/hooks/domains/session/git-change-facets.test.ts
index 28b8f11269..2f2d80fa3e 100644
--- a/apps/web/hooks/domains/session/git-change-facets.test.ts
+++ b/apps/web/hooks/domains/session/git-change-facets.test.ts
@@ -3,6 +3,19 @@ import type { FileInfo } from "@/lib/state/slices/session-runtime/types";
import { splitFilesByChangeLayer } from "./git-change-facets";
describe("splitFilesByChangeLayer", () => {
+ it("uses independent link metadata for mixed layers", () => {
+ const file = {
+ path: "link",
+ status: "modified" as const,
+ staged: false,
+ is_symlink: false,
+ staged_change: { status: "modified" as const, is_symlink: true },
+ unstaged_change: { status: "modified" as const, is_symlink: false },
+ };
+ const result = splitFilesByChangeLayer([file]);
+ expect(result.stagedFiles[0]).toHaveProperty("is_symlink", true);
+ expect(result.unstagedFiles[0]).toHaveProperty("is_symlink", false);
+ });
it("projects one mixed raw file into staged and unstaged views", () => {
const mixed = {
path: "src/mixed.ts",
diff --git a/apps/web/hooks/domains/session/git-change-facets.ts b/apps/web/hooks/domains/session/git-change-facets.ts
index 867eeaeed5..12053fdec9 100644
--- a/apps/web/hooks/domains/session/git-change-facets.ts
+++ b/apps/web/hooks/domains/session/git-change-facets.ts
@@ -12,6 +12,7 @@ function projectFileChange(
return {
...file,
status: facet.status,
+ is_symlink: facet.is_symlink,
staged: layer === "staged",
additions: facet.additions,
deletions: facet.deletions,
diff --git a/apps/web/hooks/file-editors-sync.test.ts b/apps/web/hooks/file-editors-sync.test.ts
index 6a8d87d33f..dd97052894 100644
--- a/apps/web/hooks/file-editors-sync.test.ts
+++ b/apps/web/hooks/file-editors-sync.test.ts
@@ -109,6 +109,29 @@ describe("buildGitFileSignature", () => {
});
});
+it("clears symlink identity when unchanged content becomes a regular file", async () => {
+ vi.clearAllMocks();
+ const updateFileState = vi.fn();
+ seedOpenFile({
+ content: "v1",
+ originalContent: "v1",
+ originalHash: "h:2:v1",
+ resolvedPath: "target",
+ });
+ mockRequestFileContent.mockResolvedValueOnce({ content: "v1", is_binary: false });
+ await syncOpenFileFromWorkspace({
+ client: FAKE_CLIENT,
+ sessionId: SESSION_ID,
+ fileKey: PATH,
+ path: PATH,
+ updateFileState,
+ });
+ expect(updateFileState).toHaveBeenCalledWith(
+ PATH,
+ expect.objectContaining({ resolvedPath: undefined }),
+ );
+});
+
describe("syncOpenFileFromWorkspace", () => {
let updateFileState: ReturnType<
typeof vi.fn<(path: string, updates: Partial) => void>
@@ -186,7 +209,12 @@ describe("syncOpenFileFromWorkspace", () => {
});
it("is a no-op when remote content matches the editor buffer", async () => {
- seedOpenFile({ content: "v1", originalContent: "v1", originalHash: "h:2:v1" });
+ seedOpenFile({
+ resolvedPath: PATH,
+ content: "v1",
+ originalContent: "v1",
+ originalHash: "h:2:v1",
+ });
mockRequestFileContent.mockResolvedValueOnce({
content: "v1",
is_binary: false,
diff --git a/apps/web/hooks/file-editors-sync.ts b/apps/web/hooks/file-editors-sync.ts
index fb72d2492f..bf345cdb86 100644
--- a/apps/web/hooks/file-editors-sync.ts
+++ b/apps/web/hooks/file-editors-sync.ts
@@ -14,6 +14,7 @@ function buildChangeFacetSignature(facet: FileInfo["staged_change"]): string {
if (!facet) return "";
return [
facet.status,
+ facet.is_symlink ?? "",
facet.additions ?? 0,
facet.deletions ?? 0,
facet.old_path ?? "",
@@ -31,6 +32,7 @@ export function buildGitFileSignature(file: FileInfo | undefined): string {
if (!file) return "__clean__";
return [
file.status ?? "",
+ file.is_symlink ?? "",
file.staged ? "1" : "0",
String(file.additions ?? 0),
String(file.deletions ?? 0),
@@ -82,6 +84,7 @@ export async function syncOpenFileFromWorkspace({
if (latest.isDirty) {
if (response.content === latest.content) {
updateFileState(fileKey, {
+ resolvedPath: response.resolved_path,
originalContent: response.content,
originalHash: remoteHash,
isDirty: false,
@@ -92,8 +95,14 @@ export async function syncOpenFileFromWorkspace({
updatePanelAfterSave(path, latest.name, latest.repo);
return;
}
- if (latest.hasRemoteUpdate && latest.remoteContent === response.content) return;
+ if (
+ latest.hasRemoteUpdate &&
+ latest.remoteContent === response.content &&
+ latest.resolvedPath === response.resolved_path
+ )
+ return;
updateFileState(fileKey, {
+ resolvedPath: response.resolved_path,
hasRemoteUpdate: true,
remoteContent: response.content,
remoteOriginalHash: remoteHash,
@@ -104,12 +113,14 @@ export async function syncOpenFileFromWorkspace({
if (
latest.content === response.content &&
latest.originalHash === remoteHash &&
+ latest.resolvedPath === response.resolved_path &&
!latest.hasRemoteUpdate
) {
return;
}
updateFileState(fileKey, {
+ resolvedPath: response.resolved_path,
content: response.content,
originalContent: response.content,
originalHash: remoteHash,
diff --git a/apps/web/hooks/use-file-editors.build-state.test.ts b/apps/web/hooks/use-file-editors.build-state.test.ts
index 3ff0123de1..69d8af7427 100644
--- a/apps/web/hooks/use-file-editors.build-state.test.ts
+++ b/apps/web/hooks/use-file-editors.build-state.test.ts
@@ -32,6 +32,7 @@ const RESPONSE: FileContentResponse = {
path: PATH,
content: "v1",
is_binary: false,
+ resolved_path: "target.ts",
} as FileContentResponse;
const FAKE_CLIENT = {} as NonNullable<
@@ -53,6 +54,7 @@ describe("buildFileEditorState", () => {
// drop it and the backend stats the bare task root → "file not found".
const state = await buildFileEditorState(PATH, RESPONSE, REPO);
expect(state.repo).toBe(REPO);
+ expect(state.resolvedPath).toBe("target.ts");
});
it("leaves repo undefined for single-repo tasks", async () => {
diff --git a/apps/web/hooks/use-file-editors.ts b/apps/web/hooks/use-file-editors.ts
index c131226fd4..b272f61ee0 100644
--- a/apps/web/hooks/use-file-editors.ts
+++ b/apps/web/hooks/use-file-editors.ts
@@ -211,6 +211,7 @@ async function loadAndRestoreTabs(params: RestoreTabsParams, retryCount = 0): Pr
originalHash: hash,
isDirty: false,
isBinary: response.is_binary,
+ resolvedPath: response.resolved_path,
renderedPreview:
getFilePreviewKind(savedTab.path, response.is_binary) === "markdown"
? savedTab.renderedPreview
diff --git a/apps/web/hooks/use-task-center-file-open.ts b/apps/web/hooks/use-task-center-file-open.ts
index 78202936c5..1d333a54fe 100644
--- a/apps/web/hooks/use-task-center-file-open.ts
+++ b/apps/web/hooks/use-task-center-file-open.ts
@@ -40,6 +40,7 @@ export function useTaskCenterFileOpen({
originalHash: hash,
isDirty: false,
isBinary: response.is_binary,
+ resolvedPath: response.resolved_path,
});
} catch (error) {
toast({
diff --git a/apps/web/lib/state/slices/session-runtime/git-status-state.ts b/apps/web/lib/state/slices/session-runtime/git-status-state.ts
index 52e7adc0e3..a420462d17 100644
--- a/apps/web/lib/state/slices/session-runtime/git-status-state.ts
+++ b/apps/web/lib/state/slices/session-runtime/git-status-state.ts
@@ -28,6 +28,7 @@ function sameStringList(existing: string[] | undefined, incoming: string[] | und
}
const COMPARABLE_FILE_FIELDS = [
+ "is_symlink",
"path",
"status",
"staged",
@@ -46,6 +47,7 @@ function comparableChangeFacet(facet: FileChangeFacet | undefined): string {
if (!facet) return "";
return [
facet.status,
+ facet.is_symlink ?? "",
facet.additions ?? 0,
facet.deletions ?? 0,
facet.old_path ?? "",
@@ -57,6 +59,7 @@ function comparableChangeFacet(facet: FileChangeFacet | undefined): string {
function comparableFileInfo(file: FileInfo) {
return {
path: file.path,
+ is_symlink: file.is_symlink,
status: file.status,
staged: file.staged,
additions: file.additions ?? 0,
diff --git a/apps/web/lib/state/slices/session-runtime/set-git-status-return.test.ts b/apps/web/lib/state/slices/session-runtime/set-git-status-return.test.ts
index f52049e021..b09ae19392 100644
--- a/apps/web/lib/state/slices/session-runtime/set-git-status-return.test.ts
+++ b/apps/web/lib/state/slices/session-runtime/set-git-status-return.test.ts
@@ -31,6 +31,18 @@ function status(overrides: Partial = {}): GitStatusEntry {
};
}
+it("accepts metadata-only changes and clears omitted snapshot metadata", () => {
+ const store = makeStore();
+ const first = status();
+ const linked = { ...first, files: { "a.ts": { ...first.files["a.ts"], is_symlink: true } } };
+ store.getState().setGitStatus(SESSION, first);
+ expect(store.getState().setGitStatus(SESSION, linked)).toBe(true);
+ expect(store.getState().setGitStatus(SESSION, first)).toBe(true);
+ expect(store.getState().gitStatus.byEnvironmentId[SESSION].files["a.ts"]).not.toHaveProperty(
+ "is_symlink",
+ );
+});
+
describe("setGitStatus change reporting (single deep compare)", () => {
let store: ReturnType;
diff --git a/apps/web/lib/state/slices/session-runtime/types.ts b/apps/web/lib/state/slices/session-runtime/types.ts
index 5fc53361ba..308bdbcd57 100644
--- a/apps/web/lib/state/slices/session-runtime/types.ts
+++ b/apps/web/lib/state/slices/session-runtime/types.ts
@@ -48,6 +48,7 @@ export type ProcessState = {
export type GitChangeLayer = "staged" | "unstaged";
export type FileChangeFacet = {
+ is_symlink?: boolean;
status: "modified" | "added" | "deleted" | "untracked" | "renamed";
additions?: number;
deletions?: number;
@@ -57,6 +58,7 @@ export type FileChangeFacet = {
};
export type FileInfo = {
+ is_symlink?: boolean;
path: string;
status: "modified" | "added" | "deleted" | "untracked" | "renamed";
staged: boolean;
diff --git a/apps/web/lib/types/backend.ts b/apps/web/lib/types/backend.ts
index 4b37dcb532..a430427113 100644
--- a/apps/web/lib/types/backend.ts
+++ b/apps/web/lib/types/backend.ts
@@ -329,6 +329,7 @@ export type OfficeInboxItemNotificationPayload = {
};
export type FileChangeFacet = {
+ is_symlink?: boolean;
status: "modified" | "added" | "deleted" | "untracked" | "renamed";
additions?: number;
deletions?: number;
@@ -338,6 +339,7 @@ export type FileChangeFacet = {
};
export type FileInfo = {
+ is_symlink?: boolean;
path: string;
status: "modified" | "added" | "deleted" | "untracked" | "renamed";
staged: boolean;
diff --git a/apps/web/lib/types/workspace-files.ts b/apps/web/lib/types/workspace-files.ts
index c3edfd9bd1..ea64571ee5 100644
--- a/apps/web/lib/types/workspace-files.ts
+++ b/apps/web/lib/types/workspace-files.ts
@@ -74,6 +74,7 @@ export type FileChangeNotificationPayload = {
};
export type OpenFileTab = {
+ resolvedPath?: string;
path: string;
name: string;
repo?: string;
diff --git a/apps/web/src/locales/en/editors.json b/apps/web/src/locales/en/editors.json
index ee659b3019..6babf09c0f 100644
--- a/apps/web/src/locales/en/editors.json
+++ b/apps/web/src/locales/en/editors.json
@@ -89,5 +89,6 @@
"toggleWordWrap": "Toggle word wrap",
"underlineCmdU": "Underline (Cmd+U)",
"failedToOpenEditor": "Failed to open editor",
- "downloadFile": "Download file"
+ "downloadFile": "Download file",
+ "symlink": "Symlink"
}
diff --git a/apps/web/src/locales/pseudo/editors.json b/apps/web/src/locales/pseudo/editors.json
index 4dfefecf95..e83310de79 100644
--- a/apps/web/src/locales/pseudo/editors.json
+++ b/apps/web/src/locales/pseudo/editors.json
@@ -89,5 +89,6 @@
"toggleWordWrap": "Ţōĝĝĺē ŵōŕď ŵŕàƥ",
"underlineCmdU": "Ũńďēŕĺĩńē (Ćḿď+Ũ)",
"failedToOpenEditor": "Ƒàĩĺēď ţō ōƥēń ēďĩţōŕ",
- "downloadFile": "Ďōŵńĺōàď ƒĩĺē"
+ "downloadFile": "Ďōŵńĺōàď ƒĩĺē",
+ "symlink": "Śŷḿĺĩńķ"
}
diff --git a/apps/web/src/locales/pt-pt/editors.json b/apps/web/src/locales/pt-pt/editors.json
index 168e65cb1e..d7c1f25ed1 100644
--- a/apps/web/src/locales/pt-pt/editors.json
+++ b/apps/web/src/locales/pt-pt/editors.json
@@ -89,5 +89,6 @@
"toggleWordWrap": "Alternar a quebra de linha",
"underlineCmdU": "Sublinhado (Cmd+U)",
"failedToOpenEditor": "Falha ao abrir o editor",
- "downloadFile": "Transferir ficheiro"
+ "downloadFile": "Transferir ficheiro",
+ "symlink": "Ligação simbólica"
}
diff --git a/apps/web/src/locales/zh-cn/editors.json b/apps/web/src/locales/zh-cn/editors.json
index cb346fb76b..e587b35012 100644
--- a/apps/web/src/locales/zh-cn/editors.json
+++ b/apps/web/src/locales/zh-cn/editors.json
@@ -89,5 +89,6 @@
"toggleWordWrap": "切换自动换行",
"underlineCmdU": "下划线（Cmd+U）",
"failedToOpenEditor": "打开编辑器失败",
- "downloadFile": "下载文件"
+ "downloadFile": "下载文件",
+ "symlink": "符号链接"
}
diff --git a/apps/web/src/locales/zh-hk/editors.json b/apps/web/src/locales/zh-hk/editors.json
index 410d07ea80..1ec5218728 100644
--- a/apps/web/src/locales/zh-hk/editors.json
+++ b/apps/web/src/locales/zh-hk/editors.json
@@ -89,5 +89,6 @@
"toggleWordWrap": "切換自動換行",
"underlineCmdU": "下劃線（Cmd+U）",
"failedToOpenEditor": "開啟編輯器失敗",
- "downloadFile": "下載檔案"
+ "downloadFile": "下載檔案",
+ "symlink": "符號連結"
}
diff --git a/apps/web/src/locales/zh-tw/editors.json b/apps/web/src/locales/zh-tw/editors.json
index 2154a51675..20af98e832 100644
--- a/apps/web/src/locales/zh-tw/editors.json
+++ b/apps/web/src/locales/zh-tw/editors.json
@@ -89,5 +89,6 @@
"toggleWordWrap": "切換自動換行",
"underlineCmdU": "下劃線（Cmd+U）",
"failedToOpenEditor": "開啟編輯器失敗",
- "downloadFile": "下載檔案"
+ "downloadFile": "下載檔案",
+ "symlink": "符號連結"
}
diff --git a/docs/plans/symlink-identification/plan.md b/docs/plans/symlink-identification/plan.md
new file mode 100644
index 0000000000..05ea121716
--- /dev/null
+++ b/docs/plans/symlink-identification/plan.md
@@ -0,0 +1,140 @@
+---
+created: 2026-09-14
+status: implemented
+requirements:
+ - REQ-WORKSPACES-SYMLINK-001
+system_design:
+ - ../../specs/workspaces/system-design/symlink-identification.md
+legacy_specs: []
+---
+
+# Implementation Plan: Symlink identification
+
+## Overview
+
+Deliver one vertical slice: authoritative change-layer metadata, live projection,
+then consistent Changes and editor indicators. One sequential work order owns
+integration and verification. Implementation and targeted verification are complete.
+
+## Scope
+
+In scope: workspace staged/unstaged/untracked rows, list/tree layouts, opened
+files in both editor providers and existing preview/mobile surfaces, localization,
+and stale metadata removal. Out of scope: target navigation, file-tree redesign,
+remote PR/historical classification without mode metadata, and changed mutations.
+
+## Technical approach
+
+Follow the [design](../../specs/workspaces/system-design/symlink-identification.md).
+Extend `FileInfo`/`FileChangeFacet` through the existing transport and store;
+classify each layer independently without reading targets or depending on patch
+bodies. Thread existing resolved-path editor state through shared indicators.
+Reuse mobile Changes/viewer composition. No new dependency or storage schema.
+
+## ASCII UI preview
+
+UI-01: Workspace Changes, list or tree, desktop and phone.
+Entry: task Changes; state: an uncommitted symlink and regular file.
+
+```text
+Changes > Unstaged
+[+] [link] CLAUDE.md [edit] [discard]
+[+] AGENTS.md [edit] [discard]
+```
+
+UI-02: Opened symlink, desktop editor toolbar or phone viewer header.
+Entry: edit/open CLAUDE.md; state: readable symlink.
+
+```text
+CLAUDE.md [link] Symlink [existing actions]
+------------------------------------------------
+ file contents
+```
+
+The same inline content applies on phones inside the existing mobile surfaces;
+existing navigation and touch-sized actions remain. Required: marker persists
+on hover, filename can truncate, marker does not shrink, editor label is visible.
+Spacing and English copy are illustrative, not pixel or localization contracts.
+Regular files and unknown metadata omit the marker. Broken links retain the
+Changes marker and existing file-open error. No new empty/loading surface.
+Maps to AC-WORKSPACES-SYMLINK-001.1 through .4; rendered checks below prove it.
+
+## Tests
+
+- AC 001.1 and 001.3: add `TestSymlinkStatusMetadata` in
+ `workspace_git_symlink_test.go`: staged, unstaged, untracked, deletion, rename,
+ type replacement, mixed layer, broken/external target, skipped diff and unknown
+ metadata. Use real temporary Git repositories. Verify JSON serialization.
+- AC 001.1 and 001.4: extend `changes-panel-helpers.test.ts`,
+ `changes-panel-file-row.test.tsx` and `set-git-status-return.test.ts` for facet
+ mapping, regular/unknown entries, marker persistence and metadata-only refresh.
+- AC 001.2 and 001.4: extend `use-file-editors.build-state.test.ts`,
+ `file-editors-sync.test.ts`, and `file-editor-content.test.tsx` for both
+ providers, symlink-to-regular reload with unchanged contents, same paths in two
+ repositories, and preservation of dirty buffers/request identity.
+
+All AC suffixes refer to AC-WORKSPACES-SYMLINK-001.
+
+## E2E tests
+
+Extend `e2e/tests/git/symlink-file.spec.ts` (chromium) with Changes list/tree
+markers and editor identification for both providers. Existing target-edit/save
+coverage must still pass. Add `e2e/tests/git/mobile-symlink-identification.spec.ts`
+(mobile-chrome) using real symlink fixtures and existing mobile navigation:
+identify the row, tap edit, assert visible editor label, open the regular target,
+and assert the label disappears. Check long paths, document overflow, and retained
+action hit areas. Together these cover AC 001.1 through .4.
+Managed runners rebuild product assets; run desktop and mobile sequentially.
+
+## Work orders
+
+- [x] [Task 01: Identify workspace symlinks](task-01-identify-symlinks.md)
+
+## Verification
+
+```bash
+(cd apps && pnpm install --frozen-lockfile)
+(cd apps/backend && GOCACHE=/tmp/kandev-symlink-go-cache go test ./internal/agentctl/server/process -run 'Symlink|Mixed' -count=1)
+(cd apps/backend && GOCACHE=/tmp/kandev-symlink-go-cache go test ./internal/agentctl/types/... -count=1)
+(cd apps/web && pnpm test components/task/changes-panel-helpers.test.ts components/task/changes-panel-file-row.test.tsx components/task/file-editor-content.test.tsx hooks/use-file-editors.build-state.test.ts hooks/file-editors-sync.test.ts hooks/domains/session/git-change-facets.test.ts lib/state/slices/session-runtime/set-git-status-return.test.ts)
+(cd apps/web && pnpm run typecheck)
+(cd apps/web && pnpm run i18n:check)
+(cd apps/web && GOCACHE=/tmp/kandev-symlink-go-cache pnpm e2e:run --project chromium tests/git/symlink-file.spec.ts)
+(cd apps/web && GOCACHE=/tmp/kandev-symlink-go-cache pnpm e2e:run --no-build --project mobile-chrome tests/git/mobile-symlink-identification.spec.ts)
+python3 scripts/list-docs.py validate
+python3 scripts/lint-spec-files.py --all
+git diff --check
+```
+
+## Verification results
+
+Unit, integration, typecheck, localization and lint checks passed. Desktop E2E
+passed (4 tests); mobile E2E passed (1 test). Exact commands and results are recorded in
+[Task 01](task-01-identify-symlinks.md#results).
+
+Post-fixup review regressions are recorded in [Task 01](task-01-identify-symlinks.md#post-fixup-verification): same-path delete/recreate layers are preserved and an existing editor tab refreshes symlink identity without losing dirty content.
+
+## Risks
+
+Mode changes and deleted paths cannot be classified from today's filesystem
+alone. Diff budgets must not erase identity. Store equality and editor refresh
+can otherwise retain stale labels. Platforms unable to create native symlinks
+need explicit test skips with a reason; Unix CI must exercise real fixtures.
+
+## Public documentation
+
+During implementation add a concise explanation of the marker and editor label
+to `docs/public/sessions-and-review.md` (how-to). Do not advertise draft behavior
+in public docs during this design turn.
+
+User-requested follow-up: Files tree entries use the shared link glyph in the
+existing file/folder icon slot when `FileTreeNode.is_symlink` is true. Desktop
+and phone Files surfaces share this renderer. Directory chevrons, touch actions,
+and ordinary icons are preserved. Search results without metadata are unchanged.
+
+```text
+Files (desktop and phone)
+ [link] new-link.md
+ [file] ordinary-file.md
+ > [link] linked-directory
+```
diff --git a/docs/plans/symlink-identification/task-01-identify-symlinks.md b/docs/plans/symlink-identification/task-01-identify-symlinks.md
new file mode 100644
index 0000000000..5726c0543a
--- /dev/null
+++ b/docs/plans/symlink-identification/task-01-identify-symlinks.md
@@ -0,0 +1,216 @@
+---
+id: "01-identify-symlinks"
+title: "Identify workspace symlinks"
+status: done
+wave: 1
+depends_on: []
+plan: "plan.md"
+requirements:
+ - REQ-WORKSPACES-SYMLINK-001
+acceptance_criteria:
+ - AC-WORKSPACES-SYMLINK-001.1
+ - AC-WORKSPACES-SYMLINK-001.2
+ - AC-WORKSPACES-SYMLINK-001.3
+ - AC-WORKSPACES-SYMLINK-001.4
+system_design:
+ - ../../specs/workspaces/system-design/symlink-identification.md
+---
+
+# Task 01: Identify workspace symlinks
+
+## Summary
+
+Add authoritative symlink identity to workspace change layers and render a
+persistent marker beside filenames. Reuse resolved editor metadata for a visible
+Symlink label across desktop, phone, and both editor providers.
+
+## In scope
+
+Metadata collection/projection, stale-state handling, shared marker, provider and
+preview header wiring, all locales, focused tests and public documentation.
+
+## Out of scope
+
+New file actions, target-path disclosure, persistence, new settings, file-tree
+redesign, and classification of remote/historical changes from the live checkout.
+
+## Acceptance
+
+1. Correct per-layer markers survive deleted/broken links and skipped patches;
+ metadata-only changes refresh correctly and unknown entries are unmarked.
+2. Readable symlinks display the localized editor label for both providers and
+ mobile; regular targets do not. Repository isolation and save behavior hold.
+3. Desktop/mobile rendered checks prove long-path containment, accessible labels,
+ and existing action reachability; every planned check passes or a concrete
+ environment blocker remains explicitly recorded.
+
+## ASCII UI preview
+
+UI-01: Workspace Changes, list or tree, desktop and phone.
+Entry: task Changes; state: an uncommitted symlink and regular file.
+
+```text
+Changes > Unstaged
+[+] [link] CLAUDE.md [edit] [discard]
+[+] AGENTS.md [edit] [discard]
+```
+
+UI-02: Opened symlink, desktop editor toolbar or phone viewer header.
+Entry: edit/open CLAUDE.md; state: readable symlink.
+
+```text
+CLAUDE.md [link] Symlink [existing actions]
+------------------------------------------------
+ file contents
+```
+
+The same inline content applies on phones inside the existing mobile surfaces;
+existing navigation and touch-sized actions remain. Required: marker persists
+on hover, filename can truncate, marker does not shrink, editor label is visible.
+Spacing and English copy are illustrative, not pixel or localization contracts.
+Regular files and unknown metadata omit the marker. Broken links retain the
+Changes marker and existing file-open error. No new empty/loading surface.
+Maps to AC-WORKSPACES-SYMLINK-001.1 through .4; rendered checks below prove it.
+
+Full context: [plan previews](plan.md#ascii-ui-preview).
+
+## Verification
+
+Use TDD: add failing focused cases before implementation, then run:
+
+```bash
+(cd apps && pnpm install --frozen-lockfile)
+(cd apps/backend && GOCACHE=/tmp/kandev-symlink-go-cache go test ./internal/agentctl/server/process -run 'Symlink|Mixed' -count=1)
+(cd apps/backend && GOCACHE=/tmp/kandev-symlink-go-cache go test ./internal/agentctl/types/... -count=1)
+(cd apps/web && pnpm test components/task/changes-panel-helpers.test.ts components/task/changes-panel-file-row.test.tsx components/task/file-editor-content.test.tsx hooks/use-file-editors.build-state.test.ts hooks/file-editors-sync.test.ts hooks/domains/session/git-change-facets.test.ts lib/state/slices/session-runtime/set-git-status-return.test.ts)
+(cd apps/web && pnpm run typecheck)
+(cd apps/web && pnpm run i18n:check)
+(cd apps/web && GOCACHE=/tmp/kandev-symlink-go-cache pnpm e2e:run --project chromium tests/git/symlink-file.spec.ts)
+(cd apps/web && GOCACHE=/tmp/kandev-symlink-go-cache pnpm e2e:run --no-build --project mobile-chrome tests/git/mobile-symlink-identification.spec.ts)
+python3 scripts/list-docs.py validate
+python3 scripts/lint-spec-files.py --all
+git diff --check
+```
+
+The install is needed once per fresh worktree. If additional test files change,
+append their exact targeted commands to this record and execute them as well.
+
+## Files likely touched
+
+- `apps/backend/internal/agentctl/types/streams/git.go`;
+ `apps/backend/internal/agentctl/server/process/workspace_git_status.go`,
+ `workspace_git_diff.go`, and new `workspace_git_symlink_test.go`.
+- `apps/web/lib/types/backend.ts`,
+ `apps/web/lib/state/slices/session-runtime/{types,git-status-state}.ts`;
+ Changes layer projection, `changes-panel-helpers.ts`,
+ `changes-panel-file-row.tsx`, and equality signatures where necessary.
+- `apps/web/hooks/file-editors-sync.ts`, `file-editor-state.ts`;
+ `apps/web/components/task/file-editor-{panel,content}.tsx`, `file-tab-content.tsx`,
+ `file-viewer-header.tsx`, preview headers, `mobile/mobile-file-viewer-panel.tsx`;
+ `apps/web/components/editors/monaco/monaco-editor-toolbar.tsx`,
+ `monaco/monaco-code-editor.tsx`, `codemirror/codemirror-code-editor.tsx`, and
+ shared indicator component.
+- Test files named in the plan, `apps/web/src/locales/`,
+ `docs/public/sessions-and-review.md`, and these design/delivery artifacts.
+
+## Dependencies
+
+None. Existing Git execution, access validation, mobile views and editor state
+are reused. Inspect every intermediate mapper to preserve optional metadata.
+
+## Risks
+
+See [plan risks](plan.md#risks). Preserve current working-tree security checks
+and avoid introducing per-row filesystem requests or Git subprocesses.
+
+## Parallelism
+
+`sequential`
+
+## Inputs
+
+- [Requirements](../../specs/workspaces/requirements/symlink-identification.md)
+- [Design](../../specs/workspaces/system-design/symlink-identification.md)
+- Existing `symlink-file.spec.ts`, `workspace_files_test.go`, and
+ `workspace_git_mixed_changes_test.go` fixture patterns.
+- Scoped frontend/backend/agentctl guidance and `/tdd`, `/mobile-parity`, `/e2e`.
+
+## Results
+
+Implementation and initial verification complete.
+
+- Red: seven real-Git metadata scenarios failed on missing `is_symlink`;
+ four frontend assertions failed on dropped metadata, layer projection,
+ ignored metadata-only snapshots and stale editor identity.
+- Green: planned Go Symlink/Mixed tests and `types/...` suites passed. The
+ default shared Go build cache produced missing-standard-library errors;
+ an isolated `GOCACHE=/tmp/kandev-symlink-go-cache` resolved the environment issue.
+- Planned frontend command (including `git-change-facets.test.ts`): 7 files,
+ 91 tests passed. Additional affected editor/restoration command below:
+ 13 files, 68 tests passed.
+- `pnpm run typecheck` passed. `pnpm run i18n:check` and
+ `pnpm run i18n:ratchet` passed after generating the new Traditional Chinese
+ and pseudo-locale editor entry. Unrelated generator rewrites were removed.
+- Focused ESLint passed with no errors. The CodeMirror toolbar was split to
+ retain its function-size limit; new regression cases were moved out of
+ oversized test describe blocks. Final focused lint passed without warnings.
+- Additional Git status compatibility cases passed. Reorganized frontend
+ regression suites passed again (2 files, 20 tests).
+- Fresh backend/Vite/fixture build passed. Sandbox E2E attempts could not bind
+ the local HTTP socket (`operation not permitted`); the focused runs passed
+ with sandbox escalation. Desktop: 4 tests passed (28.4s), covering both
+ providers and flat/tree layouts. Mobile: 1 test passed (6.6s), including
+ marker containment and 44px edit target. Its initial selector was corrected
+ to allow the Changes navigation button's file-count suffix.
+- Final artifact validation, 36 specification linter tests, and diff whitespace
+ checks passed.
+
+Additional affected-file verification (from repository root):
+
+```bash
+(cd apps/backend && GOCACHE=/tmp/kandev-symlink-go-cache go test ./internal/agentctl/server/process -run 'TestGetGitStatus|TestApplyPorcelain|TestUnquoteGitPath' -count=1)
+(cd apps/web && pnpm test components/task/file-browser-actions.test.ts components/task/task-center-panel-restoration.test.ts hooks/use-file-editors.build-state.test.ts hooks/use-file-editors.test.tsx hooks/use-file-editors.open-action.test.tsx components/task/file-tab-content.test.tsx components/task/file-tab-content.external-link.test.tsx components/task/html-preview-content.test.tsx components/task/markdown-preview-content.test.ts components/task/markdown-preview-content.external-link.test.tsx components/editors/monaco/monaco-editor-toolbar.test.tsx components/task/file-editor-panel.image.test.tsx components/task/file-editor-panel.download.test.tsx)
+```
+
+Design validation before implementation: catalog passed (267 decisions, 911
+specifications), specification linter tests passed (36), full spec lint and
+whitespace checks passed. Final artifact validation also passed.
+
+The successful browser invocations reused the freshly built, unchanged product
+assets after the sandbox restriction was diagnosed:
+
+```bash
+(cd apps/web && GOCACHE=/tmp/kandev-symlink-go-cache pnpm e2e:run --no-build --project chromium tests/git/symlink-file.spec.ts)
+(cd apps/web && GOCACHE=/tmp/kandev-symlink-go-cache pnpm e2e:run --no-build --project mobile-chrome tests/git/mobile-symlink-identification.spec.ts)
+```
+
+
+User follow-up: use the existing Files tree icon slot for symlink identity on
+desktop and mobile. Reuse `FileTreeNode.is_symlink` and the shared glyph, including
+symlink directories; retain chevrons and regular-entry icons. Existing mobile
+Files rows are the exemplar; no navigation or touch geometry changes. Extend
+the existing desktop/provider/directory and mobile rendered checks.
+
+Files icon follow-up verification: original-build desktop regressions failed
+on missing tree link glyphs. Fresh `pnpm build:e2e` passed. The existing global
+editor-marker assertions then matched the new tree markers too; scoped them
+outside Files. Final desktop suite: 4 passed (26.2s); mobile suite: 1 passed
+(6.4s). Focused ESLint, typecheck, spec validation/lint, and whitespace checks
+passed. Reloaded the isolated Tailscale instance and verified its real Files
+icons in a headless browser. No main-instance changes were made.
+
+## Post-fixup verification
+
+Addressed review findings for same-path staged deletion plus untracked
+replacement and already-open editor tabs whose symlink type changes. The
+backend now preserves both change layers and the tab upsert refreshes
+`resolvedPath` without overwriting dirty content.
+
+```bash
+(cd apps/backend && GOCACHE=/tmp/kandev-symlink-go-cache go test ./internal/agentctl/server/process -count=1)
+(cd apps/web && pnpm test -- --run components/task/task-center-panel-file-tabs.test.ts hooks/use-file-editors.build-state.test.ts hooks/file-editors-sync.test.ts hooks/use-task-center-file-open.test.ts)
+(cd apps/web && pnpm exec eslint components/task/task-center-panel-file-tabs.ts components/task/task-center-panel-file-tabs.test.ts hooks/use-task-center-file-open.ts)
+```
+
+The focused frontend run passed 34 tests, the full backend process package
+passed, and the new regression cases passed before the fixup commit.
diff --git a/docs/public/sessions-and-review.md b/docs/public/sessions-and-review.md
index 3dd140ed47..01ab29e8ec 100644
--- a/docs/public/sessions-and-review.md
+++ b/docs/public/sessions-and-review.md
@@ -259,6 +259,13 @@ impossible data when reported use exceeds the reported window.
Open **+ > Changes** on desktop. A repository-less task has no Git state, so Kandev closes this panel automatically.
+Symbolic links have a link icon beside their filename in workspace **Staged**
+and **Unstaged** rows, including untracked links. Opening a readable link shows
+**Symlink** beside its path in the file editor. These indicators are also visible
+on phones. In **Files**, symbolic links use a link icon in place of the usual
+file or folder icon. Each Changes row identifies the entry in that change layer; a deleted
+link keeps its marker. Opening and saving files follows the existing behavior.
+
Changes are grouped by repository and then by state:
- **PR Changes** for the linked pull-request comparison;
diff --git a/docs/specs/workspaces/requirements/symlink-identification.md b/docs/specs/workspaces/requirements/symlink-identification.md
new file mode 100644
index 0000000000..6a01d685e8
--- /dev/null
+++ b/docs/specs/workspaces/requirements/symlink-identification.md
@@ -0,0 +1,56 @@
+---
+status: active
+system: workspaces
+created: 2026-09-14
+owners:
+ - kandev
+---
+
+# Symlink identification
+
+## Overview
+
+Users shall recognize symbolic links in workspace Changes and file editor views.
+Workspaces owns this capability because link identity belongs to repository file
+state; the UI consumes that identity across desktop and phone surfaces.
+
+## Requirements
+
+### REQ-WORKSPACES-SYMLINK-001: Visible link identity
+
+A symlink is the selected directory entry itself, not a regular file reached
+through a symlinked ancestor. A Changes row describes its selected change layer.
+
+#### Acceptance criteria
+
+- **AC-WORKSPACES-SYMLINK-001.1:** Staged, unstaged and untracked symlink rows
+ shall carry a persistent link marker in both list and tree modes. A deletion
+ shall identify the removed entry. For a replacement, the resulting entry's
+ type shall determine the marker independently for each change layer.
+- **AC-WORKSPACES-SYMLINK-001.2:** Opening a readable symlink shall show a visible
+ localized Symlink label in the file editor, for either editor provider and on
+ phones. Opening its regular target shall not show that label. Repository and
+ session identity shall isolate same-named files.
+- **AC-WORKSPACES-SYMLINK-001.3:** A broken or inaccessible symlink shall remain
+ identifiable in Changes when entry metadata is available, without requiring
+ target contents. Existing file-open errors and permission boundaries shall
+ remain in force. Missing metadata shall not produce a guessed link marker.
+- **AC-WORKSPACES-SYMLINK-001.4:** Markers shall be perceivable without color or
+ hover, have localized accessible names, remain visible beside truncated long
+ paths, and preserve existing actions and touch targets. Metadata refresh shall
+ remove stale labels when an entry becomes a regular file. The Files tree shall
+ use a link glyph in the existing icon slot for symlink entries, including
+ directories, on desktop and phones. Regular entries retain their usual icons.
+
+## Scope and exclusions
+
+The requested outcome is identification, not target navigation or a new editing
+mode. Preserve save, stage, discard, diff, file-tree traversal, and access behavior.
+The scope is workspace Changes rows, Files tree icons, and opened files, including existing
+preview variants. Remote PR and historical commit rows without authoritative mode
+metadata are excluded; never classify them from today's checkout. No new setting,
+feature toggle, target-path disclosure, or persisted metadata is required.
+
+## Implementation plans
+
+- [Symlink identification](../../../plans/symlink-identification/plan.md)
diff --git a/docs/specs/workspaces/system-design/symlink-identification.md b/docs/specs/workspaces/system-design/symlink-identification.md
new file mode 100644
index 0000000000..4f473eaec9
--- /dev/null
+++ b/docs/specs/workspaces/system-design/symlink-identification.md
@@ -0,0 +1,93 @@
+---
+status: current
+system: workspaces
+requirements:
+ - REQ-WORKSPACES-SYMLINK-001
+---
+
+# Symlink identification design
+
+## Boundaries and evidence
+
+Workspace entry metadata is authoritative. The existing platform
+[Git status design](../../platform/system-design/workspace-git-status.md) owns
+observation, budgets and mixed-layer delivery; this addition preserves those
+contracts. `streams.FileTreeNode.IsSymlink` already describes file-tree entries.
+`FileContentResponse.resolved_path` is populated for readable direct symlinks,
+and `buildFileEditorState` stores it as `FileEditorState.resolvedPath`.
+Changes `ChangedFile` and editor chrome consume this identity for their indicators.
+The existing [workspace symlink ADR](../../../decisions/2026-07-19-workspace-symlink-entries.md)
+concerns storage maintenance, not editor access; it is not expanded here.
+
+## Metadata delivery
+
+Add optional `is_symlink` metadata to `streams.FileInfo` and
+`FileChangeFacet`, and mirror it in the frontend backend/state types.
+Use a nullable boolean in Go when unknown must be distinguished from false.
+Populate each layer from its destination mode, using its source mode only for
+an actual deletion. Index mode identifies staged entries; working-tree modes
+identify unstaged entries and Lstat identifies untracked entries; HEAD identifies staged deletions and
+index mode identifies unstaged deletions. Git symlinks have mode 120000.
+Mixed-layer facets own independent values; their flattened compatibility value
+matches the flattened status layer. Renames use the applicable old/new paths.
+
+Use at most two batched `git diff --raw -z --no-renames --no-ext-diff`
+reads (one with `--cached`) through the existing tracker Git execution boundary
+and its timeout/admission controls. `workspace_git_symlink.go` parses source and
+destination modes without relying on filename quoting or patch parsing. Never
+start one subprocess per file. Do not rely on diff body
+availability: binary, truncated and budget-skipped rows still need metadata.
+Avoid following target contents for classification; retain existing workspace
+path checks and cancellation. Handle type-change porcelain status where needed
+without changing existing stage/discard semantics. On metadata read failure,
+leave classification unknown while preserving ordinary status availability.
+
+Carry metadata through Git-status serialization, store equality/comparators,
+layer expansion and `mapToChangedFiles` into `ChangedFile.isSymlink`.
+Include the value in change signatures where equality suppresses UI updates.
+Never borrow metadata from a different repository, session, or historical view.
+
+## Editor and presentation
+
+For successfully loaded files, derive link identity from the existing nonempty
+`resolvedPath`. Pass it through `FileEditorContentProps`, both editor providers,
+viewer/preview header variants, and the mobile viewer header. Keep identity in
+file state rather than performing component-level requests. Refresh/reload paths
+must update or clear resolved metadata, including when content is unchanged.
+Retain current dirty-buffer conflict handling and request-generation guards.
+
+A small shared noninteractive indicator renders a link glyph with a translated
+accessible Symlink name. Changes shows the glyph adjacent to the filename,
+outside the hover-swapped stage/action slot. The editor shows glyph plus the
+visible translated label. It never takes focus or adds a click action.
+The Files tree consumes existing `FileTreeNode.is_symlink` and replaces its
+file/folder icon with the shared link glyph. Directory expand/collapse controls
+remain unchanged. Search results without entry metadata retain their usual icon.
+Keep it shrink-0 while the path truncates. Use existing tokens and icon library.
+Translate new copy in all five locales with the established Traditional Chinese
+generator; do not expose the target path as part of this feature.
+
+## Mobile parity
+
+Use `mobile-changes-panel.tsx` and `mobile-file-viewer-panel.tsx` as the shipped
+exemplars. The indicator is inline content in their existing surfaces. Preserve
+navigation, scroll ownership, safe areas, and touch action sizing. Link identity
+must survive row action visibility and long-path truncation on phones. There is
+no new tooltip-only disclosure, drawer, or preference.
+
+## Persistence and failure
+
+No migration, new polling, or metrics. Metadata is part of the existing accepted
+snapshot/read. Unknown metadata renders no indicator. Broken links can be marked
+in Changes while retaining the existing editor error. Classification grants no
+new filesystem access and does not resolve or read external target contents.
+
+## Requirement mapping
+
+| Criteria | Design | Evidence |
+| --- | --- | --- |
+| 001.1, 001.3 | Metadata delivery | Real Git fixtures, JSON round-trip, skipped diffs |
+| 001.2 | Editor and presentation | Both providers, direct target, repository isolation |
+| 001.4 | Presentation and mobile parity | Refresh tests, desktop/mobile rendered checks |
+
+All criterion suffixes refer to AC-WORKSPACES-SYMLINK-001.