@andrejvysny/symphony 0.1.0 → 0.1.2

package/README.md

@@ -1,47 +1,68 @@
 # @andrejvysny/symphony
 
-Agent-agnostic coding-agent orchestrator — delegate tickets to a **local coding agent** (Claude Code
-by default; Codex CLI / opencode also supported) running against a **local file-based task store**. A
-single-user local app: no SaaS, no Docker, no database, no auth — state is plain JSON under
-`~/.symphony`. TypeScript reimplementation of [Symphony](https://github.com/andrejvysny/symphony-ts).
+A local **web dashboard** for delegating coding tasks to AI agents. Create tickets on a kanban
+board, and Symphony runs a local coding agent (Claude Code by default) on each one in the background
+— you watch progress live in the browser. Single-user, runs entirely on your machine: no SaaS, no
+Docker, no database, no login. State is plain JSON under `~/.symphony`.
 
 ## Install
 
 ```bash
-npm i -g @andrejvysny/symphony      # or: pnpm add -g @andrejvysny/symphony
-symphony --help
+npm install -g @andrejvysny/symphony
 ```
 
-**Prerequisites**
+> Requires **Node ≥ 22**. The default agent uses your local **`claude` login** (`~/.claude`).
 
-- **Node ≥ 22**.
-- A local **`claude` login** (`~/.claude`) — the default backend reuses it. (Codex/opencode backends
-  use their own CLIs instead.)
-- A **`WORKFLOW.md`** config in your working directory — copy
-  [`WORKFLOW.md.example`](https://github.com/andrejvysny/symphony-ts/blob/master/WORKFLOW.md.example)
-  and set `workspace.repo` to your local git repo.
+## Launch the dashboard
 
-## Use
+**1. (Optional) scaffold a config:**
 
 ```bash
-# 1. Drop a WORKFLOW.md in the current dir (see WORKFLOW.md.example), then:
-symphony WORKFLOW.md --port 4500          # run the orchestrator + dashboard at http://127.0.0.1:4500/
+symphony init        # writes a WORKFLOW.md you can edit
+```
+
+**2. Start it:**
+
+```bash
+symphony --port 4500
+```
+
+> Zero-config is fine: `symphony --port 4500` runs with sensible defaults even without a
+> `WORKFLOW.md`, and the dashboard prompts you to create a project. `symphony init` just gives you a
+> file to customize.
 
-# Create tickets from the CLI (or the dashboard's "+ New ticket"):
-symphony ticket create "Add dark mode" --desc "..." --state Todo
+**3. Open the dashboard:** **http://127.0.0.1:4500**
 
+From there you can create a project (point it at a local git repo), add tickets, and watch the agent
+work them in real time.
+
+## In the dashboard
+
+- **Kanban board** — Backlog · Todo · In Progress · Human Review · Done, updating live as the agent works.
+- **Create tickets** — title, description, priority; the agent picks them up automatically.
+- **Live agent view** — the agent's plan (TodoWrite checklist) and activity stream per ticket.
+- **Projects** — switch between repos, or create a new one, without restarting.
+- **Settings** — backend, concurrency, timeouts, poll interval — applied live.
+
+## CLI
+
+```bash
+symphony init                                 # write a starter WORKFLOW.md (optional)
+symphony --port 4500                          # run the orchestrator + dashboard (zero-config OK)
+symphony ticket create "Add dark mode" --state Todo   # create a ticket from the terminal
+symphony --help
 symphony --version
 ```
 
-| Command                                                        | What it does                                      |
-| -------------------------------------------------------------- | ------------------------------------------------- |
-| `symphony [WORKFLOW.md] [--port <n>] [--json-logs]`            | Run the orchestrator (and dashboard if `--port`). |
-| `symphony ticket create "<title>" [--desc --state --priority]` | Create a ticket in the active project's store.    |
-| `symphony --version` / `--help`                                | Version / usage.                                  |
+## Security
+
+The dashboard has **no authentication** — keep it on loopback (`127.0.0.1`, the default). Binding to
+a public host exposes the API to your network.
 
-> The dashboard has **no authentication** — keep `server.host` on loopback (`127.0.0.1`).
+## Links
 
-Full docs, configuration reference, and architecture: **https://github.com/andrejvysny/symphony-ts**.
+- Full docs, configuration reference, and source: **https://github.com/andrejvysny/symphony-ts**
+- Annotated config: [`WORKFLOW.md.example`](https://github.com/andrejvysny/symphony-ts/blob/master/WORKFLOW.md.example)
 
 ## License
 

package/dist/WORKFLOW.md.example

@@ -0,0 +1,105 @@
+---
+# Symphony-TS workflow contract. Copy to WORKFLOW.md and customize.
+tracker:
+  kind: file
+  # Local file store root — every project + its issues live under here as plain JSON.
+  # Defaults to ~/.symphony when omitted. No database, no Docker, no external services.
+  data_root: ~/.symphony
+  # Active project key: a slug naming its directory under <data_root>/projects/. Leave unset to start
+  # with NO active project — the dashboard then prompts you to create or open one (managed from the
+  # project switcher; the chosen project is written back here). There is no implicit "default" project.
+  # project_id: my-project
+  # Symphony custom flow. The agent may set active_states + review_state (never terminal).
+  # Board lanes: Backlog · Todo · In Progress · Human Review · Done. "Rework" is no longer a state —
+  # the review "Rework" action sends a ticket back to In Progress with a `rework` badge. Cancelled is
+  # a terminal state for classification but is hidden from the board.
+  active_states: [Todo, In Progress]
+  terminal_states: [Done, Closed, Canceled, Cancelled, Duplicate]
+  # Non-active, non-terminal "park" state: the agent moves a finished issue here for a human.
+  review_state: Human Review
+  # Leftmost, non-active "not yet ready" lane (human-only — the orchestrator never dispatches it).
+  # Seeded into new projects and additively added to existing ones. Set to '' to disable.
+  backlog_state: Backlog
+  # The orchestrator moves an issue here the instant an agent picks it up from the entry lane (the
+  # first active state), so the board shows work-in-progress immediately. Must be active; '' disables.
+  in_progress_state: In Progress
+
+# Switchable projects for the dashboard's project switcher. The ACTIVE project is whichever
+# project_id/repo sit in `tracker`/`workspace` above; this registry is the set you can switch to
+# (and what "+ New project" appends to). Each entry = a project key + its own repo folder.
+# Switching live re-points the orchestrator (no restart). Managed from the dashboard — listed here
+# so it survives restarts.
+projects:
+  # - name: Backend
+  #   project_id: backend       # the project's dir key under <data_root>/projects/
+  #   repo: ~/code/backend
+  #   identifier: BE            # issue id prefix → BE-1, BE-2, …
+
+polling:
+  interval_ms: 5000
+
+workspace:
+  # single_dir (default): the agent works DIRECTLY in `repo` on its current branch, ONE task at a
+  # time, so tasks build on each other (commits land on e.g. master). `repo` must be a LOCAL path.
+  # worktree: each ticket gets an isolated worktree branched off `base_branch`, merged back on accept.
+  mode: single_dir
+  # The project repo. single_dir: a local path the agent edits. worktree: local path or git URL.
+  repo: ~/code/your-repo
+  # worktree mode only: where shared clone + per-issue worktrees live; and the branch naming prefix.
+  root: ~/code/symphony-workspaces
+  branch_prefix: "symphony/"
+  # worktree mode only: branch new worktrees off this branch (defaults to the clone's default branch).
+  # base_branch: main
+  # worktree mode only: on accept (review → Done) merge the issue branch into base_branch so the next
+  # worktree builds on top. On conflict the branch is preserved and a banner surfaces it. Default true.
+  merge_on_accept: true
+
+hooks:
+  # Runs once per new worktree. Install deps here.
+  after_create: |
+    if [ -f package.json ]; then npm ci || npm install; fi
+  timeout_ms: 120000
+
+agent:
+  backend: claude-sdk        # claude-sdk | claude-cli | codex-cli | opencode-cli
+  permission_mode: bypassPermissions   # full autonomy (high-trust)
+  max_concurrent_agents: 5
+  # Symphony's per-task RE-PROMPT budget (not the agent's own steps). 2 = one full delegation + at
+  # most one finish-up nudge if the agent stops before parking the issue for review.
+  max_turns: 2
+  # Cap consecutive continuation re-dispatches before blocking the issue (0 = unlimited). 1 = surface
+  # an unfinished task to the operator after the single nudge instead of looping.
+  max_continuations: 1
+  # max_agent_steps: 200           # optional: cap the AGENT's own internal step budget (SDK maxTurns).
+  #                                # Omit to leave uncapped so one delegation runs to completion.
+  # model: claude-opus-4-8         # optional model override
+  # effort: high                   # low | medium | high | xhigh | max (reasoning depth; default high)
+  # thinking: adaptive             # adaptive (Claude decides) | disabled
+  # max_budget_usd: 5              # optional per-turn budget cap (claude-sdk)
+  # system_prompt: |               # override the built-in Claude-optimized operating contract
+  #   <role>You are ...</role>
+  # tmux: true               # CLI backends only: run each turn in a tmux session you can
+                             # `tmux attach -t symphony-<id>`; raw stdout is logged to logs_root.
+                             # No effect on the in-process claude-sdk backend.
+
+# Root for raw tmux session logs (run.jsonl/err.log per turn). Default: <tmpdir>/symphony_logs.
+# Override at launch with `--logs-root <dir>`.
+# logs_root: ~/code/symphony-logs
+
+server:
+  port: 4500                 # enables the dashboard at http://127.0.0.1:4500/
+---
+
+You have been assigned issue {{ issue.identifier }}, working in an isolated git worktree on the branch you were started on.
+
+<issue>
+Identifier: {{ issue.identifier }}
+Issue id (pass as task_id to the tracker tools): {{ issue.id }}
+Title: {{ issue.title }}
+{% if issue.priority %}Priority: {{ issue.priority }}
+{% endif %}{% if issue.labels.size > 0 %}Labels: {{ issue.labels | join: ", " }}
+{% endif %}Description:
+{% if issue.description %}{{ issue.description }}{% else %}(No description was provided. Treat the title as the specification; if it is too vague to implement safely, follow the blocked protocol.){% endif %}
+</issue>
+
+Implement this issue end to end, following your operating protocol: read it with tracker_get_task, move it to "In Progress" with a short plan comment, make the change, confirm the project's build/tests/lint pass, commit locally, then post an evidence-backed summary comment (with the verification output and commit SHA) and move the issue to "Human Review". Keep every change scoped to this issue.

package/dist/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+var major = Number(process.versions.node.split(".")[0]);
+if (Number.isFinite(major) && major < 22) {
+  process.stderr.write(
+    `symphony requires Node >= 22 (you are on ${process.versions.node}). Please upgrade Node and re-run.
+`
+  );
+  process.exit(1);
+}
+await import(new URL("./main.js", import.meta.url).href);
+//# sourceMappingURL=cli.js.map

package/dist/main.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 // src/main.ts
-import path12 from "path";
+import { existsSync as existsSync4 } from "fs";
+import { writeFile as writeFile3 } from "fs/promises";
+import path13 from "path";
 
 // ../../packages/core/dist/index.js
 import { z as z5 } from "zod";
@@ -28,13 +30,13 @@ import { readFile as readFile3 } from "fs/promises";
 import path22 from "path";
 import YAML from "yaml";
 import { createHash } from "crypto";
-import { readFile as readFile22, stat, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir2, readFile as readFile22, stat, writeFile as writeFile2 } from "fs/promises";
 import path42 from "path";
 import { Liquid } from "liquidjs";
 import path7 from "path";
-import { mkdir as mkdir2 } from "fs/promises";
+import { mkdir as mkdir3 } from "fs/promises";
 import { execa } from "execa";
-import { access as access2, mkdir as mkdir3 } from "fs/promises";
+import { access as access2, mkdir as mkdir22 } from "fs/promises";
 import path5 from "path";
 import { simpleGit } from "simple-git";
 import { realpathSync } from "fs";
@@ -1597,18 +1599,53 @@ var FileStore = class {
   async doEnsure() {
     await fs.mkdir(this.issuesDir, { recursive: true });
     await fs.mkdir(this.uploadsDir, { recursive: true });
-    await this.writeIfAbsent(
-      this.metaFile,
-      JSON.stringify(
-        { identifier: this.seed.identifier, next_seq: 1 },
-        null,
-        2
-      )
-    );
+    await this.ensureMeta();
     await this.writeIfAbsent(this.statesFile, JSON.stringify(this.seed.states, null, 2));
     await this.writeIfAbsent(this.labelsFile, JSON.stringify(this.seed.labels ?? [], null, 2));
     await this.ensureSeedStates();
   }
+  /**
+   * Ensure meta.json exists and is valid. A fresh project seeds `{ identifier, next_seq: 1 }`. If
+   * meta.json is MISSING or CORRUPT while issue files already exist (deleted/corrupted out from under
+   * a populated project), recover instead of resetting ids to 1 — a reset would reissue existing ids
+   * and let a later create overwrite a live ticket. Recovery scans `issues/<ID>.json` for the max
+   * trailing `-<seq>` and the shared id prefix. Runs under the meta lock; the atomic write makes
+   * concurrent recovery converge (the recovered values are deterministic from the files on disk).
+   */
+  async ensureMeta() {
+    await withFileLock(this.metaFile, async () => {
+      if (await this.readJson(this.metaFile, metaSchema)) return;
+      const recovered = await this.recoverMeta();
+      await writeFileAtomic(this.metaFile, JSON.stringify(recovered, null, 2));
+    });
+  }
+  /** Reconstruct meta from existing issue filenames (max trailing `-<seq>` + their shared prefix). */
+  async recoverMeta() {
+    let names = [];
+    try {
+      names = await fs.readdir(this.issuesDir);
+    } catch (e) {
+      if (!isErrno(e, "ENOENT")) throw e;
+    }
+    let maxSeq = 0;
+    const prefixes = /* @__PURE__ */ new Set();
+    for (const name of names) {
+      const m = /^(.+)-(\d+)\.json$/.exec(name);
+      if (!m) continue;
+      prefixes.add(m[1]);
+      const seq2 = Number(m[2]);
+      if (Number.isFinite(seq2) && seq2 > maxSeq) maxSeq = seq2;
+    }
+    if (prefixes.size > 1) {
+      throw new Error(
+        `file store: cannot recover meta.json for project ${this.projectKey} \u2014 conflicting issue id prefixes: ${[...prefixes].sort().join(", ")}`
+      );
+    }
+    const identifier = prefixes.size === 1 ? [...prefixes][0] : this.seed.identifier;
+    if (maxSeq > 0)
+      this.warn(`file store: recovered meta.json for ${this.projectKey} (next_seq=${maxSeq + 1})`);
+    return { identifier, next_seq: maxSeq + 1 };
+  }
   /**
    * Additively reconcile states.json with the seeded state set so a newly-added lane (e.g. Backlog)
    * appears in already-created projects too. Preserves every existing entry, its data, and order;
@@ -1737,7 +1774,13 @@ var FileStore = class {
   /** Write a brand-new issue. Its id is unique (minted from reserveId) so no lock is needed. */
   async putNewIssue(issue) {
     await this.ensureProject();
-    await writeFileAtomic(this.issueFile(issue.id), JSON.stringify(issue, null, 2));
+    const file = this.issueFile(issue.id);
+    if (await fs.access(file).then(
+      () => true,
+      () => false
+    ))
+      throw new Error(`file store: refusing to overwrite existing issue ${issue.id}`);
+    await writeFileAtomic(file, JSON.stringify(issue, null, 2));
   }
   /** Read-modify-write one issue under its file lock. Throws if the issue does not exist. */
   async mutateIssue(id, fn) {
@@ -2096,24 +2139,26 @@ function str(v) {
 
 // ../../packages/core/dist/index.js
 import { execFile as execFile4 } from "child_process";
-import { appendFile, mkdir as mkdir32 } from "fs/promises";
+import { appendFile, mkdir as mkdir4 } from "fs/promises";
 import path8 from "path";
 import { promisify as promisify4 } from "util";
 import { pino } from "pino";
+import { createHash as createHash2 } from "crypto";
 import { existsSync } from "fs";
 import { createRequire } from "module";
 import os22 from "os";
 import path9 from "path";
 import { fileURLToPath } from "url";
 import { execFile as execFile22 } from "child_process";
-import { mkdir as mkdir4 } from "fs/promises";
+import { mkdir as mkdir5 } from "fs/promises";
 import { promisify as promisify22 } from "util";
-import { once } from "events";
 import fs2 from "fs/promises";
 import net from "net";
+import path10 from "path";
 import { existsSync as existsSync2 } from "fs";
+import { rm as rm2 } from "fs/promises";
 import os3 from "os";
-import path10 from "path";
+import path11 from "path";
 var DEFAULT_ACTIVE_STATES = ["Todo", "In Progress"];
 var DEFAULT_TERMINAL_STATES = ["Done", "Closed", "Canceled", "Cancelled", "Duplicate"];
 var trackerSchema = z5.object({
@@ -2405,6 +2450,50 @@ async function loadConfig(filePath) {
   }
   return { config, promptBody: wf.promptBody, filePath: wf.filePath };
 }
+var WORKFLOW_TEMPLATE = `---
+# Symphony workflow config. Edit as needed, then run:  symphony --port 4500
+# Full annotated reference: WORKFLOW.md.example (shipped next to this CLI) or
+# https://github.com/andrejvysny/symphony-ts/blob/master/WORKFLOW.md.example
+
+tracker:
+  kind: file
+  # Local JSON task store root (no database, no services). Defaults to ~/.symphony.
+  data_root: ~/.symphony
+  # Leave project_id unset to start with NO active project \u2014 open the dashboard and use
+  # "+ New project" to create or select one (the choice is written back here). There is no
+  # implicit default project.
+  # project_id: my-project
+
+workspace:
+  # single_dir (default): the agent works DIRECTLY in \`repo\` on its current branch, ONE task at a
+  # time, so tasks build on each other. worktree: isolate each ticket in its own git worktree.
+  mode: single_dir
+  # The project repo \u2014 a LOCAL git path. You can also set this per-project from the dashboard.
+  # repo: ~/code/your-repo
+
+agent:
+  backend: claude-sdk          # claude-sdk | claude-cli | codex-cli | opencode-cli
+  permission_mode: bypassPermissions
+  max_concurrent_agents: 5
+
+server:
+  port: 4500                   # dashboard at http://127.0.0.1:4500/
+---
+
+You have been assigned issue {{ issue.identifier }}: "{{ issue.title }}".
+
+<issue>
+Identifier: {{ issue.identifier }}
+Issue id (pass as task_id to the tracker tools): {{ issue.id }}
+Title: {{ issue.title }}
+{% if issue.priority %}Priority: {{ issue.priority }}
+{% endif %}{% if issue.labels.size > 0 %}Labels: {{ issue.labels | join: ", " }}
+{% endif %}Description:
+{% if issue.description %}{{ issue.description }}{% else %}(No description was provided. Treat the title as the specification; if it is too vague to implement safely, follow the blocked protocol.){% endif %}
+</issue>
+
+Implement this issue end to end: read it with tracker_get_task, move it to "In Progress" with a short plan comment, make the change, confirm the project's build/tests/lint pass, commit locally, then post an evidence-backed summary comment (with the verification output and commit SHA) and move the issue to "Human Review". Keep every change scoped to this issue.
+`;
 var noopLogger = {
   info: () => {
   },
@@ -2414,23 +2503,31 @@ var noopLogger = {
   },
   child: () => noopLogger
 };
+var MISSING_STAMP = { mtimeMs: 0, size: 0, hash: "" };
 var WorkflowStore = class {
-  constructor(filePath, logger = noopLogger, pollMs = 1e3) {
+  constructor(filePath, opts = {}) {
     this.filePath = filePath;
-    this.logger = logger;
-    this.pollMs = pollMs;
+    this.logger = opts.logger ?? noopLogger;
+    this.pollMs = opts.pollMs ?? 1e3;
+    this.allowMissing = opts.allowMissing ?? false;
   }
   filePath;
-  logger;
-  pollMs;
   current;
   stamp;
   timer;
   /** Raw (pre-resolution) front-matter from the last read — the basis for write-back. */
   rawFrontMatter = {};
   body = "";
-  /** Initial load — throws (fatal at startup) if the file is missing/invalid. */
+  logger;
+  pollMs;
+  allowMissing;
+  /** Initial load. Throws (fatal at startup) if the file is missing/invalid — unless `allowMissing`,
+   *  where a missing file loads defaults. */
   async load() {
+    return this.refresh();
+  }
+  /** Re-read from disk and replace the in-memory snapshot + stamp; returns the fresh snapshot. */
+  async refresh() {
     const { snapshot, stamp, raw, body } = await this.read();
     this.current = snapshot;
     this.stamp = stamp;
@@ -2438,6 +2535,10 @@ var WorkflowStore = class {
     this.body = body;
     return snapshot;
   }
+  /** Whether we hold in-memory defaults for a not-yet-created file (zero-config pre-create state). */
+  isMissingStamp() {
+    return this.stamp?.mtimeMs === 0 && this.stamp.size === 0;
+  }
   start() {
     if (this.timer) return;
     this.timer = setInterval(() => {
@@ -2473,17 +2574,32 @@ var WorkflowStore = class {
    * double-reload. Returns the new snapshot.
    */
   async persist(mutate) {
-    const raw = structuredClone(this.rawFrontMatter);
-    mutate(raw);
-    resolveConfig(parseConfig(raw), path42.dirname(path42.resolve(this.filePath)));
-    const content = serializeWorkflowFile(raw, this.body);
-    await writeFile2(path42.resolve(this.filePath), content, "utf8");
-    const { snapshot, stamp, raw: freshRaw, body } = await this.read();
-    this.current = snapshot;
-    this.stamp = stamp;
-    this.rawFrontMatter = freshRaw;
-    this.body = body;
-    return snapshot;
+    const abs = path42.resolve(this.filePath);
+    await mkdir2(path42.dirname(abs), { recursive: true });
+    if (this.isMissingStamp()) {
+      try {
+        await this.refresh();
+      } catch {
+      }
+    }
+    const apply = () => {
+      const raw = structuredClone(this.rawFrontMatter);
+      mutate(raw);
+      resolveConfig(parseConfig(raw), path42.dirname(abs));
+      return serializeWorkflowFile(raw, this.body);
+    };
+    if (this.isMissingStamp()) {
+      try {
+        await writeFile2(abs, apply(), { encoding: "utf8", flag: "wx" });
+      } catch (e) {
+        if (e.code !== "EEXIST") throw e;
+        await this.refresh();
+        await writeFile2(abs, apply(), "utf8");
+      }
+    } else {
+      await writeFile2(abs, apply(), "utf8");
+    }
+    return this.refresh();
   }
   async read() {
     const abs = path42.resolve(this.filePath);
@@ -2493,6 +2609,10 @@ var WorkflowStore = class {
       st = await stat(abs);
       content = await readFile22(abs, "utf8");
     } catch (e) {
+      if (this.allowMissing && e.code === "ENOENT") {
+        const config2 = resolveConfig(parseConfig({}), path42.dirname(abs));
+        return { snapshot: { config: config2, promptBody: "" }, stamp: MISSING_STAMP, raw: {}, body: "" };
+      }
       throw new ConfigError(`cannot read workflow file ${abs}: ${e.message}`);
     }
     const hash = createHash("sha1").update(content).digest("hex");
@@ -2511,12 +2631,14 @@ var WorkflowStore = class {
     try {
       st = await stat(abs);
     } catch (e) {
+      if (this.allowMissing && e.code === "ENOENT") return;
       this.logger.error({ error: String(e) }, "workflow file stat failed; keeping last config");
       return;
     }
     if (this.stamp && st.mtimeMs === this.stamp.mtimeMs && st.size === this.stamp.size) return;
     try {
       const { snapshot, stamp, raw, body } = await this.read();
+      if (stamp === MISSING_STAMP) return;
       if (this.stamp && stamp.hash === this.stamp.hash) {
         this.stamp = stamp;
         return;
@@ -2626,7 +2748,7 @@ async function exists(p) {
   }
 }
 async function ensureSharedClone(repo, root) {
-  await mkdir3(root, { recursive: true });
+  await mkdir22(root, { recursive: true });
   const dir = path5.join(root, SHARED_DIR_NAME);
   return withLock(dir, async () => {
     if (!await exists(path5.join(dir, ".git"))) {
@@ -2723,7 +2845,7 @@ var WorkspaceManager = class {
   /** Clone the shared repo once. Must be called before createForIssue. */
   async init() {
     if (!this.workspace.repo) throw new ConfigError("workspace.repo is required");
-    await mkdir2(this.workspace.root, { recursive: true });
+    await mkdir3(this.workspace.root, { recursive: true });
     this.shared = await ensureSharedClone(this.workspace.repo, this.workspace.root);
   }
   hookEnv(issue, wsPath, branch) {
@@ -2990,7 +3112,7 @@ async function runWorker(deps, ctx) {
       const persistLog = config.agent.persist_run_log !== false;
       const auditPath = path8.join(config.logs_root, issue.identifier, String(turn), "events.jsonl");
       if (persistLog)
-        await mkdir32(path8.dirname(auditPath), { recursive: true }).catch(() => void 0);
+        await mkdir4(path8.dirname(auditPath), { recursive: true }).catch(() => void 0);
       const runOpts = {
         prompt,
         cwd: ws.path,
@@ -4158,7 +4280,7 @@ async function runGit(args, cwd) {
   return stdout;
 }
 async function ensureGitRepo(repo) {
-  await mkdir4(repo, { recursive: true });
+  await mkdir5(repo, { recursive: true });
   let top;
   try {
     top = (await runGit(["rev-parse", "--show-toplevel"], repo)).trim();
@@ -4239,8 +4361,20 @@ var SingleDirWorkspaceManager = class {
 function dataRootOf(config) {
   return config.tracker.data_root ?? path9.join(os22.homedir(), ".symphony");
 }
+var SUN_PATH_MAX = process.platform === "darwin" ? 103 : 107;
+function dataRootKey(config) {
+  return createHash2("sha256").update(path9.resolve(dataRootOf(config))).digest("hex").slice(0, 16);
+}
 function trackerSocketPath(config) {
-  return path9.join(dataRootOf(config), "tracker.sock");
+  if (process.platform === "win32") return `\\\\.\\pipe\\symphony-tracker-${dataRootKey(config)}`;
+  const preferred = path9.join(dataRootOf(config), "tracker.sock");
+  if (Buffer.byteLength(preferred) <= SUN_PATH_MAX) return preferred;
+  const fallback = path9.join(os22.tmpdir(), `symphony-${dataRootKey(config)}.sock`);
+  if (Buffer.byteLength(fallback) > SUN_PATH_MAX)
+    throw new ConfigError(
+      `tracker socket path too long for this platform: even the ${os22.tmpdir()} fallback exceeds ${SUN_PATH_MAX} bytes. Set a shorter $TMPDIR or tracker.data_root.`
+    );
+  return fallback;
 }
 function hasActiveProject(config) {
   return config.tracker.kind !== "file" || !!config.tracker.project_id;
@@ -4317,9 +4451,40 @@ function buildMcpConfig(config) {
     }
   };
 }
+function errno(e) {
+  return typeof e === "object" && e !== null ? e.code : void 0;
+}
+function listen(server, socketPath) {
+  return new Promise((resolve, reject) => {
+    const onError = (e) => {
+      server.removeListener("listening", onListening);
+      reject(e);
+    };
+    const onListening = () => {
+      server.removeListener("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(socketPath);
+  });
+}
+function isSocketLive(socketPath) {
+  return new Promise((resolve) => {
+    const client = net.connect(socketPath);
+    const settle = (live) => {
+      client.destroy();
+      resolve(live);
+    };
+    client.once("connect", () => settle(true));
+    client.once("error", () => settle(false));
+  });
+}
 async function startTrackerBridge(opts) {
   const { socketPath, resolveTools } = opts;
-  await fs2.rm(socketPath, { force: true });
+  const isPipe = process.platform === "win32";
+  if (!isPipe)
+    await fs2.mkdir(path10.dirname(socketPath), { recursive: true });
   const dispatch = async (line, sock) => {
     let req;
     try {
@@ -4355,20 +4520,33 @@ async function startTrackerBridge(opts) {
     sock.on("error", () => {
     });
   });
-  server.listen(socketPath);
-  await once(server, "listening");
+  try {
+    await listen(server, socketPath);
+  } catch (e) {
+    if (errno(e) !== "EADDRINUSE") {
+      throw new Error(`tracker bridge: cannot listen on ${socketPath}: ${e.message}`);
+    }
+    if (!isPipe && !await isSocketLive(socketPath)) {
+      await fs2.rm(socketPath, { force: true });
+      await listen(server, socketPath);
+    } else {
+      throw new Error(
+        `tracker bridge: another Symphony instance is already running on ${socketPath} (same data_root). Stop it first, or use a different tracker.data_root.`
+      );
+    }
+  }
   return {
     socketPath,
     async close() {
       await new Promise((resolve) => server.close(() => resolve()));
-      await fs2.rm(socketPath, { force: true });
+      if (!isPipe) await fs2.rm(socketPath, { force: true });
     }
   };
 }
 function expandHome(p) {
   if (!p) return null;
   if (p === "~") return os3.homedir();
-  if (p.startsWith("~/")) return path10.join(os3.homedir(), p.slice(2));
+  if (p.startsWith("~/")) return path11.join(os3.homedir(), p.slice(2));
   return p;
 }
 function activeProjectId(cfg) {
@@ -4503,25 +4681,35 @@ function buildDashboardSource(orchestrator, store, opts = {}) {
       const base = slugify(input.name);
       let key = base;
       for (let n = 2; taken.has(key); n++) key = `${base}-${n}`;
-      await scaffoldProject({
-        dataRoot,
-        projectKey: key,
-        seed: {
-          identifier: input.identifier,
-          states: seedStates(t.backlog_state, t.active_states, t.review_state, t.terminal_states)
-        }
-      });
       const entry = {
         name: input.name,
         project_id: key,
         repo: input.repo,
         identifier: input.identifier
       };
-      const snap = await st.persist((raw) => {
+      const mutate = (raw) => {
         const list = Array.isArray(raw["projects"]) ? raw["projects"] : [];
         list.push(entry);
         raw["projects"] = list;
+      };
+      st.composeConfig(mutate);
+      await scaffoldProject({
+        dataRoot,
+        projectKey: key,
+        seed: {
+          identifier: input.identifier,
+          states: seedStates(t.backlog_state, t.active_states, t.review_state, t.terminal_states)
+        }
       });
+      let snap;
+      try {
+        snap = await st.persist(mutate);
+      } catch (e) {
+        await rm2(path11.join(dataRoot, "projects", key), { recursive: true, force: true }).catch(
+          () => void 0
+        );
+        throw e;
+      }
       orchestrator.applyConfig(snap.config);
       return {
         project_id: key,
@@ -4695,7 +4883,7 @@ function buildDashboardSource(orchestrator, store, opts = {}) {
       if (!issue) return null;
       const [activity2, comments] = supportsActivity(tracker) ? await Promise.all([tracker.fetchActivity(id), tracker.fetchComments(id)]) : [[], []];
       const wcfg = orchestrator.currentConfig().workspace;
-      const worktree = wcfg.mode === "single_dir" ? wcfg.repo ?? null : path10.join(wcfg.root, sanitizeIdentifier(issue.identifier));
+      const worktree = wcfg.mode === "single_dir" ? wcfg.repo ?? null : path11.join(wcfg.root, sanitizeIdentifier(issue.identifier));
       const snap = orchestrator.snapshot();
       const live = snap.running.find((r) => r.issue_id === issue.id)?.tokens;
       const persisted = issue.usage;
@@ -4811,19 +4999,19 @@ function buildDashboardSource(orchestrator, store, opts = {}) {
       if (t.kind !== "file" || !t.data_root) return null;
       if (projectKey.includes("/") || projectKey.includes("\\") || projectKey.includes(".."))
         return null;
-      const base = path10.join(t.data_root, "projects", projectKey, "uploads");
-      const abs = path10.resolve(base, rest);
-      const rel = path10.relative(base, abs);
-      if (rel.startsWith("..") || path10.isAbsolute(rel)) return null;
+      const base = path11.join(t.data_root, "projects", projectKey, "uploads");
+      const abs = path11.resolve(base, rest);
+      const rel = path11.relative(base, abs);
+      if (rel.startsWith("..") || path11.isAbsolute(rel)) return null;
       return abs;
     }
   };
 }
-var CORE_VERSION = "0.1.0";
+var CORE_VERSION = "0.1.2";
 
 // ../dashboard/dist/index.js
 import { createReadStream, existsSync as existsSync3 } from "fs";
-import path11 from "path";
+import path12 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import multipart from "@fastify/multipart";
 import fastifyStatic from "@fastify/static";
@@ -5106,7 +5294,11 @@ function createDashboardServer(source) {
     if (fields["description"]) input.description = fields["description"];
     if (fields["stateId"]) input.stateId = fields["stateId"];
     if (fields["model"]) input.model = fields["model"];
-    if (isEffort(fields["effort"])) input.effort = fields["effort"];
+    if (fields["effort"] !== void 0 && fields["effort"] !== "") {
+      if (!isEffort(fields["effort"]))
+        return reply.code(400).send({ error: { code: "invalid_effort" } });
+      input.effort = fields["effort"];
+    }
     try {
       const created = await source.createTicket(input);
       return reply.code(201).send(created);
@@ -5142,7 +5334,11 @@ function createDashboardServer(source) {
       if (b.priority === null || typeof b.priority === "number") edit.priority = b.priority;
       if (Array.isArray(b.labels)) edit.labels = b.labels.filter((l) => typeof l === "string");
       if (b.model === null || typeof b.model === "string") edit.model = b.model;
-      if (b.effort === null || isEffort(b.effort)) edit.effort = b.effort;
+      if (b.effort !== void 0) {
+        if (b.effort !== null && !isEffort(b.effort))
+          return reply.code(400).send({ error: { code: "invalid_effort" } });
+        edit.effort = b.effort;
+      }
       if (Object.keys(edit).length === 0) {
         return reply.code(400).send({ error: { code: "empty_edit" } });
       }
@@ -5239,7 +5435,15 @@ function createDashboardServer(source) {
 
 `);
     });
-    req.raw.on("close", unsubscribe);
+    const ping = setInterval(() => reply.raw.write(": ping\n\n"), 2e4);
+    let cleaned = false;
+    const cleanup = () => {
+      if (cleaned) return;
+      cleaned = true;
+      clearInterval(ping);
+      unsubscribe();
+    };
+    req.raw.on("close", cleanup);
   });
   app.get("/api/v1/events", (req, reply) => {
     reply.hijack();
@@ -5284,7 +5488,7 @@ function createDashboardServer(source) {
       const abs = source.resolveUpload(req.params.projectKey, req.params["*"]);
       if (!abs || !existsSync3(abs))
         return reply.code(404).send({ error: { code: "upload_not_found" } });
-      const type = UPLOAD_CONTENT_TYPES[path11.extname(abs).toLowerCase()] ?? "application/octet-stream";
+      const type = UPLOAD_CONTENT_TYPES[path12.extname(abs).toLowerCase()] ?? "application/octet-stream";
       return reply.type(type).send(createReadStream(abs));
     }
   );
@@ -5321,6 +5525,8 @@ function parseArgs(argv) {
       } else {
         flags.set(key, true);
       }
+    } else if (/^-[a-zA-Z]$/.test(a)) {
+      flags.set(a.slice(1), true);
     } else {
       positionals.push(a);
     }
@@ -5329,10 +5535,32 @@ function parseArgs(argv) {
 }
 function workflowPath(args) {
   const explicit = args.flags.get("workflow");
-  if (typeof explicit === "string") return path12.resolve(explicit);
+  if (typeof explicit === "string") return path13.resolve(explicit);
   const firstPositional = args.positionals[0];
-  if (firstPositional && firstPositional.endsWith(".md")) return path12.resolve(firstPositional);
-  return path12.resolve("WORKFLOW.md");
+  if (firstPositional && firstPositional.endsWith(".md")) return path13.resolve(firstPositional);
+  return path13.resolve("WORKFLOW.md");
+}
+async function runInit(args) {
+  const explicit = args.flags.get("workflow");
+  const positional = args.positionals[1];
+  const target = path13.resolve(
+    typeof explicit === "string" ? explicit : positional ?? "WORKFLOW.md"
+  );
+  if (existsSync4(target) && !args.flags.has("force")) {
+    process.stderr.write(`symphony: ${target} already exists (use --force to overwrite)
+`);
+    process.exitCode = 1;
+    return;
+  }
+  await writeFile3(target, WORKFLOW_TEMPLATE, "utf8");
+  process.stdout.write(
+    `created ${target}
+
+Next: edit it if you like, then run:
+  symphony --port 4500
+Open http://127.0.0.1:4500/ and use "+ New project" to point Symphony at a git repo.
+`
+  );
 }
 async function runTicketCreate(args) {
   const title = args.positionals[2];
@@ -5343,7 +5571,17 @@ async function runTicketCreate(args) {
     process.exitCode = 1;
     return;
   }
-  const { config } = await loadConfig(workflowPath(args));
+  const wf = workflowPath(args);
+  if (!existsSync4(wf)) {
+    process.stderr.write(
+      `symphony: no WORKFLOW.md at ${wf}
+Run \`symphony init\` to create one, then \`symphony --port 4500\` and create a project in the dashboard before adding tickets.
+`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const { config } = await loadConfig(wf);
   const tracker = buildTracker(config);
   if (!supportsIssueCreation(tracker)) {
     process.stderr.write(`tracker "${tracker.kind}" does not support issue creation
@@ -5367,10 +5605,16 @@ var activeLogger;
 async function runOrchestrator(args) {
   const logger = createLogger({ pretty: !args.flags.has("json-logs") });
   activeLogger = logger;
-  const store = new WorkflowStore(workflowPath(args), logger);
+  const wf = workflowPath(args);
+  const store = new WorkflowStore(wf, { logger, allowMissing: true });
+  if (!existsSync4(wf))
+    logger.info(
+      {},
+      "no WORKFLOW.md found \u2014 running with defaults; create a project in the dashboard, or run `symphony init`"
+    );
   const { config, promptBody } = await store.load();
   const logsRootFlag = args.flags.get("logs-root");
-  if (typeof logsRootFlag === "string") config.logs_root = path12.resolve(logsRootFlag);
+  if (typeof logsRootFlag === "string") config.logs_root = path13.resolve(logsRootFlag);
   store.start();
   logger.info(
     { tracker: config.tracker.kind, backend: config.agent.backend },
@@ -5413,8 +5657,10 @@ async function runOrchestrator(args) {
   }
   const portFlag = args.flags.get("port");
   const port = typeof portFlag === "string" ? Number(portFlag) : config.server?.port ?? void 0;
+  if (typeof portFlag === "string" && !(Number.isInteger(port) && port >= 0 && port <= 65535))
+    logger.warn({ port: portFlag }, "ignoring invalid --port (expected an integer 0\u201365535)");
   let dashboard;
-  if (port !== void 0 && Number.isFinite(port)) {
+  if (port !== void 0 && Number.isInteger(port) && port >= 0 && port <= 65535) {
     dashboard = await startDashboard(buildDashboardSource(orchestrator, store), {
       port,
       host: config.server?.host ?? "127.0.0.1",
@@ -5449,6 +5695,7 @@ async function runOrchestrator(args) {
 var HELP = `symphony ${CORE_VERSION} \u2014 agent-agnostic coding-agent orchestrator
 
 Usage:
+  symphony init [path] [--force]                      Write a starter WORKFLOW.md
   symphony [WORKFLOW.md] [--port <n>] [--json-logs]   Run the orchestrator
   symphony ticket create "<title>" [--desc <t>] [--state <s>] [--priority <n>]
   symphony --version
@@ -5461,7 +5708,9 @@ Options:
   --version, -v   Print version
   --help, -h      Show this help
 
-Workflow file: see WORKFLOW.md.example. Agent auth uses your local \`claude\` login.
+Quick start: \`symphony init\` then \`symphony --port 4500\`. With no WORKFLOW.md, the
+orchestrator runs with defaults and the dashboard prompts you to create a project.
+Agent auth uses your local \`claude\` login.
 `;
 async function main(argv) {
   const args = parseArgs(argv);
@@ -5474,6 +5723,10 @@ async function main(argv) {
 `);
     return;
   }
+  if (args.positionals[0] === "init") {
+    await runInit(args);
+    return;
+  }
   if (args.positionals[0] === "ticket" && args.positionals[1] === "create") {
     await runTicketCreate(args);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrejvysny/symphony",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agent-agnostic coding-agent orchestrator — delegate tickets to local coding agents (Claude Code, codex, opencode) in isolated git worktrees, driven by a local file task store.",
   "keywords": [
     "claude",
@@ -24,7 +24,7 @@
   },
   "type": "module",
   "bin": {
-    "symphony": "./dist/main.js"
+    "symphony": "dist/cli.js"
   },
   "files": [
     "dist"