@xevy/cli 0.1.17 → 0.1.19

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.
package/README.md CHANGED
@@ -57,7 +57,8 @@ OAuth.
57
57
  ```bash
58
58
  xevy # open an interactive pi session with Xevy loaded
59
59
  xevy "summarise this repo" # or send a one-off prompt
60
- xevy dev VI22-07 # attach to a task's remote Dev Session
60
+ xevy dev task/VI22-07 # attach to a task's remote Dev Session
61
+ xevy dev xevy/xevyai # start or resume your personal project session
61
62
  ```
62
63
 
63
64
  That's it — you're set up. The sections below are reference for when you need more detail.
@@ -140,33 +141,35 @@ xevy "summarise this repo" # forwards the prompt to pi
140
141
 
141
142
  ## `xevy dev`
142
143
 
143
- Connect an interactive terminal to the coding agent attached to a task's remote
144
- Dev Session:
144
+ Connect an interactive terminal to a task or personal remote Dev Session:
145
145
 
146
146
  ```bash
147
- xevy dev VI22-07
148
- xevy dev cb49c02e-66d8-4475-95a8-6f3930643ec8
149
- xevy dev VI22-07 --base https://xevy.example.com
147
+ xevy dev task/VI22-07
148
+ xevy dev task/cb49c02e-66d8-4475-95a8-6f3930643ec8
149
+ xevy dev xevy/xevyai
150
+ xevy dev xevy/xevyai --base https://xevy.example.com
150
151
  ```
151
152
 
152
153
  The command stays attached across normal Pi exits and transient terminal
153
- disconnects. It shows startup/restart status while the remote terminal is being
154
- prepared; press `Ctrl+]` to detach intentionally and leave the Dev Session
155
- running.
156
-
157
- The CLI resolves an exact task ID or task code, attaches to its existing Dev
158
- Session, or starts one from a linked repository. It then renders Pi's native TUI
159
- from the isolated remote workspace: normal composer, thinking, tools, history,
160
- keyboard shortcuts, and session resume all behave like Pi on a local machine.
161
- When several accessible tasks share a code, or a project has several linked
162
- repositories, the CLI presents a numbered selector first.
154
+ disconnects. After Pi exits, it waits three seconds before restarting and shows
155
+ a `Ctrl+C` detach hint; press `Ctrl+]` while attached to leave the Dev Session
156
+ running immediately.
157
+
158
+ The CLI grammar is explicit: `task/<task-id-or-code>` selects a task session,
159
+ while `<workspace>/<project>` selects your default personal project session.
160
+ Bare task IDs, aliases, and scope-guessing are intentionally unsupported. After
161
+ the target is resolved, the CLI renders Pi's native TUI from the isolated remote
162
+ workspace: normal composer, thinking, tools, history, keyboard shortcuts, and
163
+ session resume all behave like Pi on a local machine. A multi-repository project
164
+ asks for its runtime repository only on first start.
163
165
 
164
166
  `xevy dev` is only a terminal transport. Pi, Git credentials, the repository,
165
167
  and Docker remain on the server. Press `Ctrl+]` to detach without stopping Pi;
166
168
  run the same command again to reattach. Pi conversation history is stored in the
167
169
  bounded Dev Session volume. The controller periodically commits work and pushes
168
- the resumable Dev Session branch; exiting Pi also commits and pushes any final
169
- edits. You do not need to ask the agent to commit after every prompt.
170
+ the canonical task branch; exiting Pi also commits and pushes any final edits.
171
+ You do not need to ask the agent to commit after every prompt or merge a second
172
+ Dev Session branch when finishing.
170
173
 
171
174
  Terminal control:
172
175
 
@@ -175,8 +178,9 @@ Ctrl+] Disconnect this terminal without stopping Pi or the Dev Session
175
178
  ```
176
179
 
177
180
  Use the task's Dev Session panel in Xevy to open the live site, stop the session,
178
- or finish and redeploy after exiting Pi. A heartbeat keeps the session active
179
- while the CLI is attached, within the server's hard expiry limit.
181
+ or finish it after exiting Pi. Preview redeploy remains a separate action. A
182
+ heartbeat keeps the session active while the CLI is attached, within the
183
+ server's hard expiry limit.
180
184
 
181
185
  Host precedence is `--base`, `XEVY_BASE`, the saved credentials `baseUrl`, then
182
186
  `https://xevy.ai`. API-key precedence is `XEVY_API_KEY`, then the saved key in
