santree 0.6.1 → 0.6.3

package/dist/lib/multiplexer/tmux.js

@@ -36,14 +36,6 @@ export const tmuxMultiplexer = {
         const ok = tmuxSync(`tmux select-window -t ${shellEscape(name)}`);
         return ok ? { ok: true } : { ok: false, reason: "failed" };
     },
-    renameWindow(_currentName, newName) {
-        if (!this.isActive())
-            return { ok: false, reason: "not-active" };
-        // tmux rename-window operates on the current window when no -t is given, which
-        // matches every existing call site in santree.
-        const ok = tmuxSync(`tmux rename-window ${shellEscape(newName)}`);
-        return ok ? { ok: true } : { ok: false, reason: "failed" };
-    },
     sendCommand(name, command) {
         if (!this.isActive())
             return { ok: false, reason: "not-active" };

package/dist/lib/multiplexer/types.d.ts

@@ -16,7 +16,6 @@ export interface Multiplexer {
     isActive(): boolean;
     createWindow(opts: CreateWindowOpts): Promise<SessionResult>;
     selectWindow(name: string): Promise<SessionResult>;
-    renameWindow(currentName: string, newName: string): SessionResult;
     sendCommand(name: string, command: string): SessionResult;
     isSessionAlive(ticketId: string): boolean;
 }

package/dist/lib/session-signal.d.ts

@@ -4,10 +4,12 @@ export declare function extractRepoAndTicket(cwd: string): {
     repoRoot: string;
     ticketId: string;
 } | null;
-export declare function renameSessionWindow(ticketId: string, state: SessionStateValue): void;
 /**
- * Unified helper: reads stdin, extracts repo/ticket, writes state file,
- * renames the multiplexer window, then exits.
+ * Unified helper: reads stdin, extracts repo/ticket, writes the session-state
+ * file, then exits. The dashboard reads the state file to render its session
+ * badges (◆ waiting / active / idle, ◇ id-only). Window/tab renaming used to
+ * happen here too but was removed — it clobbered names the user had set
+ * manually and added little value once the state file was in place.
  */
 export declare function signalState(state: SessionStateValue): void;
 export declare function getHooksJson(): Record<string, unknown>;

package/dist/lib/session-signal.js

@@ -1,6 +1,5 @@
 import * as fs from "fs";
 import * as path from "path";
-import { getMultiplexer } from "./multiplexer/index.js";
 export function readStdin() {
     try {
         return fs.readFileSync(0, "utf-8");
@@ -21,27 +20,12 @@ export function extractRepoAndTicket(cwd) {
         return null;
     return { repoRoot, ticketId };
 }
-export function renameSessionWindow(ticketId, state) {
-    const mux = getMultiplexer();
-    if (!mux.isActive())
-        return;
-    let name;
-    switch (state) {
-        case "waiting":
-            name = `${ticketId} !`;
-            break;
-        case "idle":
-            name = `${ticketId} ~`;
-            break;
-        default:
-            name = ticketId;
-            break;
-    }
-    mux.renameWindow("", name);
-}
 /**
- * Unified helper: reads stdin, extracts repo/ticket, writes state file,
- * renames the multiplexer window, then exits.
+ * Unified helper: reads stdin, extracts repo/ticket, writes the session-state
+ * file, then exits. The dashboard reads the state file to render its session
+ * badges (◆ waiting / active / idle, ◇ id-only). Window/tab renaming used to
+ * happen here too but was removed — it clobbered names the user had set
+ * manually and added little value once the state file was in place.
  */
 export function signalState(state) {
     const input = readStdin();
@@ -68,7 +52,6 @@ export function signalState(state) {
         at: new Date().toISOString(),
     };
     fs.writeFileSync(stateFile, JSON.stringify(payload, null, 2) + "\n");
-    renameSessionWindow(ticketId, state);
     process.exit(0);
 }
 export function getHooksJson() {

package/dist/lib/trackers/config.js

@@ -4,7 +4,7 @@ export function readTrackerConfig(repoRoot) {
     const tracker = all._tracker;
     const linear = all._linear;
     let kind = null;
-    if (tracker?.kind === "linear" || tracker?.kind === "github") {
+    if (tracker?.kind === "linear" || tracker?.kind === "github" || tracker?.kind === "local") {
         kind = tracker.kind;
     }
     return { kind, legacyLinearOrg: linear?.org ?? null };

package/dist/lib/trackers/index.d.ts

@@ -9,6 +9,17 @@ export { setRepoTracker, removeRepoTracker, readTrackerConfig } from "./config.j
  *   4. Auto-detect: any stored Linear creds → Linear, else GitHub (gh is always available).
  */
 export declare function getIssueTracker(repoRoot: string | null): IssueTracker;
+/**
+ * True when the repo has an *explicit* tracker choice — env override,
+ * per-repo `_tracker.kind`, legacy `_linear.org`, or any stored Linear
+ * credentials (the old auto-detect signal). When false, callers (the
+ * dashboard) should present the tracker-selection flow instead of letting
+ * `getIssueTracker` silently fall back to GitHub and then fail auth.
+ *
+ * Pure detection — does not alter `getIssueTracker`'s fallback, so existing
+ * non-dashboard call sites keep working unchanged.
+ */
+export declare function isRepoTrackerConfigured(repoRoot: string | null): boolean;
 export declare function getActiveTrackerKind(repoRoot: string | null): IssueTrackerKind;
 /**
  * Trackers worth trying when resolving a ticket from a foreign PR branch.

package/dist/lib/trackers/index.js

@@ -1,5 +1,6 @@
 import { linearTracker } from "./linear/index.js";
 import { githubTracker } from "./github/index.js";
+import { localTracker } from "./local/index.js";
 import { readTrackerConfig } from "./config.js";
 import { readLinearAuthStore } from "./auth-store.js";
 export { setRepoTracker, removeRepoTracker, readTrackerConfig } from "./config.js";
@@ -16,12 +17,16 @@ export function getIssueTracker(repoRoot) {
         return linearTracker;
     if (explicit === "github")
         return githubTracker;
+    if (explicit === "local")
+        return localTracker;
     if (repoRoot) {
         const cfg = readTrackerConfig(repoRoot);
         if (cfg.kind === "linear")
             return linearTracker;
         if (cfg.kind === "github")
             return githubTracker;
+        if (cfg.kind === "local")
+            return localTracker;
         if (cfg.legacyLinearOrg)
             return linearTracker;
     }
@@ -29,6 +34,27 @@ export function getIssueTracker(repoRoot) {
         return linearTracker;
     return githubTracker;
 }
+/**
+ * True when the repo has an *explicit* tracker choice — env override,
+ * per-repo `_tracker.kind`, legacy `_linear.org`, or any stored Linear
+ * credentials (the old auto-detect signal). When false, callers (the
+ * dashboard) should present the tracker-selection flow instead of letting
+ * `getIssueTracker` silently fall back to GitHub and then fail auth.
+ *
+ * Pure detection — does not alter `getIssueTracker`'s fallback, so existing
+ * non-dashboard call sites keep working unchanged.
+ */
+export function isRepoTrackerConfigured(repoRoot) {
+    const explicit = process.env["SANTREE_TRACKER"]?.toLowerCase();
+    if (explicit === "linear" || explicit === "github" || explicit === "local")
+        return true;
+    if (repoRoot) {
+        const cfg = readTrackerConfig(repoRoot);
+        if (cfg.kind || cfg.legacyLinearOrg)
+            return true;
+    }
+    return Object.keys(readLinearAuthStore()).length > 0;
+}
 export function getActiveTrackerKind(repoRoot) {
     return getIssueTracker(repoRoot).kind;
 }

package/dist/lib/trackers/local/frontmatter.d.ts

@@ -0,0 +1,12 @@
+export type FrontmatterValue = string | number | string[];
+export interface ParsedFile {
+    data: Record<string, FrontmatterValue>;
+    body: string;
+}
+/** Parse a Markdown document with an optional leading `---` frontmatter
+ * block. Returns `{ data, body }`; `data` is `{}` when there is no valid
+ * frontmatter. */
+export declare function parseFrontmatter(content: string): ParsedFile;
+/** Serialize `{ data, body }` back into a `---` frontmatter Markdown file.
+ * Key order is preserved as inserted by the caller. */
+export declare function serializeFrontmatter(data: Record<string, FrontmatterValue>, body: string): string;

package/dist/lib/trackers/local/frontmatter.js

@@ -0,0 +1,91 @@
+// Minimal, hand-rolled frontmatter parse/serialize.
+//
+// The project intentionally has no YAML dependency and adding one
+// (gray-matter / yaml) is out of scope. The Local tracker only ever stores
+// scalars (string, number) and a single string[] (`labels`), so a tiny
+// purpose-built reader/writer is enough. It is deliberately defensive:
+// unknown keys are preserved as raw strings, malformed lines are skipped,
+// and a missing/garbled frontmatter block yields an empty record rather
+// than throwing (matches the "degrade gracefully" pattern in metadata.ts).
+const FENCE = "---";
+function parseScalar(raw) {
+    const trimmed = raw.trim();
+    // Strip matching surrounding quotes if present.
+    const unquoted = (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))
+        ? trimmed.slice(1, -1)
+        : trimmed;
+    // Only treat as a number when the whole token is numeric — issue IDs
+    // like "LOCAL-1" must stay strings.
+    if (unquoted !== "" && /^-?\d+(\.\d+)?$/.test(unquoted)) {
+        return Number(unquoted);
+    }
+    return unquoted;
+}
+function parseList(raw) {
+    const inner = raw.trim().replace(/^\[/, "").replace(/\]$/, "");
+    if (inner.trim() === "")
+        return [];
+    return inner
+        .split(",")
+        .map((s) => {
+        const t = s.trim();
+        return (t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))
+            ? t.slice(1, -1)
+            : t;
+    })
+        .filter((s) => s.length > 0);
+}
+/** Parse a Markdown document with an optional leading `---` frontmatter
+ * block. Returns `{ data, body }`; `data` is `{}` when there is no valid
+ * frontmatter. */
+export function parseFrontmatter(content) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    if (lines[0]?.trim() !== FENCE) {
+        return { data: {}, body: normalized };
+    }
+    const data = {};
+    let i = 1;
+    for (; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (line.trim() === FENCE) {
+            i++;
+            break;
+        }
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            continue; // skip malformed line
+        const key = line.slice(0, colon).trim();
+        if (!key)
+            continue;
+        const rawValue = line.slice(colon + 1).trim();
+        data[key] = rawValue.startsWith("[") ? parseList(rawValue) : parseScalar(rawValue);
+    }
+    // Body is everything after the closing fence; drop a single leading
+    // blank line that separates fence from content.
+    const bodyLines = lines.slice(i);
+    if (bodyLines[0] === "")
+        bodyLines.shift();
+    return { data, body: bodyLines.join("\n").replace(/\s+$/, "") };
+}
+function serializeValue(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => v).join(", ")}]`;
+    }
+    if (typeof value === "number")
+        return String(value);
+    // Quote strings that contain characters which would break the simple
+    // `key: value` line parser or look like a list.
+    if (/^[\[\]]|[:#]|^\s|\s$/.test(value) || value === "") {
+        return JSON.stringify(value);
+    }
+    return value;
+}
+/** Serialize `{ data, body }` back into a `---` frontmatter Markdown file.
+ * Key order is preserved as inserted by the caller. */
+export function serializeFrontmatter(data, body) {
+    const head = Object.entries(data).map(([k, v]) => `${k}: ${serializeValue(v)}`);
+    const trimmedBody = body.replace(/\s+$/, "");
+    return `${FENCE}\n${head.join("\n")}\n${FENCE}\n\n${trimmedBody}\n`;
+}

package/dist/lib/trackers/local/index.d.ts

@@ -0,0 +1,2 @@
+import type { IssueTracker } from "../types.js";
+export declare const localTracker: IssueTracker;

package/dist/lib/trackers/local/index.js

@@ -0,0 +1,102 @@
+import { allocateId, deleteIssueFile, listIssues, priorityLabel, readCreatedAt, readIssue, writeIssue, } from "./store.js";
+// Terminal states are hidden from the "assigned" list, mirroring how Linear
+// filters out completed/canceled issues.
+const TERMINAL_TYPES = new Set(["completed", "canceled"]);
+async function getAuthStatus(repoRoot) {
+    if (!repoRoot) {
+        return { authenticated: false, hint: "Not inside a git repository" };
+    }
+    // Local has no credentials — being in a repo is all it needs.
+    return { authenticated: true, accountLabel: ".santree/issues" };
+}
+async function signOut(_repoRoot) {
+    // No credentials to clear.
+}
+function extractIdFromBranch(branch) {
+    // Recognizes `LOCAL-1`, `local-1`, `feature/LOCAL-1-foo`, `local-1-foo`.
+    // The dashboard builds branches as `feature/${ticketId}-${slug}` where
+    // ticketId is `LOCAL-1`, so the literal `LOCAL-1` is always present.
+    const m = branch.match(/(?:^|[/_-])local-(\d+)(?:-|$)/i);
+    if (!m)
+        return null;
+    return `LOCAL-${m[1]}`;
+}
+function cleanupCache(_identifier) {
+    // No remote image cache for local issues.
+}
+async function listAssigned(repoRoot) {
+    // Local has no assignee concept — "assigned" == all non-terminal issues.
+    const issues = listIssues(repoRoot).filter((i) => !TERMINAL_TYPES.has(i.state.type));
+    return { ok: true, value: issues };
+}
+async function getIssue(identifier, repoRoot) {
+    const issue = readIssue(repoRoot, identifier);
+    if (!issue) {
+        return { ok: false, reason: "not-found", message: `Issue ${identifier} not found` };
+    }
+    return { ok: true, value: issue };
+}
+async function createIssue(input, repoRoot) {
+    const identifier = allocateId(repoRoot);
+    const priority = input.priority ?? 0;
+    const issue = {
+        identifier,
+        title: input.title,
+        description: input.description.trim() === "" ? null : input.description,
+        url: "",
+        priority,
+        priorityLabel: priorityLabel(priority),
+        state: { name: "Todo", type: "unstarted" },
+        labels: input.labels ?? [],
+        projectId: null,
+        projectName: null,
+        comments: [],
+    };
+    writeIssue(repoRoot, issue, new Date().toISOString());
+    return { ok: true, value: issue };
+}
+async function updateIssue(identifier, patch, repoRoot) {
+    const existing = readIssue(repoRoot, identifier);
+    if (!existing) {
+        return { ok: false, reason: "not-found", message: `Issue ${identifier} not found` };
+    }
+    const priority = patch.priority ?? existing.priority;
+    const updated = {
+        ...existing,
+        title: patch.title ?? existing.title,
+        description: patch.description !== undefined
+            ? patch.description.trim() === ""
+                ? null
+                : patch.description
+            : existing.description,
+        priority,
+        priorityLabel: patch.priority !== undefined ? priorityLabel(priority) : existing.priorityLabel,
+        labels: patch.labels ?? existing.labels,
+        state: patch.state ?? existing.state,
+    };
+    // Preserve the original creation timestamp across edits.
+    writeIssue(repoRoot, updated, readCreatedAt(repoRoot, identifier) || new Date().toISOString());
+    return { ok: true, value: updated };
+}
+async function deleteIssue(identifier, repoRoot) {
+    const ok = deleteIssueFile(repoRoot, identifier);
+    if (!ok) {
+        return { ok: false, reason: "not-found", message: `Issue ${identifier} not found` };
+    }
+    return { ok: true, value: undefined };
+}
+export const localTracker = {
+    kind: "local",
+    displayName: "Local",
+    issueNoun: "issue",
+    getAuthStatus,
+    signOut,
+    extractIdFromBranch,
+    cleanupCache,
+    listAssigned,
+    getIssue,
+    canMutate: true,
+    createIssue,
+    updateIssue,
+    deleteIssue,
+};

package/dist/lib/trackers/local/store.d.ts

@@ -0,0 +1,30 @@
+import type { Issue } from "../types.js";
+export declare const ID_PREFIX = "LOCAL";
+export declare function getIssuesDir(repoRoot: string): string;
+export declare function ensureIssuesDir(repoRoot: string): string;
+/** Map a Linear-style numeric priority to a human label. 0 == no priority. */
+export declare function priorityLabel(priority: number): string;
+/** Read every well-formed issue file. Malformed files are skipped, never
+ * fatal. Returned newest-first by creation time (falling back to numeric ID). */
+export declare function listIssues(repoRoot: string): Issue[];
+export declare function readIssue(repoRoot: string, identifier: string): Issue | null;
+/** Write (create or overwrite) an issue file. `createdAt` preserves the
+ * original timestamp on edits; pass a fresh ISO string when creating. */
+export declare function writeIssue(repoRoot: string, issue: Issue, createdAt: string): void;
+/** Return the original `createdAt` for an existing issue, or "" if unknown. */
+export declare function readCreatedAt(repoRoot: string, identifier: string): string;
+export declare function deleteIssueFile(repoRoot: string, identifier: string): boolean;
+/**
+ * Allocate the next issue ID and persist the high-water mark so numbers are
+ * monotonic and never recycled: deleting LOCAL-3 then creating again yields
+ * LOCAL-4, not LOCAL-3 — a stale local `feature/LOCAL-3-*` branch/worktree
+ * can't collide with a reused ID.
+ *
+ * The counter lives in `.santree/metadata.json` (`_local.lastId`), which is
+ * git-ignored and therefore per-machine. That's exactly the right scope: the
+ * collision we're avoiding is with *local* worktrees/branches. On a fresh
+ * clone metadata.json is absent, so the counter rebuilds from the committed
+ * issue files (max existing) — correct, since a fresh clone has no stale
+ * local worktrees.
+ */
+export declare function allocateId(repoRoot: string): string;

package/dist/lib/trackers/local/store.js

@@ -0,0 +1,203 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getSantreeDir, readAllMetadata, writeAllMetadata } from "../../metadata.js";
+import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+// On-disk layout: one Markdown file per issue under `.santree/issues/`,
+// named `<ID>.md` (e.g. `LOCAL-1.md`). `.santree/issues/` is NOT in
+// .gitignore (which only excludes worktrees/metadata.json/session-states),
+// so issue files are version-controlled by default — the whole point of the
+// built-in tracker.
+//
+// Comments are intentionally not modeled in v1: Local issues always carry
+// `comments: []`. The Issue type already permits an empty array.
+export const ID_PREFIX = "LOCAL";
+const FILE_RE = /^LOCAL-(\d+)\.md$/;
+export function getIssuesDir(repoRoot) {
+    return path.join(getSantreeDir(repoRoot), "issues");
+}
+export function ensureIssuesDir(repoRoot) {
+    const dir = getIssuesDir(repoRoot);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+function issueFilePath(repoRoot, identifier) {
+    return path.join(getIssuesDir(repoRoot), `${identifier}.md`);
+}
+/** Map a Linear-style numeric priority to a human label. 0 == no priority. */
+export function priorityLabel(priority) {
+    switch (priority) {
+        case 1:
+            return "Urgent";
+        case 2:
+            return "High";
+        case 3:
+            return "Medium";
+        case 4:
+            return "Low";
+        default:
+            return "None";
+    }
+}
+function recordToIssue(data, body) {
+    const identifier = typeof data["id"] === "string" ? data["id"] : null;
+    if (!identifier || !FILE_RE.test(`${identifier}.md`))
+        return null;
+    const title = typeof data["title"] === "string" ? data["title"] : String(data["title"] ?? "");
+    const priority = typeof data["priority"] === "number" ? data["priority"] : 0;
+    const labels = Array.isArray(data["labels"]) ? data["labels"] : [];
+    const stateName = typeof data["state"] === "string" ? data["state"] : "Todo";
+    const stateType = typeof data["stateType"] === "string" ? data["stateType"] : "unstarted";
+    const description = body.trim() === "" ? null : body;
+    return {
+        identifier,
+        title,
+        description,
+        url: "", // Local issues have no web URL — the dashboard hides the [o] action.
+        priority,
+        priorityLabel: typeof data["priorityLabel"] === "string" ? data["priorityLabel"] : priorityLabel(priority),
+        state: { name: stateName, type: stateType },
+        labels,
+        projectId: null,
+        projectName: null,
+        comments: [],
+    };
+}
+function issueToRecord(issue, createdAt) {
+    return {
+        data: {
+            id: issue.identifier,
+            title: issue.title,
+            state: issue.state.name,
+            stateType: issue.state.type,
+            priority: issue.priority,
+            priorityLabel: issue.priorityLabel,
+            labels: issue.labels,
+            createdAt,
+        },
+        body: issue.description ?? "",
+    };
+}
+/** Read every well-formed issue file. Malformed files are skipped, never
+ * fatal. Returned newest-first by creation time (falling back to numeric ID). */
+export function listIssues(repoRoot) {
+    const dir = getIssuesDir(repoRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const m = name.match(FILE_RE);
+        if (!m)
+            continue;
+        try {
+            const raw = fs.readFileSync(path.join(dir, name), "utf-8");
+            const { data, body } = parseFrontmatter(raw);
+            const issue = recordToIssue(data, body);
+            if (!issue)
+                continue;
+            const createdAt = typeof data["createdAt"] === "string" ? data["createdAt"] : "";
+            out.push({ issue, createdAt, num: Number(m[1]) });
+        }
+        catch {
+            // Skip unreadable / corrupt file.
+        }
+    }
+    out.sort((a, b) => {
+        if (a.createdAt && b.createdAt && a.createdAt !== b.createdAt) {
+            return b.createdAt.localeCompare(a.createdAt);
+        }
+        return b.num - a.num;
+    });
+    return out.map((o) => o.issue);
+}
+export function readIssue(repoRoot, identifier) {
+    const file = issueFilePath(repoRoot, identifier);
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const { data, body } = parseFrontmatter(fs.readFileSync(file, "utf-8"));
+        return recordToIssue(data, body);
+    }
+    catch {
+        return null;
+    }
+}
+/** Write (create or overwrite) an issue file. `createdAt` preserves the
+ * original timestamp on edits; pass a fresh ISO string when creating. */
+export function writeIssue(repoRoot, issue, createdAt) {
+    ensureIssuesDir(repoRoot);
+    const { data, body } = issueToRecord(issue, createdAt);
+    fs.writeFileSync(issueFilePath(repoRoot, issue.identifier), serializeFrontmatter(data, body));
+}
+/** Return the original `createdAt` for an existing issue, or "" if unknown. */
+export function readCreatedAt(repoRoot, identifier) {
+    const file = issueFilePath(repoRoot, identifier);
+    if (!fs.existsSync(file))
+        return "";
+    try {
+        const { data } = parseFrontmatter(fs.readFileSync(file, "utf-8"));
+        return typeof data["createdAt"] === "string" ? data["createdAt"] : "";
+    }
+    catch {
+        return "";
+    }
+}
+export function deleteIssueFile(repoRoot, identifier) {
+    const file = issueFilePath(repoRoot, identifier);
+    if (!fs.existsSync(file))
+        return false;
+    try {
+        fs.unlinkSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function maxExistingNum(repoRoot) {
+    const dir = getIssuesDir(repoRoot);
+    let max = 0;
+    if (fs.existsSync(dir)) {
+        try {
+            for (const name of fs.readdirSync(dir)) {
+                const m = name.match(FILE_RE);
+                if (m)
+                    max = Math.max(max, Number(m[1]));
+            }
+        }
+        catch {
+            // fall through with max = 0
+        }
+    }
+    return max;
+}
+/**
+ * Allocate the next issue ID and persist the high-water mark so numbers are
+ * monotonic and never recycled: deleting LOCAL-3 then creating again yields
+ * LOCAL-4, not LOCAL-3 — a stale local `feature/LOCAL-3-*` branch/worktree
+ * can't collide with a reused ID.
+ *
+ * The counter lives in `.santree/metadata.json` (`_local.lastId`), which is
+ * git-ignored and therefore per-machine. That's exactly the right scope: the
+ * collision we're avoiding is with *local* worktrees/branches. On a fresh
+ * clone metadata.json is absent, so the counter rebuilds from the committed
+ * issue files (max existing) — correct, since a fresh clone has no stale
+ * local worktrees.
+ */
+export function allocateId(repoRoot) {
+    const all = readAllMetadata(repoRoot);
+    const local = all["_local"] ?? {};
+    const last = typeof local.lastId === "number" ? local.lastId : 0;
+    const next = Math.max(last, maxExistingNum(repoRoot)) + 1;
+    all["_local"] = { ...local, lastId: next };
+    writeAllMetadata(repoRoot, all);
+    return `${ID_PREFIX}-${next}`;
+}

package/dist/lib/trackers/types.d.ts

@@ -1,4 +1,4 @@
-export type IssueTrackerKind = "linear" | "github";
+export type IssueTrackerKind = "linear" | "github" | "local";
 export interface Comment {
     author: string;
     body: string;
@@ -39,6 +39,22 @@ export type IssueTrackerResult<T> = {
     reason: "unauthenticated" | "not-found" | "network";
     message?: string;
 };
+/** Fields accepted when creating a new issue. Only the built-in Local tracker
+ * supports mutation today (see `IssueTracker.canMutate`). */
+export interface NewIssueInput {
+    title: string;
+    description: string;
+    priority?: number;
+    labels?: string[];
+}
+/** Partial patch for an existing issue. Omitted fields are left unchanged. */
+export interface IssuePatch {
+    title?: string;
+    description?: string;
+    priority?: number;
+    labels?: string[];
+    state?: State;
+}
 export interface IssueTracker {
     readonly kind: IssueTrackerKind;
     readonly displayName: string;
@@ -49,4 +65,13 @@ export interface IssueTracker {
     cleanupCache(identifier: string): void;
     listAssigned(repoRoot: string): Promise<IssueTrackerResult<AssignedIssue[]>>;
     getIssue(identifier: string, repoRoot: string): Promise<IssueTrackerResult<Issue>>;
+    /** When true, the tracker implements createIssue/updateIssue/deleteIssue.
+     * Read-only trackers (Linear, GitHub) leave this undefined; UI surfaces
+     * gate every mutation path on `tracker.canMutate === true` (feature
+     * detection — never a `kind === "local"` string check, per the
+     * no-tracker-conditionals-outside-the-factory policy). */
+    readonly canMutate?: boolean;
+    createIssue?(input: NewIssueInput, repoRoot: string): Promise<IssueTrackerResult<Issue>>;
+    updateIssue?(identifier: string, patch: IssuePatch, repoRoot: string): Promise<IssueTrackerResult<Issue>>;
+    deleteIssue?(identifier: string, repoRoot: string): Promise<IssueTrackerResult<void>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "santree",
-	"version": "0.6.1",
+	"version": "0.6.3",
 	"description": "Git worktree manager",
 	"license": "MIT",
 	"author": "Santiago Toscanini",