@phren/cli 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/dist/bridge/agent-hooks.d.ts +20 -6
  2. package/dist/bridge/agent-hooks.js +74 -24
  3. package/dist/bridge/claude-question-dialog.d.ts +65 -0
  4. package/dist/bridge/claude-question-dialog.js +210 -0
  5. package/dist/bridge/command.d.ts +3 -2
  6. package/dist/bridge/command.js +97 -5
  7. package/dist/bridge/computers.d.ts +5 -0
  8. package/dist/bridge/computers.js +10 -4
  9. package/dist/bridge/conductor-group.d.ts +23 -0
  10. package/dist/bridge/conductor-group.js +25 -0
  11. package/dist/bridge/hand-off.js +5 -1
  12. package/dist/bridge/herdr.d.ts +7 -0
  13. package/dist/bridge/herdr.js +53 -2
  14. package/dist/bridge/link.d.ts +48 -0
  15. package/dist/bridge/link.js +136 -0
  16. package/dist/bridge/memory-store.d.ts +23 -0
  17. package/dist/bridge/memory-store.js +152 -0
  18. package/dist/bridge/pair.d.ts +46 -0
  19. package/dist/bridge/pair.js +240 -0
  20. package/dist/bridge/peers.d.ts +9 -0
  21. package/dist/bridge/peers.js +25 -2
  22. package/dist/bridge/push.d.ts +42 -3
  23. package/dist/bridge/push.js +90 -20
  24. package/dist/bridge/server-launch.d.ts +9 -0
  25. package/dist/bridge/server-launch.js +34 -11
  26. package/dist/bridge/server-pane-routes.js +45 -8
  27. package/dist/bridge/server-routes.d.ts +1 -0
  28. package/dist/bridge/server-routes.js +11 -3
  29. package/dist/bridge/server-stream.js +4 -1
  30. package/dist/bridge/speech-key.d.ts +33 -0
  31. package/dist/bridge/speech-key.js +106 -0
  32. package/dist/bridge/speech-transcribe.js +1 -1
  33. package/dist/bridge/speech.d.ts +7 -3
  34. package/dist/bridge/speech.js +36 -17
  35. package/dist/bridge-hook.mjs +1356 -514
  36. package/dist/cli/namespaces-store.js +21 -0
  37. package/dist/cli-handlers.js +6 -0
  38. package/dist/cli-registry.js +14 -2
  39. package/dist/content/learning.js +1 -1
  40. package/dist/data/tasks.d.ts +26 -0
  41. package/dist/data/tasks.js +72 -1
  42. package/dist/entrypoint.js +7 -0
  43. package/dist/governance/rbac.d.ts +1 -1
  44. package/dist/governance/rbac.js +1 -0
  45. package/dist/init/init-walkthrough.d.ts +10 -0
  46. package/dist/init/init-walkthrough.js +25 -2
  47. package/dist/init/init.d.ts +5 -0
  48. package/dist/init/init.js +54 -32
  49. package/dist/link/doctor.js +10 -0
  50. package/dist/link/link.js +9 -3
  51. package/dist/link/refresh.js +11 -10
  52. package/dist/mcp/profile.js +2 -1
  53. package/dist/modules/config.d.ts +7 -0
  54. package/dist/modules/config.js +17 -0
  55. package/dist/modules/registry.js +5 -4
  56. package/dist/sync/conflict-resolve.d.ts +1 -1
  57. package/dist/sync/conflict-resolve.js +44 -7
  58. package/dist/sync/task-claim.d.ts +22 -0
  59. package/dist/sync/task-claim.js +45 -0
  60. package/dist/tools/dispatch.js +2 -2
  61. package/dist/tools/search.js +1 -1
  62. package/dist/tools/tasks.js +40 -1
  63. package/package.json +2 -1
  64. package/starter/global/skills/conductor/SKILL.md +41 -9