@@ -15,8 +15,30 @@ const SESSION_START_TIMEOUT_MS = 10 * 60_000;
15
15
  const EXECUTION_RECONNECT_LIMIT = 8;
16
16
  const TERMINAL_RECONNECT_LIMIT = 8;
17
17
  const TERMINAL_RECONNECT_MAX_DELAY_MS = 5_000;
18
+ const TERMINAL_RESTART_GRACE_MS = 3_000;
18
19
  const TERMINAL_STABLE_RUNTIME_MS = 10_000;
19
20
  const TERMINAL_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
21
+ const DEV_TARGET_SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
22
+
23
+ function parseDevTarget(value) {
24
+ const reference = String(value || "").trim();
25
+ const segments = reference.split("/");
26
+ const usage = "Use `task/<task-id-or-code>` or `<workspace>/<project>`.";
27
+ if (segments.length !== 2 || segments.some((segment) => !segment)) {
28
+ throw new Error(`Invalid Dev Session target '${reference}'. ${usage}`);
29
+ }
30
+ if (segments.some((segment) => !DEV_TARGET_SEGMENT_PATTERN.test(segment))) {
31
+ throw new Error(`Invalid Dev Session target '${reference}'. Identifiers may use letters, numbers, '.', '_', and '-'.`);
32
+ }
33
+ if (segments[0] === "task") {
34
+ return { kind: "task", taskReference: segments[1] };
35
+ }
36
+ return {
37
+ kind: "personal",
38
+ workspaceIdentifier: segments[0],
39
+ projectIdentifier: segments[1],
40
+ };
41
+ }
20
42
 
21
43
  export function parseCredentialsText(source) {
22
44
  const values = {};
@@ -54,11 +76,11 @@ export function normalizeBaseUrl(value) {
54
76
 
55
77
  export function parseDevCommandArgs(argv) {
56
78
  const args = [...argv];
57
- let taskReference = "";
79
+ let targetReference = "";
58
80
  let base = null;
59
81
  while (args.length > 0) {
60
82
  const argument = args.shift();
61
- if (argument === "-h" || argument === "--help") return { help: true, taskReference: "", base: null };
83
+ if (argument === "-h" || argument === "--help") return { help: true, target: null, base: null };
62
84
  if (argument === "--base") {
63
85
  const value = args.shift();
64
86
  if (!value) throw new Error("Missing value for --base");
@@ -66,11 +88,13 @@ export function parseDevCommandArgs(argv) {
66
88
  continue;
67
89
  }
68
90
  if (argument.startsWith("-")) throw new Error(`Unknown option for \`xevy dev\`: ${argument}.`);
69
- if (taskReference) throw new Error("`xevy dev` accepts one task ID or task code.");
70
- taskReference = argument;
91
+ if (targetReference) throw new Error("`xevy dev` accepts one Dev Session target.");
92
+ targetReference = argument;
93
+ }
94
+ if (!targetReference) {
95
+ throw new Error("Usage: xevy dev <task/<task-id-or-code>|workspace/project> [--base <url>]");
71
96
  }
72
- if (!taskReference) throw new Error("Usage: xevy dev <task-id-or-code> [--base <url>]");
73
- return { help: false, taskReference, base };
97
+ return { help: false, target: parseDevTarget(targetReference), base };
74
98
  }
75
99
 
76
100
  export function resolveDevConnection({
@@ -599,12 +623,17 @@ export function createTerminalStatus({ output, writeLine, animate }) {
599
623
  };
600
624
  }
601
625
 
602
- function sessionSummary(task, session, base, writeLine) {
603
- const url = devSessionLaunchUrl(base, task);
626
+ function sessionSummary(context, session, base, writeLine) {
627
+ const task = context.kind === "task" ? context.task : null;
628
+ const url = task
629
+ ? devSessionLaunchUrl(base, task)
630
+ : new URL(`/agent?session=${encodeURIComponent(session.id)}`, `${normalizeBaseUrl(base)}/`).toString();
604
631
  writeLine("\nDev Session");
605
- writeLine(` Task ${formatTask(task)}`);
606
- writeLine(` Site ${url || "not available yet"}`);
607
- writeLine(` Branch ${session.config?.branch || "unknown"}`);
632
+ if (task) writeLine(` Task ${formatTask(task)}`);
633
+ else writeLine(` Project ${context.workspace.identifier}/${context.project.identifier} · Personal`);
634
+ writeLine(` Workbench ${url || "not available yet"}`);
635
+ writeLine(` Preview ${session.config?.runtimeMode === "none" || !session.hostname ? "none (workspace only)" : `https://${session.hostname}`}`);
636
+ writeLine(` Branch ${session.branch || session.config?.branch || "unknown"}`);
608
637
  writeLine(` Status ${session.status}`);
609
638
  writeLine(` Expires ${session.expiresAt || "server-managed"}`);
610
639
  writeLine("\nNative Pi terminal · press Ctrl+] to detach and leave it running\n");
@@ -740,6 +769,7 @@ async function attachNativeTerminalPersistently({
740
769
  let consecutiveFailures = 0;
741
770
  try {
742
771
  while (!signal?.aborted) {
772
+ let reconnectDelayMs = null;
743
773
  status.update(reconnecting ? "Restarting remote Pi terminal…" : "Starting remote Pi terminal…");
744
774
  try {
745
775
  const result = await attachNativeTerminal({
@@ -757,9 +787,12 @@ async function attachNativeTerminalPersistently({
757
787
  consecutiveFailures = result?.durationMs >= TERMINAL_STABLE_RUNTIME_MS
758
788
  ? 0
759
789
  : consecutiveFailures + 1;
760
- status.update(result?.reason === "transport-lost"
761
- ? "Terminal connection lost · reconnecting…"
762
- : "Pi exited · restarting terminal…");
790
+ if (result?.reason === "transport-lost") {
791
+ status.update("Terminal connection lost · reconnecting…");
792
+ } else {
793
+ reconnectDelayMs = TERMINAL_RESTART_GRACE_MS;
794
+ status.update("Pi exited · restarting in 3 seconds · Ctrl+C to detach");
795
+ }
763
796
  } catch (error) {
764
797
  if (signal?.aborted) throw error;
765
798
  if (error instanceof DevSessionApiError && ![409, 502, 503, 504].includes(error.status)) throw error;
@@ -772,7 +805,8 @@ async function attachNativeTerminalPersistently({
772
805
  throw new Error("The remote Pi terminal repeatedly exited before stabilizing. The Dev Session remains active; check its logs and rerun `xevy dev` after correcting the startup error.");
773
806
  }
774
807
  await sleep(
775
- Math.min(500 * 2 ** Math.max(0, consecutiveFailures - 1), TERMINAL_RECONNECT_MAX_DELAY_MS),
808
+ reconnectDelayMs
809
+ ?? Math.min(500 * 2 ** Math.max(0, consecutiveFailures - 1), TERMINAL_RECONNECT_MAX_DELAY_MS),
776
810
  signal,
777
811
  );
778
812
  let current = null;
@@ -793,12 +827,12 @@ async function attachNativeTerminalPersistently({
793
827
  }
794
828
  }
795
829
 
796
- function commandHelp(writeLine) {
830
+ function commandHelp(writeLine, hasWebPreview = true) {
797
831
  writeLine("Commands:");
798
832
  writeLine(" /status Refresh session status");
799
833
  writeLine(" /logs Show the latest Dev Session logs");
800
- writeLine(" /open Open a fresh one-use Dev Session URL");
801
- writeLine(" /finish Merge into the task branch and stop");
834
+ if (hasWebPreview) writeLine(" /open Open a fresh one-use Dev Session URL");
835
+ writeLine(" /finish Save the task branch and stop");
802
836
  writeLine(" /stop Stop the Dev Session without finishing");
803
837
  writeLine(" /detach Leave it running and exit this CLI");
804
838
  writeLine(" /help Show these commands");
@@ -806,7 +840,7 @@ function commandHelp(writeLine) {
806
840
 
807
841
  async function confirmAction({ interactive, ask, action }) {
808
842
  if (!interactive) throw new Error(`/${action} requires an interactive confirmation.`);
809
- const answer = (await ask(`${action === "finish" ? "Finish, merge into the task branch, and stop" : "Stop this Dev Session"}? [y/N]: `)).toLowerCase();
843
+ const answer = (await ask(`${action === "finish" ? "Save the task branch and finish this Dev Session" : "Stop this Dev Session"}? [y/N]: `)).toLowerCase();
810
844
  return answer === "y" || answer === "yes";
811
845
  }
812
846
 
@@ -843,8 +877,10 @@ export async function runDevSession(options) {
843
877
  if (!token.startsWith("xevy_pk_")) {
844
878
  throw new Error("A Xevy API key is required. Run `xevy setup --credentials` first.");
845
879
  }
846
- const taskReference = String(options.taskReference || "").trim();
847
- if (!taskReference) throw new Error("Usage: xevy dev <task-id-or-code> [--base <url>]");
880
+ const target = options.target;
881
+ if (!target || !["task", "personal"].includes(target.kind)) {
882
+ throw new Error("Usage: xevy dev <task/<task-id-or-code>|workspace/project> [--base <url>]");
883
+ }
848
884
 
849
885
  const fetchImpl = options.fetchImpl || globalThis.fetch;
850
886
  if (typeof fetchImpl !== "function") throw new Error("This Node.js version does not provide fetch.");
@@ -913,54 +949,104 @@ export async function runDevSession(options) {
913
949
 
914
950
  let heartbeat = null;
915
951
  let task;
952
+ let context;
916
953
  let session;
954
+ let sessionPath;
917
955
  try {
918
- // Validate both host and key before resolving any task context.
956
+ // Validate both host and key before resolving any session context.
919
957
  await api.request("/api/profile", { signal: detachController.signal });
920
- const search = await api.request("/api/tasks/search", {
921
- method: "POST",
922
- body: { taskIdentifier: taskReference },
923
- signal: detachController.signal,
924
- });
925
- const tasks = search?.tasks || [];
926
- if (tasks.length === 0) throw new Error(`No accessible task matches '${taskReference}'.`);
927
- task = await selectOne({
928
- items: tasks,
929
- label: "tasks",
930
- describe: formatTask,
931
- interactive,
932
- ask,
933
- writeLine,
934
- });
935
-
936
- const sessionPath = `/api/projects/${encodeURIComponent(task.workspaceIdentifier)}/${encodeURIComponent(task.projectIdentifier)}/tasks/${encodeURIComponent(task.id)}/live-session`;
937
- const current = await api.request(`${sessionPath}/`, { signal: detachController.signal });
938
- session = current?.session || null;
939
- if (!session) {
940
- const repositoryResult = await api.request(`${sessionPath}/repositories`, { signal: detachController.signal });
941
- const repositories = repositoryResult?.repos || [];
942
- if (repositories.length === 0) {
943
- throw new Error("No linked repository is configured for this project.");
944
- }
945
- const repository = await selectOne({
946
- items: repositories,
947
- label: "repositories",
948
- describe: (item) => `${item.displayName || item.role}${item.defaultBranch ? ` · ${item.defaultBranch}` : ""}`,
949
- interactive,
950
- ask,
951
- writeLine,
952
- });
953
- writeLine(`Starting Dev Session with ${repository.displayName || repository.role}…`);
954
- const started = await api.request(`${sessionPath}/`, {
958
+ if (target.kind === "task") {
959
+ const search = await api.request("/api/tasks/search", {
955
960
  method: "POST",
956
- body: { runtimeRepositoryId: repository.id },
961
+ body: { taskIdentifier: target.taskReference },
957
962
  signal: detachController.signal,
958
- timeoutMs: 60_000,
959
963
  });
960
- session = started?.session;
961
- if (!session) throw new Error("Xevy accepted the request but returned no Dev Session.");
964
+ const tasks = search?.tasks || [];
965
+ if (tasks.length === 0) throw new Error(`No accessible task matches '${target.taskReference}'.`);
966
+ if (tasks.length > 1) {
967
+ throw new Error(`More than one task matches '${target.taskReference}'. Use the task UUID after 'task/'.`);
968
+ }
969
+ task = tasks[0];
970
+ context = { kind: "task", task };
971
+ sessionPath = `/api/projects/${encodeURIComponent(task.workspaceIdentifier)}/${encodeURIComponent(task.projectIdentifier)}/tasks/${encodeURIComponent(task.id)}/live-session`;
972
+ const current = await api.request(`${sessionPath}/`, { signal: detachController.signal });
973
+ session = current?.session || null;
974
+ if (!session) {
975
+ const repositoryResult = await api.request(`${sessionPath}/repositories`, { signal: detachController.signal });
976
+ const repositories = repositoryResult?.repos || [];
977
+ if (repositories.length === 0) {
978
+ throw new Error("No linked repository is configured for this project.");
979
+ }
980
+ const repository = await selectOne({
981
+ items: repositories,
982
+ label: "repositories",
983
+ describe: (item) => `${item.displayName || item.role}${item.defaultBranch ? ` · ${item.defaultBranch}` : ""}`,
984
+ interactive,
985
+ ask,
986
+ writeLine,
987
+ });
988
+ writeLine(`Starting Dev Session with ${repository.displayName || repository.role}…`);
989
+ const started = await api.request(`${sessionPath}/`, {
990
+ method: "POST",
991
+ body: { runtimeRepositoryId: repository.id },
992
+ signal: detachController.signal,
993
+ timeoutMs: 60_000,
994
+ });
995
+ session = started?.session;
996
+ if (!session) throw new Error("Xevy accepted the request but returned no Dev Session.");
997
+ } else {
998
+ writeLine("Attaching to the existing Dev Session…");
999
+ }
962
1000
  } else {
963
- writeLine("Attaching to the existing Dev Session…");
1001
+ const workspaceResult = await api.request("/api/workspaces", { signal: detachController.signal });
1002
+ const workspace = (workspaceResult?.workspaces || [])
1003
+ .find((item) => item.identifier === target.workspaceIdentifier);
1004
+ const project = workspace?.projects?.find((item) => item.identifier === target.projectIdentifier);
1005
+ if (!workspace || !project) {
1006
+ throw new Error(`No accessible project matches '${target.workspaceIdentifier}/${target.projectIdentifier}'.`);
1007
+ }
1008
+ context = { kind: "personal", workspace, project };
1009
+ const candidates = await api.request(
1010
+ `/api/agent/dev-session-candidates?projectId=${encodeURIComponent(project.id)}`,
1011
+ { signal: detachController.signal },
1012
+ );
1013
+ const existingSessionId = candidates?.personal?.existingSessionId || null;
1014
+ if (existingSessionId) {
1015
+ sessionPath = `/api/agent/dev-sessions/${encodeURIComponent(existingSessionId)}`;
1016
+ const current = await api.request(sessionPath, { signal: detachController.signal });
1017
+ session = current?.session || null;
1018
+ if (session) writeLine("Attaching to your existing personal Dev Session…");
1019
+ }
1020
+ if (!session) {
1021
+ const repositories = candidates?.repositories || [];
1022
+ if (repositories.length === 0) {
1023
+ throw new Error(candidates?.personal?.blocker || "No linked repository is configured for this project.");
1024
+ }
1025
+ const repository = await selectOne({
1026
+ items: repositories,
1027
+ label: "repositories",
1028
+ describe: (item) => `${item.displayName || item.role}${item.defaultBranch ? ` · ${item.defaultBranch}` : ""}`,
1029
+ interactive,
1030
+ ask,
1031
+ writeLine,
1032
+ });
1033
+ writeLine(`Starting personal Dev Session with ${repository.displayName || repository.role}…`);
1034
+ const started = await api.request("/api/agent/dev-sessions", {
1035
+ method: "POST",
1036
+ body: {
1037
+ target: {
1038
+ kind: "personal",
1039
+ projectId: project.id,
1040
+ runtimeRepositoryId: repository.id,
1041
+ },
1042
+ },
1043
+ signal: detachController.signal,
1044
+ timeoutMs: 60_000,
1045
+ });
1046
+ session = started?.session;
1047
+ if (!session?.id) throw new Error("Xevy accepted the request but returned no Dev Session.");
1048
+ sessionPath = `/api/agent/dev-sessions/${encodeURIComponent(session.id)}`;
1049
+ }
964
1050
  }
965
1051
 
966
1052
  let heartbeatFailures = 0;
@@ -990,7 +1076,7 @@ export async function runDevSession(options) {
990
1076
  sleep,
991
1077
  signal: detachController.signal,
992
1078
  });
993
- sessionSummary(task, session, base, writeLine);
1079
+ sessionSummary(context, session, base, writeLine);
994
1080
 
995
1081
  const nativeTerminal = options.nativeTerminal
996
1082
  ?? (input === process.stdin && output === process.stdout);
@@ -1008,7 +1094,12 @@ export async function runDevSession(options) {
1008
1094
  animateStatus: options.animateStatus,
1009
1095
  });
1010
1096
  detached = true;
1011
- return { task, session, detached: true };
1097
+ return { task, project: context.kind === "personal" ? context.project : null, session, detached: true };
1098
+ }
1099
+
1100
+ if (context.kind === "personal") {
1101
+ writeLine("Attached successfully. Rerun in an interactive terminal to open Pi.");
1102
+ return { task: null, project: context.project, session, detached: true };
1012
1103
  }
1013
1104
 
1014
1105
  const renderState = {
@@ -1038,7 +1129,7 @@ export async function runDevSession(options) {
1038
1129
 
1039
1130
  if (!interactive) {
1040
1131
  writeLine("Attached successfully. Rerun in an interactive terminal to prompt the agent.");
1041
- return { task, session, detached: true };
1132
+ return { task, project: null, session, detached: true };
1042
1133
  }
1043
1134
 
1044
1135
  while (!detached) {
@@ -1046,7 +1137,7 @@ export async function runDevSession(options) {
1046
1137
  if (detached) break;
1047
1138
  if (!prompt) continue;
1048
1139
  if (prompt === "/help") {
1049
- commandHelp(writeLine);
1140
+ commandHelp(writeLine, session.config?.runtimeMode !== "none" && Boolean(session.hostname));
1050
1141
  continue;
1051
1142
  }
1052
1143
  if (prompt === "/detach") {
@@ -1057,7 +1148,7 @@ export async function runDevSession(options) {
1057
1148
  const result = await api.request(`${sessionPath}/`, { signal: detachController.signal });
1058
1149
  if (!result?.session) throw new Error("No active Dev Session remains for this task.");
1059
1150
  session = result.session;
1060
- sessionSummary(task, session, base, writeLine);
1151
+ sessionSummary(context, session, base, writeLine);
1061
1152
  continue;
1062
1153
  }
1063
1154
  if (prompt === "/logs") {
@@ -1067,6 +1158,10 @@ export async function runDevSession(options) {
1067
1158
  continue;
1068
1159
  }
1069
1160
  if (prompt === "/open") {
1161
+ if (session.config?.runtimeMode === "none" || !session.hostname) {
1162
+ writeLine("This Dev Session has no web runtime or live preview.");
1163
+ continue;
1164
+ }
1070
1165
  await launchBrowser({ api, sessionPath, platform, spawnImpl, writeLaunchLine });
1071
1166
  continue;
1072
1167
  }
@@ -1076,7 +1171,7 @@ export async function runDevSession(options) {
1076
1171
  continue;
1077
1172
  }
1078
1173
  await api.request(`${sessionPath}/stop`, { method: "POST", body: {}, signal: detachController.signal });
1079
- writeLine("Dev Session stopped. Its pushed branch is preserved for a safe resume.");
1174
+ writeLine("Dev Session stopped. The pushed task branch is preserved for a safe resume.");
1080
1175
  detached = true;
1081
1176
  break;
1082
1177
  }
@@ -1104,7 +1199,7 @@ export async function runDevSession(options) {
1104
1199
  if (completed.status !== "succeeded") {
1105
1200
  throw new Error(completed.errorMessage || `Finish ${completed.status}.`);
1106
1201
  }
1107
- writeLine("Finished: the Dev Session branch was merged into the task branch and the workspace was stopped.");
1202
+ writeLine("Finished: the task branch was saved and the workspace was stopped.");
1108
1203
  detached = true;
1109
1204
  break;
1110
1205
  }
@@ -1155,10 +1250,15 @@ export async function runDevSession(options) {
1155
1250
  writeLine(`Agent turn failed: ${completed.errorMessage || "unknown error"}`);
1156
1251
  }
1157
1252
  }
1158
- return { task, session, detached: true };
1253
+ return { task, project: null, session, detached: true };
1159
1254
  } catch (error) {
1160
1255
  if (detached && /detached/i.test(error instanceof Error ? error.message : String(error))) {
1161
- return { task, session, detached: true };
1256
+ return {
1257
+ task,
1258
+ project: context?.kind === "personal" ? context.project : null,
1259
+ session,
1260
+ detached: true,
1261
+ };
1162
1262
  }
1163
1263
  throw new Error(redactSensitive(error instanceof Error ? error.message : String(error), secrets));
1164
1264
  } finally {
package/bin/xevy.mjs CHANGED
@@ -96,7 +96,7 @@ function usage() {
96
96
  xevy setup [options] Choose credentials, pi, skills, and MCP setup
97
97
  xevy update [--base u] Refresh the pi extensions + coding-agent skills/MCP
98
98
  xevy check [--base u] Report skill updates or missing coding-agent targets
99
- xevy dev <task> Attach to a remote task Dev Session
99
+ xevy dev <target> Attach to a remote task or personal Dev Session
100
100
 
101
101
  Options:
102
102
  --base <url> Xevy host (default: XEVY_BASE or ${DEFAULT_BASE})
@@ -118,7 +118,8 @@ Examples:
118
118
  npx @xevy/cli setup --credentials --mcp -a codex
119
119
  npx @xevy/cli setup --all -y
120
120
  npx @xevy/cli update
121
- npx @xevy/cli dev VI22-07
121
+ npx @xevy/cli dev task/VI22-07
122
+ npx @xevy/cli dev xevy/xevyai
122
123
  npx @xevy/cli
123
124
 
124
125
  Install globally to drop the npx prefix:
@@ -130,11 +131,12 @@ Install globally to drop the npx prefix:
130
131
  function devUsage() {
131
132
  console.log(`Xevy Dev Session
132
133
 
133
- xevy dev <task-id-or-code> [--base <url>]
134
+ xevy dev task/<task-id-or-code> [--base <url>]
135
+ xevy dev <workspace>/<project> [--base <url>]
134
136
 
135
- Connects this terminal to the task's remote Dev Session. The command attaches
136
- to an existing session or starts one from a linked repository, then opens Pi's
137
- native interactive terminal inside the isolated remote workspace.
137
+ Connects this terminal to a remote Dev Session. The reserved task/ prefix
138
+ selects task work; a workspace/project target starts or resumes your personal
139
+ project session. Pi runs inside the isolated remote workspace.
138
140
 
139
141
  Terminal control:
140
142
  Ctrl+] Detach without stopping Pi or the Dev Session
@@ -159,7 +161,7 @@ function parseArgv(argv) {
159
161
  try {
160
162
  const parsed = parseDevCommandArgs(args);
161
163
  if (parsed.help) return { command: "dev-help" };
162
- return { command: "dev", taskReference: parsed.taskReference, base: parsed.base };
164
+ return { command: "dev", target: parsed.target, base: parsed.base };
163
165
  } catch (error) {
164
166
  die(error instanceof Error ? error.message : String(error));
165
167
  }
@@ -663,7 +665,7 @@ async function dev(opts) {
663
665
  await runDevSession({
664
666
  base,
665
667
  token,
666
- taskReference: opts.taskReference,
668
+ target: opts.target,
667
669
  });
668
670
  }
669
671
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xevy/cli",
3
- "version": "0.1.17",
3
+ "version": "0.1.19",
4
4
  "description": "Xevy CLI — connect to remote Dev Sessions, configure credentials, pi, coding-agent skills, and MCP, and keep integrations current.",
5
5
  "type": "module",
6
6
  "keywords": [