@@ -62,9 +62,10 @@ const COMPOSITES = {
62
62
  },
63
63
  manage_task: {
64
64
  title: "◆ phren · manage task",
65
- summary: "Change an existing task: complete, update, remove, pin, or tidy the done list. Pass `action` plus that action's own parameters.",
65
+ summary: "Change an existing task: complete, update, remove, pin, claim for this computer, or tidy the done list. Pass `action` plus that action's own parameters.",
66
66
  actions: {
67
67
  complete: "complete_task",
68
+ claim: "claim_task",
68
69
  update: "update_task",
69
70
  remove: "remove_task",
70
71
  pin: "pin_task",
@@ -2,3 +2,10 @@ export declare function setModuleEnabled(store: string, name: string, value: boo
2
2
  /** Freeze legacy surfaces before runtime defaults can change an existing install. */
3
3
  export declare function migrateModules(store: string, hookInstalled?: boolean): void;
4
4
  export declare function initializeModules(store: string): void;
5
+ /**
6
+ * `phren pair` and `phren bridge install` are how a person asks for the Hook,
7
+ * so they turn its module on instead of refusing. Returns true when this
8
+ * call enabled it. Without a store there is nothing to record; the Hook's
9
+ * legacy default already allows it there.
10
+ */
11
+ export declare function enableHookForPhone(store: string): boolean;
@@ -68,3 +68,20 @@ export function initializeModules(store) {
68
68
  atomicWriteText(file, yaml.dump({ version: 1, enabled: Object.fromEntries(BUILTIN_MODULES.map(module => [module.name, module.defaultEnabled])) }, { noRefs: true }));
69
69
  });
70
70
  }
71
+ /**
72
+ * `phren pair` and `phren bridge install` are how a person asks for the Hook,
73
+ * so they turn its module on instead of refusing. Returns true when this
74
+ * call enabled it. Without a store there is nothing to record; the Hook's
75
+ * legacy default already allows it there.
76
+ */
77
+ export function enableHookForPhone(store) {
78
+ const hasStore = !!readConfig(store) || fs.existsSync(path.join(store, "phren.root.yaml")) || fs.existsSync(installPreferencesFile(store));
79
+ if (!hasStore)
80
+ return false;
81
+ const config = readConfig(store);
82
+ if (config?.enabled?.hook === true)
83
+ return false;
84
+ migrateModules(store);
85
+ setModuleEnabled(store, "hook", true);
86
+ return true;
87
+ }
@@ -40,7 +40,8 @@ export const BUILTIN_MODULES = [
40
40
  { agents: ["claude", "codex", "copilot", "cursor"], events: ["Stop"], handler: "phren hook-stop" },
41
41
  { agents: ["claude"], events: ["PostToolUse"], handler: "phren hook-tool" },
42
42
  ],
43
- hookRoutes: [], capabilities: ["memory"],
43
+ hookRoutes: [...routes("GET", ["/v1/store/head", "/v1/store/tree", "/v1/store/blob"]), ...routes("POST", ["/v1/store/file", "/v1/store/delete"])],
44
+ capabilities: ["memory", "memoryStore"],
44
45
  storeFiles: [
45
46
  "phren.root.yaml", "machines.yaml", "profiles/*.yaml", ".config/modules.yaml", ".config/*.json",
46
47
  "<project>/AGENTS.md", "<project>/summary.md", "<project>/FINDINGS.md", "<project>/truths.md",
@@ -56,7 +57,7 @@ export const BUILTIN_MODULES = [
56
57
  schemaVersion: 1, name: "tasks", version: VERSION, defaultEnabled: false, requires: ["memory"],
57
58
  tools: [
58
59
  ...core(["get_tasks", "add_task", "manage_task"]),
59
- ...full(["complete_task", "remove_task", "update_task", "tidy_done_tasks", "pin_task"]),
60
+ ...full(["complete_task", "remove_task", "update_task", "tidy_done_tasks", "pin_task", "claim_task"]),
60
61
  ],
61
62
  cliCommands: ["task", "tasks", "config task-mode", "config proactivity.tasks"], agentHooks: [], hookRoutes: [], capabilities: ["tasks"],
62
63
  storeFiles: ["<project>/tasks.md", ".sessions/checkpoint-*.json"], localFiles: [],
@@ -67,7 +68,7 @@ export const BUILTIN_MODULES = [
67
68
  tools: [],
68
69
  cliCommands: [
69
70
  "bridge", "bridge install", "bridge update", "bridge uninstall", "bridge rollback", "bridge status",
70
- "bridge doctor", "bridge usage", "bridge usage-statusline", "bridge hook", "bridge serve", "bridge ssh",
71
+ "bridge doctor", "bridge usage", "bridge usage-statusline", "bridge hook", "bridge serve", "bridge ssh", "pair",
71
72
  "bridge fanouts archive", "canary",
72
73
  ],
73
74
  agentHooks: [
@@ -127,7 +128,7 @@ export const BUILTIN_MODULES = [
127
128
  {
128
129
  schemaVersion: 1, name: "conductor", version: VERSION, defaultEnabled: false, requires: ["memory", "hook"],
129
130
  tools: full(["dispatch", "dispatch_returns", "hand_off", "live_sessions"]), cliCommands: ["dispatch", "dispatch status", "dispatch returns", "dispatch sessions", "hand-off", "conductor", "conductor grants", "bridge enroll-computer"], agentHooks: [],
130
- hookRoutes: [...routes("GET", ["/v1/dispatch", "/v1/dispatch/capacity", "/v1/conductor/grants"]),
131
+ hookRoutes: [...routes("GET", ["/v1/dispatch", "/v1/dispatch/capacity", "/v1/conductor", "/v1/conductor/grants"]),
131
132
  ...routes("POST", ["/v1/dispatch", "/v1/dispatch/workers", "/v1/dispatch/returns", "/v1/conductor/grants"]), ...routes("DELETE", ["/v1/conductor/grants"])],
132
133
  capabilities: ["dispatch"], storeFiles: ["global/skills/conductor/**"],
133
134
  localFiles: ["<bridge>/hooks.yaml", "<bridge>/conductor.yaml", "<bridge>/dispatches/*.json"], phoneScreens: [], skills: ["conductor"],
@@ -2,7 +2,7 @@ export interface ConflictResolution {
2
2
  resolved: string[];
3
3
  unresolved: string[];
4
4
  }
5
- type Strategy = "tasks" | "findings" | "archive" | "topic" | "summary" | null;
5
+ type Strategy = "tasks" | "findings" | "archive" | "topic" | "summary" | "union" | null;
6
6
  export declare function conflictStrategy(relFile: string): Strategy;
7
7
  /** Resolves what it can in the store's in-progress merge and stages it. */
8
8
  export declare function resolveStoreConflicts(cwd: string): ConflictResolution;
@@ -1,8 +1,14 @@
1
1
  /**
2
2
  * Resolves the content conflicts a store merge can settle without a person:
3
- * tasks.md per task id against the merge base, generated blocks from the
4
- * incoming side, and the record-oriented files that already union-merge.
5
- * Everything else stays conflicted so the caller aborts and names it.
3
+ * tasks.md per task id against the merge base, generated summaries from the
4
+ * incoming side, and the append-only record files (findings, notes, journal,
5
+ * review queue, topic archives) as a union of both sides. Everything else
6
+ * stays conflicted so the caller aborts and names it.
7
+ *
8
+ * Any file left unresolved aborts the whole merge, and every later auto-save
9
+ * then commits locally and fails to push, so a store drifts further from its
10
+ * remote each session. Every file phren itself writes during normal use needs
11
+ * a strategy here.
6
12
  */
7
13
  import { execFileSync, spawnSync } from "child_process";
8
14
  import * as crypto from "crypto";
@@ -29,6 +35,10 @@ export function conflictStrategy(relFile) {
29
35
  return "topic";
30
36
  if (name === "summary.md")
31
37
  return "summary";
38
+ if (name === "review.md")
39
+ return "union";
40
+ if (/(^|\/)(notes|journal)\/[^/]+\.md$/i.test(file))
41
+ return "union";
32
42
  return null;
33
43
  }
34
44
  function git(cwd, args) {
@@ -71,15 +81,38 @@ function mergeText(base, ours, theirs) {
71
81
  fs.rmSync(dir, { recursive: true, force: true });
72
82
  }
73
83
  }
84
+ /**
85
+ * A line-level three-way merge that keeps both sides of a conflicting hunk,
86
+ * local lines first (`git merge-file --union`). For append-only records two
87
+ * machines adding entries at the same spot is not a real conflict.
88
+ */
89
+ function unionText(base, ours, theirs) {
90
+ const clean = mergeText(base, ours, theirs);
91
+ if (clean !== null)
92
+ return clean;
93
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "phren-merge-"));
94
+ try {
95
+ const [o, b, t] = ["ours", "base", "theirs"].map((name) => path.join(dir, name));
96
+ fs.writeFileSync(o, ours);
97
+ fs.writeFileSync(b, base);
98
+ fs.writeFileSync(t, theirs);
99
+ const result = spawnSync("git", ["merge-file", "--union", "-p", o, b, t], { encoding: "utf8", env: nonInteractiveGitEnv(), timeout: EXEC_TIMEOUT_MS });
100
+ return result.status === 0 ? result.stdout : null;
101
+ }
102
+ finally {
103
+ fs.rmSync(dir, { recursive: true, force: true });
104
+ }
105
+ }
74
106
  /**
75
107
  * Generated blocks regenerate, so the incoming block wins; the rest of the
76
- * file must still merge line by line.
108
+ * file merges with `merge`: a union of both sides by default (a topic
109
+ * archive's bullets).
77
110
  */
78
- function mergeWithGeneratedBlock(base, ours, theirs, start, end, where) {
111
+ function mergeWithGeneratedBlock(base, ours, theirs, start, end, where, merge = unionText) {
79
112
  const b = splitBlock(base, start, end);
80
113
  const o = splitBlock(ours, start, end);
81
114
  const t = splitBlock(theirs, start, end);
82
- const rest = mergeText(b.rest, o.rest, t.rest);
115
+ const rest = merge(b.rest, o.rest, t.rest);
83
116
  if (rest === null)
84
117
  return null;
85
118
  const block = t.block ?? o.block;
@@ -94,7 +127,11 @@ function resolveContent(strategy, base, ours, theirs) {
94
127
  // Archived tasks only accumulate: keep both sides, the incoming version of any duplicate.
95
128
  case "archive": return mergeTask(theirs, ours);
96
129
  case "topic": return mergeWithGeneratedBlock(base, ours, theirs, NOW_START, NOW_END, "top");
97
- case "summary": return mergeWithGeneratedBlock(base, ours, theirs, KNOWS_START, KNOWS_END, "bottom");
130
+ // Summaries are regenerated from the store: when the hand-written part
131
+ // doesn't merge cleanly, take the incoming file whole and let the next
132
+ // summarize pass fold in anything only this machine had.
133
+ case "summary": return mergeWithGeneratedBlock(base, ours, theirs, KNOWS_START, KNOWS_END, "bottom", mergeText) ?? theirs;
134
+ case "union": return unionText(base, ours, theirs);
98
135
  }
99
136
  }
100
137
  /** Resolves what it can in the store's in-progress merge and stages it. */
@@ -0,0 +1,22 @@
1
+ import { type TaskClaim, type TaskItem } from "../data/tasks.js";
2
+ export interface ClaimOutcome {
3
+ /** True when this computer holds the claim after syncing; false after a release. */
4
+ claimed: boolean;
5
+ item?: TaskItem;
6
+ /** The claim that won when another computer's reached the remote first. */
7
+ heldBy?: TaskClaim;
8
+ /** False when the claim could not reach the store's remote. */
9
+ synced: boolean;
10
+ detail: string;
11
+ error?: string;
12
+ }
13
+ /**
14
+ * Claims a task across unlinked conductors: pull the store so a claim already
15
+ * pushed elsewhere refuses this one, write the claim, then commit and push.
16
+ * When another computer's claim reached the remote first, the store merge
17
+ * keeps theirs, so the task is read again after the push to see who won.
18
+ */
19
+ export declare function claimTaskSynced(phrenPath: string, project: string, match: string, claim: TaskClaim, opts?: {
20
+ release?: boolean;
21
+ force?: boolean;
22
+ }): Promise<ClaimOutcome>;
@@ -0,0 +1,45 @@
1
+ import { runBestEffortGit } from "../cli/session-git.js";
2
+ import { claimTask, resolveTaskItem } from "../data/tasks.js";
3
+ import { withFileLock } from "../governance/locks.js";
4
+ import { runtimeFile } from "../phren-paths.js";
5
+ import { mergeStoreUpstream } from "./store-merge.js";
6
+ const git = async (cwd, args) => {
7
+ const result = await runBestEffortGit(args, cwd);
8
+ return { ok: result.ok, output: result.output ?? "", error: result.error };
9
+ };
10
+ /**
11
+ * Claims a task across unlinked conductors: pull the store so a claim already
12
+ * pushed elsewhere refuses this one, write the claim, then commit and push.
13
+ * When another computer's claim reached the remote first, the store merge
14
+ * keeps theirs, so the task is read again after the push to see who won.
15
+ */
16
+ export async function claimTaskSynced(phrenPath, project, match, claim, opts = {}) {
17
+ return withFileLock(runtimeFile(phrenPath, "git-op"), async () => {
18
+ const pulled = await mergeStoreUpstream(phrenPath, { git, commitMessage: "auto-save phren (task claim)" });
19
+ const offline = pulled.status === "error" || pulled.status === "busy" ? pulled.detail : undefined;
20
+ const written = claimTask(phrenPath, project, match, claim, opts);
21
+ if (!written.ok)
22
+ return { claimed: false, synced: !offline, detail: offline ?? "", error: written.error };
23
+ const bid = written.data.stableId ?? match;
24
+ const verb = opts.release ? "releases" : "claims";
25
+ const saved = await mergeStoreUpstream(phrenPath, { git, commitMessage: `phren: ${claim.computer} ${verb} ${project} task ${bid}` });
26
+ if (offline || saved.status === "error" || saved.status === "busy") {
27
+ return { claimed: !opts.release, item: written.data, synced: false, detail: `The change is written on this computer but not synced: ${offline ?? saved.detail}` };
28
+ }
29
+ if (/no tracking remote/i.test(saved.detail)) {
30
+ return { claimed: !opts.release, item: written.data, synced: false, detail: "The store has no remote, so the change is only on this computer." };
31
+ }
32
+ let pushed = await git(phrenPath, ["push", "--quiet"]);
33
+ if (!pushed.ok) {
34
+ const merged = await mergeStoreUpstream(phrenPath, { git, commitLocalWrites: false });
35
+ pushed = merged.status === "updated" || merged.status === "unchanged" ? await git(phrenPath, ["push", "--quiet"]) : { ok: false, output: "", error: merged.detail };
36
+ }
37
+ const current = resolveTaskItem(phrenPath, project, bid);
38
+ const now = current.ok ? current.data : undefined;
39
+ if (!opts.release && now?.claim && now.claim.computer !== claim.computer) {
40
+ return { claimed: false, item: now, heldBy: now.claim, synced: pushed.ok, detail: `${now.claim.computer} claimed this task first.` };
41
+ }
42
+ return { claimed: !opts.release, item: now ?? written.data, synced: pushed.ok,
43
+ detail: pushed.ok ? "Pushed to the store's remote." : `Committed but not pushed: ${pushed.error ?? "push failed"}` };
44
+ });
45
+ }
@@ -41,9 +41,9 @@ export function register(server) {
41
41
  try {
42
42
  const result = await listLiveSessions();
43
43
  const note = result.peerError ? ` Enrolled computers were skipped: ${result.peerError}`
44
- : result.enrolled === 0 && !result.notLinked.length ? " No other computers are enrolled here; run `phren bridge enroll-computer` to add them." : "";
44
+ : result.enrolled === 0 && !result.notLinked.length ? " No other computers are linked here; `phren bridge discover` lists the ones you already reach over ssh, and `phren bridge link <host>` links one." : "";
45
45
  const unlinked = result.notLinked.length
46
- ? ` Not linked, so not checked (this does not mean nothing is running there): ${result.notLinked.map(item => item.aliases?.length ? `${item.name} (also ${item.aliases.join(", ")})` : item.name).join("; ")}. Link one with \`phren bridge enroll-computer\`.` : "";
46
+ ? ` Not linked, so not checked (this does not mean nothing is running there): ${result.notLinked.map(item => item.aliases?.length ? `${item.name} (also ${item.aliases.join(", ")})` : item.name).join("; ")}. If you reach one over ssh, the owner can link it with \`phren bridge link <host>\`; never link a computer without the owner asking.` : "";
47
47
  return mcpResponse({ ok: true, data: result, message: `${result.sessions.length} live sessions across ${result.enrolled + 1} computers.${note}${unlinked}` });
48
48
  }
49
49
  catch (error) {
@@ -698,7 +698,7 @@ async function handleGetFindings(ctx, { project, limit, include_superseded, incl
698
698
  if (entry.scope)
699
699
  metadata.push(`scope=${entry.scope}`);
700
700
  if (entry.symbol)
701
- metadata.push(`symbol=${entry.symbol}`);
701
+ metadata.push(`name=${entry.symbol}`);
702
702
  if (entry.supersedes)
703
703
  metadata.push(`supersedes="${entry.supersedes.slice(0, 30)}"`);
704
704
  if (entry.supersededBy)
@@ -10,6 +10,8 @@ import { clearTaskCheckpoint } from "../session/checkpoints.js";
10
10
  import { incrementSessionTasksCompleted } from "./session.js";
11
11
  import { normalizeMemoryScope } from "../shared.js";
12
12
  import { permissionDeniedError } from "../governance/rbac.js";
13
+ import { getMachineName } from "../machine-identity.js";
14
+ import { claimTaskSynced } from "../sync/task-claim.js";
13
15
  const TASK_SECTION_ORDER = ["Active", "Queue", "Done"];
14
16
  const DEFAULT_TASK_LIMIT = 20;
15
17
  /** Done items are historical — cap tightly by default to avoid large responses. */
@@ -80,7 +82,8 @@ function buildTaskSummary(doc, includedSections) {
80
82
  const prio = item.priority ? ` [${item.priority}]` : "";
81
83
  const bidPrefix = item.stableId ? `bid:${item.stableId} ` : "";
82
84
  const githubTag = item.githubIssue ? ` [gh:#${item.githubIssue}]` : item.githubUrl ? " [gh]" : "";
83
- lines.push(` - ${bidPrefix}${item.line.slice(0, 80)}${item.line.length > 80 ? "\u2026" : ""}${prio}${githubTag}`);
85
+ const claimTag = item.claim ? ` [claimed: ${item.claim.computer}]` : "";
86
+ lines.push(` - ${bidPrefix}${item.line.slice(0, 80)}${item.line.length > 80 ? "\u2026" : ""}${prio}${githubTag}${claimTag}`);
84
87
  }
85
88
  if (items.length > 3)
86
89
  lines.push(` ... and ${items.length - 3} more`);
@@ -548,6 +551,42 @@ export function register(server, ctx) {
548
551
  return mcpResponse({ ok: true, message: result.data, data: { project, keep: keep ?? 30, dryRun: dry_run ?? false } });
549
552
  });
550
553
  });
554
+ server.registerTool("claim_task", {
555
+ title: "◆ phren · claim task",
556
+ description: "Claim a task for this computer so conductors that are not linked do not take the same work: " +
557
+ "syncs the store, moves the task to Active with a `Claimed:` line naming this computer, then commits and pushes. " +
558
+ "Refuses a task another computer holds. With release, clears this computer's claim and returns the task to the Queue. " +
559
+ "Conductors skip tasks claimed by other computers.",
560
+ inputSchema: z.object({
561
+ project: z.string().describe("Project name."),
562
+ item: z.string().describe("Task to claim: bid:XXXXXXXX, a positional ID (Q3) or its text."),
563
+ session: z.string().regex(/^[A-Za-z0-9._:-]{1,128}$/).optional().describe("The claiming conductor's session id, recorded with the claim."),
564
+ release: z.boolean().optional().describe("Release this computer's claim instead of taking one."),
565
+ force: z.boolean().optional().describe("Take over another computer's claim once it is more than a day old."),
566
+ }),
567
+ }, async ({ project: projectInput, item, session, release, force }) => {
568
+ const resolved = resolveStoreForProject(ctx, projectInput);
569
+ const project = resolved.project;
570
+ const targetPath = resolved.phrenPath;
571
+ if (!isValidProjectName(project))
572
+ return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
573
+ const denied = permissionDeniedError(targetPath, "claim_task", project);
574
+ if (denied)
575
+ return mcpResponse({ ok: false, error: denied });
576
+ return withWriteQueue(async () => {
577
+ // The Claimed line takes a plain token; a name with spaces would never parse back.
578
+ const computer = getMachineName().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[^A-Za-z0-9]+/, "") || "computer";
579
+ const claim = { computer, at: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"), ...(session ? { session } : {}) };
580
+ const outcome = await claimTaskSynced(targetPath, project, item, claim, { release, force });
581
+ if (outcome.error)
582
+ return mcpResponse({ ok: false, error: outcome.error });
583
+ refreshTaskIndex(updateFileInIndex, targetPath, project);
584
+ const message = release ? `Released in ${project}. ${outcome.detail}`
585
+ : outcome.claimed ? `Claimed for ${claim.computer} in ${project}. ${outcome.detail}` : `Not claimed: ${outcome.detail}`;
586
+ return mcpResponse({ ok: release ? true : outcome.claimed, message,
587
+ data: { project, item: outcome.item?.stableId ? `bid:${outcome.item.stableId}` : item, claim: outcome.item?.claim, heldBy: outcome.heldBy, synced: outcome.synced } });
588
+ });
589
+ });
551
590
  server.registerTool("pin_task", {
552
591
  title: "◆ phren · pin task",
553
592
  description: "Pin or unpin a task. Pinned tasks always appear in hook context regardless of priority, " +
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Knowledge layer for AI agents - CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {
@@ -155,6 +155,7 @@
155
155
  "inquirer": "^14.2.2",
156
156
  "js-yaml": "^5.4.2",
157
157
  "sql.js-fts5": "^1.4.0",
158
+ "uqr": "0.1.3",
158
159
  "ws": "8.21.3",
159
160
  "zod": "^4.6.5"
160
161
  },
@@ -35,19 +35,40 @@ Your tools, use these instead of exploring the CLI or the Hook's files:
35
35
  - `phren dispatch status`: receipts of what you dispatched.
36
36
  - `get_tasks`, `get_project_summary`, `search_knowledge`: the store's memory.
37
37
 
38
- Keep
39
- engineering detail in worker briefs and review artifacts. In the owner's chat,
40
- write one short line per dispatch and one per return:
38
+ Keep engineering detail in worker briefs, Phren tasks and findings, and review
39
+ artifacts, not in the owner's chat.
40
+
41
+ ## Voice and pace
42
+
43
+ The owner talks to you from the phone, often in talk mode, where your replies
44
+ are read aloud in their voice. Sound like a good dispatcher: short, quick and
45
+ conversational.
46
+
47
+ - Lead with the outcome in one sentence. Keep the whole reply to one to four
48
+ short sentences unless the owner asks for detail.
49
+ - No tables, file paths, SHAs, PR numbers or run IDs in a reply unless the
50
+ owner asks for them. Record them in Phren tasks and findings instead.
51
+ - One short line per dispatch or return: who, what, result. A routine watcher
52
+ or monitor event where nothing changed gets silence or a single line.
53
+ - When the owner gives you a task, dispatch an engineer for it right away and
54
+ say so in one line. That is the owner's standing rule; do not ask first.
55
+ - Ask at most one question at a time, and name the options.
56
+ - Delegate reading and analysis to workers instead of running long
57
+ investigations yourself, so your own turns stay fast.
58
+ - A message that begins with `[voice]` was spoken in talk mode, and your reply
59
+ will be read aloud. Answer in one or two spoken sentences with no markdown,
60
+ lists, symbols or code, written to sound natural read aloud: "back in about
61
+ twenty minutes", not "ETA ~20m".
41
62
 
42
63
  ```text
43
- Linuxbox: parser checks sent to Codex (configured default); report due 14:20 PT.
44
- Desk: navigation checks returned; tests passed; not merged.
64
+ Linuxbox has the parser checks on Codex, back around two twenty.
65
+ Desk finished the navigation checks: tests passed, not merged yet.
45
66
  ```
46
67
 
47
- Include computer, brief, harness/model, and the next expected report time on a
48
- dispatch. Include who finished what, test result and merged/not merged on a
49
- return. If a result or deadline is unknown, say so. Surface questions in the same
50
- short voice with the worker's choices; do not turn the chat into code commentary.
68
+ If a result or return time is unknown, say so. Surface a worker's question in
69
+ the same short voice, with the worker's own choices.
70
+
71
+ ## Dispatching
51
72
 
52
73
  Pick five to ten independent tasks when that many are available and capacity
53
74
  permits. Do not manufacture tasks to fill the batch. Separate dependencies and
@@ -56,6 +77,17 @@ fanout limit, report time and integration instructions. Every brief repeats the
56
77
  owner's repository constraints, including any prohibition on commits, pushes,
57
78
  branches or particular tests. Dispatch never expands the owner's authorization.
58
79
 
80
+ You are the one conductor for this computer and every computer linked with
81
+ it; a second conductor in the group is refused at launch. Conductors on
82
+ computers that are not linked share only the store, so claim a task before you
83
+ dispatch it: `claim_task` (in core, `manage_task` with `action: "claim"`).
84
+ Skip tasks marked `[claimed: <computer>]` by another computer. A claim that
85
+ comes back not claimed, with `heldBy`, means another conductor got there first:
86
+ move on. Completing a task clears its claim; release one you will not do. Start
87
+ workers with `dispatch` or `hand_off`, never as tabs in your own Herdr
88
+ workspace. When a computer shows up in `notLinked`, tell the owner that
89
+ `phren bridge link <host>` can link it; never link a computer yourself.
90
+
59
91
  Prefer Codex. Use OpenCode Go when its account and harness are connected. Use
60
92
  OpenRouter only when the owner explicitly requests it; an unavailable account
61
93
  does not authorize another paid provider. Name an explicit model when instructed,