@evref-bl/pharo-launcher-mcp 0.1.1 → 0.1.3

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 (47) hide show
  1. package/README.md +158 -123
  2. package/bin/pharo-launcher.cmd +46 -46
  3. package/bin/pharo-launcher.sh +0 -0
  4. package/dist/commandCatalog.d.ts.map +1 -1
  5. package/dist/commandCatalog.js +17 -0
  6. package/dist/commandCatalog.js.map +1 -1
  7. package/dist/config.d.ts +21 -1
  8. package/dist/config.d.ts.map +1 -1
  9. package/dist/config.js +97 -11
  10. package/dist/config.js.map +1 -1
  11. package/dist/crossProfileCopy.d.ts +87 -0
  12. package/dist/crossProfileCopy.d.ts.map +1 -0
  13. package/dist/crossProfileCopy.js +437 -0
  14. package/dist/crossProfileCopy.js.map +1 -0
  15. package/dist/discovery.d.ts +165 -1
  16. package/dist/discovery.d.ts.map +1 -1
  17. package/dist/discovery.js +744 -1
  18. package/dist/discovery.js.map +1 -1
  19. package/dist/imageMetadata.d.ts +9 -0
  20. package/dist/imageMetadata.d.ts.map +1 -0
  21. package/dist/imageMetadata.js +82 -0
  22. package/dist/imageMetadata.js.map +1 -0
  23. package/dist/launcherCli.d.ts +7 -1
  24. package/dist/launcherCli.d.ts.map +1 -1
  25. package/dist/launcherCli.js +651 -32
  26. package/dist/launcherCli.js.map +1 -1
  27. package/dist/models.d.ts +2 -0
  28. package/dist/models.d.ts.map +1 -1
  29. package/dist/platform.d.ts +2 -0
  30. package/dist/platform.d.ts.map +1 -1
  31. package/dist/platform.js +21 -0
  32. package/dist/platform.js.map +1 -1
  33. package/dist/resultNormalizer.d.ts.map +1 -1
  34. package/dist/resultNormalizer.js +87 -1
  35. package/dist/resultNormalizer.js.map +1 -1
  36. package/dist/server.d.ts +6 -1
  37. package/dist/server.d.ts.map +1 -1
  38. package/dist/server.js +516 -6
  39. package/dist/server.js.map +1 -1
  40. package/docs/README.md +26 -0
  41. package/docs/cleanup-hook-boundary.md +94 -0
  42. package/docs/development.md +64 -22
  43. package/docs/reference/tools.md +179 -0
  44. package/docs/troubleshooting.md +135 -0
  45. package/docs/user/getting-started.md +172 -0
  46. package/docs/user/profile-mode.md +176 -0
  47. package/package.json +11 -6
@@ -0,0 +1,94 @@
1
+ # Cleanup Hook Boundary
2
+
3
+ This boundary maps pharo-launcher-mcp status, timeout, stop, and cleanup
4
+ surfaces for caller-managed isolated live checks. It documents the launcher
5
+ server's contract only; callers own higher-level project policy, approval,
6
+ artifact retention, and cleanup orchestration.
7
+
8
+ ## Read-Only Inspection
9
+
10
+ These checks are safe for planning and static verification:
11
+
12
+ - `npm test`, `npm run typecheck`, and `npm run build`
13
+ - `git status --short --branch`
14
+ - source review of command schemas, parser behavior, result envelopes, and
15
+ timeout handling
16
+ - `pharo_launcher_health`, because it reports resolved paths without invoking
17
+ Pharo Launcher
18
+ - `pharo_launcher_config`, because it reports resolved configuration without
19
+ invoking Pharo Launcher
20
+
21
+ These checks inspect live host state or invoke Pharo Launcher. Run them only
22
+ when the caller has chosen to cross that boundary:
23
+
24
+ - `pharo_launcher_version`
25
+ - `pharo_launcher_validate_installation`
26
+ - `pharo_launcher_image_list`
27
+ - `pharo_launcher_image_info`
28
+ - `pharo_launcher_process_list`
29
+
30
+ They are non-mutating, but they still cross the live host boundary.
31
+
32
+ ## Status Signals
33
+
34
+ The existing launcher result envelope carries status data for callers:
35
+
36
+ - `ok`
37
+ - `parser.status`
38
+ - normalized `data` when parsing is supported
39
+ - raw `stdout` and `stderr`
40
+ - command `durationMs`
41
+ - command `exitCode`
42
+ - command `timedOut`
43
+ - optional `timeoutReason`
44
+
45
+ For cleanup decisions, callers must prefer normalized image and process data.
46
+ Raw output is diagnostic evidence, not ownership proof.
47
+
48
+ ## Stop And Cleanup Hooks
49
+
50
+ The mutation hooks that can participate in cleanup are:
51
+
52
+ - `pharo_launcher_process_kill` with `confirm: true`
53
+ - `pharo_launcher_image_delete` with `confirm: true`
54
+ - `pharo_launcher_image_recreate` with `confirm: true`, only for explicitly
55
+ disposable images
56
+ - profile-root cleanup by the caller after logs and diagnostics are retained
57
+
58
+ The caller must pass either a recorded pid or an owned image name. Ambiguous
59
+ cleanup input is not allowed. It must never use these hooks against the user's
60
+ source image, default profile, unrelated images, unrelated VMs, or a process
61
+ that cannot be tied to the smoke run.
62
+
63
+ ## Timeout Boundary
64
+
65
+ Every launcher call must have a bounded timeout supplied by the caller or by
66
+ the server default. A timeout means the caller records the phase as failed,
67
+ retains command metadata, and continues with owned cleanup. A timeout does not
68
+ authorize broader host cleanup.
69
+
70
+ ## Profile And Artifact Boundary
71
+
72
+ A future isolated live check must use a disposable profile rooted by
73
+ `PHARO_LAUNCHER_MCP_STATE_ROOT` or the explicit profile path variables:
74
+
75
+ - `PHARO_LAUNCHER_MCP_LAUNCHER_IMAGE`
76
+ - `PHARO_LAUNCHER_MCP_IMAGES_DIR`
77
+ - `PHARO_LAUNCHER_MCP_VMS_DIR`
78
+ - `PHARO_LAUNCHER_MCP_TEMPLATE_SOURCES_DIR`
79
+ - `PHARO_LAUNCHER_MCP_INIT_SCRIPTS_DIR`
80
+ - `PHARO_LAUNCHER_MCP_LOGS_DIR`
81
+
82
+ Retain the launcher logs, command envelopes, image names, image paths, process
83
+ pids, and timeout reasons before deleting disposable directories.
84
+
85
+ ## Follow-Up Policy
86
+
87
+ No launcher-side blocking hook gap is currently identified for caller-managed
88
+ isolated live checks. pharo-launcher-mcp exposes the needed status, timeout,
89
+ image delete, and process kill primitives. Callers still own higher-level
90
+ ownership, approval, artifact retention, and idempotent cleanup policy.
91
+
92
+ If a future caller needs one atomic cleanup/report command instead of composing
93
+ the existing primitives, create a pharo-launcher-mcp follow-up work item. Do
94
+ not bypass the safety gate with raw host commands.
@@ -1,9 +1,9 @@
1
- # pharo-launcher-mcp Development
1
+ # Development
2
2
 
3
- This document contains development notes for pharo-launcher-mcp. The main README is kept
4
- focused on installation, configuration, and tool usage.
3
+ This document is for maintainers changing pharo-launcher-mcp. The README stays
4
+ focused on installation and first use; user-facing detail lives under `docs/`.
5
5
 
6
- ## Source Layout
6
+ ## Source layout
7
7
 
8
8
  - `src/server.ts`: MCP server surface and tool dispatch.
9
9
  - `src/commandCatalog.ts`: Pharo Launcher command definitions and input checks.
@@ -18,12 +18,11 @@ focused on installation, configuration, and tool usage.
18
18
  - `bin/pharo-launcher.sh`: POSIX wrapper.
19
19
  - `scripts/*.ps1`: Windows helper scripts for local live checks.
20
20
 
21
- ## Local Setup
21
+ ## Local setup
22
22
 
23
23
  ```sh
24
24
  npm install
25
- npm run build
26
- npm test
25
+ npm run check
27
26
  ```
28
27
 
29
28
  Useful scripts:
@@ -35,33 +34,45 @@ npm test
35
34
  npm run test:integration
36
35
  ```
37
36
 
38
- `npm test` runs unit coverage only. It does not invoke a local Pharo Launcher.
37
+ `npm run check` runs type checking, build, and unit tests. `npm test` runs unit
38
+ coverage only. It does not invoke a local Pharo Launcher.
39
39
 
40
- ## Platform Contract
40
+ ## Platform contract
41
41
 
42
42
  The production code handles Windows, macOS, and Linux explicitly:
43
43
 
44
44
  - Windows defaults to `%LOCALAPPDATA%\Pharo Launcher`,
45
45
  `PharoConsole.exe`, and `pharo-launcher.cmd`.
46
- - macOS defaults to `$HOME/Library/Application Support/Pharo Launcher`,
47
- the app-bundle VM path, and `pharo-launcher.sh`.
46
+ - macOS discovery checks `$HOME/Applications/PharoLauncher.app` and
47
+ `/Applications/PharoLauncher.app` before falling back to
48
+ `$HOME/Library/Application Support/Pharo Launcher`. App-bundle installs use
49
+ `Contents/MacOS/Pharo` and `Contents/Resources/PharoLauncher.image`.
48
50
  - Linux defaults to `$HOME/.local/share/Pharo Launcher`, `pharo-vm/pharo`,
49
51
  and `pharo-launcher.sh`.
50
52
 
51
53
  `src/crossPlatform.test.ts` covers configuration defaults, bundled wrapper
52
54
  selection, and native process backend selection for all three platforms.
55
+ `src/config.test.ts` covers macOS app-bundle discovery, fallback, and explicit
56
+ environment override precedence.
53
57
 
54
- ## Process Backend
58
+ No-profile mode means no pharo-launcher-mcp profile is active and no
59
+ pharo-launcher-mcp home/cache is created. The resolved Pharo Launcher
60
+ installation and its normal state scope are used directly. Profile mode is
61
+ entered only when `PHARO_LAUNCHER_MCP_PROFILE`,
62
+ `PHARO_LAUNCHER_MCP_STATE_ROOT`, or one of the explicit profile directory
63
+ variables is present.
55
64
 
56
- Pharo Launcher process commands can vary by host. pharo-launcher-mcp uses a native process
57
- backend for `pharo_launcher_process_list` and `pharo_launcher_process_kill`
58
- when needed:
65
+ ## Process backend
66
+
67
+ Pharo Launcher process commands can vary by host. pharo-launcher-mcp uses a
68
+ native process backend for `pharo_launcher_process_list` and
69
+ `pharo_launcher_process_kill` when needed:
59
70
 
60
71
  - Windows uses a PowerShell/CIM query.
61
72
  - macOS and Linux use `ps -axo pid=,args=`.
62
73
  - Unsupported host platforms return an explicit unsupported-backend error.
63
74
 
64
- ## Parsing Boundary
75
+ ## Parsing boundary
65
76
 
66
77
  `src/parser.ts` is the only layer that translates Pharo Launcher output into
67
78
  pharo-launcher-mcp models.
@@ -86,7 +97,14 @@ LauncherProcess
86
97
  LauncherCommandResult
87
98
  ```
88
99
 
89
- ## Integration Tests
100
+ Inventory output adds normalized identity metadata on top of parsed launcher
101
+ models. Template identities normalize Pharo and Moose template names to the
102
+ underlying Pharo version when possible, infer architecture from template names
103
+ or URLs, and attach source-file digest/mtime for installed `.ston` template
104
+ files. Image identities mirror the launcher metadata returned by image
105
+ list/info commands.
106
+
107
+ ## Integration tests
90
108
 
91
109
  Run the live integration suite explicitly:
92
110
 
@@ -119,10 +137,10 @@ External-source image creation variants such as build, pull request,
119
137
  repository, SHA, and VM mutation commands should use explicit fixtures because
120
138
  they require network inputs or can alter VM installations.
121
139
 
122
- ## Windows Live Helpers
140
+ ## Windows live helpers
123
141
 
124
142
  The helper scripts under `scripts/*.ps1` are Windows PowerShell conveniences for
125
- the current development environment:
143
+ a local Windows development environment:
126
144
 
127
145
  ```powershell
128
146
  .\scripts\verify-environment.ps1
@@ -134,10 +152,10 @@ The live smoke test uses a dedicated profile root and copies the Pharo Launcher
134
152
  control image there before making live calls. It runs harmless checks by
135
153
  default: health, `--version`, and installation validation.
136
154
 
137
- Default profile root:
155
+ When `-StateRoot` is not supplied, the helper uses:
138
156
 
139
157
  ```text
140
- C:\dev\code\git\.pharo-launcher-mcp\profiles\live-test
158
+ <repo-parent>\.pharo-launcher-mcp\profiles\live-test
141
159
  ```
142
160
 
143
161
  Refresh the copied launcher control image:
@@ -149,7 +167,13 @@ Refresh the copied launcher control image:
149
167
  These helpers are not a substitute for cross-platform verification on macOS and
150
168
  Linux.
151
169
 
152
- ## Local Probes
170
+ ## Cleanup hook boundary
171
+
172
+ Use `docs/cleanup-hook-boundary.md` when mapping launcher status, stop,
173
+ timeout, and cleanup hooks for isolated live checks. That boundary
174
+ distinguishes read-only planning checks from host inspection and mutation.
175
+
176
+ ## Local probes
153
177
 
154
178
  Probe the local Pharo Launcher image list without starting MCP stdio:
155
179
 
@@ -164,3 +188,21 @@ Start the MCP server over stdio from a local build:
164
188
  ```powershell
165
189
  node .\dist\index.js
166
190
  ```
191
+
192
+ ## Documentation updates
193
+
194
+ Keep docs close to the behavior they describe:
195
+
196
+ - Put the fastest install and health path in `README.md`.
197
+ - Put profile details in `docs/user/profile-mode.md`.
198
+ - Put tool arguments and result shape in `docs/reference/tools.md`.
199
+ - Put live host failure modes in `docs/troubleshooting.md`.
200
+ - Keep examples generic. Do not use local machine paths, project names, issue
201
+ numbers, or incident history as examples.
202
+
203
+ Before committing docs changes, run:
204
+
205
+ ```sh
206
+ npm run check
207
+ npm pack --dry-run
208
+ ```
@@ -0,0 +1,179 @@
1
+ # Tool Reference
2
+
3
+ pharo-launcher-mcp exposes MCP tools over stdio. Most tools call Pharo Launcher
4
+ and return a normalized launcher result envelope. Health and configuration tools
5
+ only inspect local paths.
6
+
7
+ ## Health And Configuration
8
+
9
+ | Tool | Live Launcher invocation | Purpose |
10
+ | --- | --- | --- |
11
+ | `pharo_launcher_health` | No | Reports service version, resolved paths, wrapper source, and existence checks. |
12
+ | `pharo_launcher_config` | No | Reports resolved installation, profile, wrapper, and configuration paths. |
13
+ | `pharo_launcher_version` | Yes | Runs `--version`. |
14
+ | `pharo_launcher_validate_installation` | Yes | Checks resolved paths and runs `--version`. |
15
+ | `pharo_launcher_inventory` | Yes | Reports profile roots, templates, image identities, declared image handles, probes, and diagnostics. |
16
+
17
+ `pharo_launcher_inventory` accepts optional `declaredImages` supplied by a
18
+ scoped caller:
19
+
20
+ ```json
21
+ {
22
+ "declaredImages": [
23
+ {
24
+ "imageId": "image:sample-130",
25
+ "imageName": "sample-130",
26
+ "status": "active"
27
+ }
28
+ ]
29
+ }
30
+ ```
31
+
32
+ ## Image Tools
33
+
34
+ | Tool | Arguments |
35
+ | --- | --- |
36
+ | `pharo_launcher_image_list` | `nameFilter`, table options |
37
+ | `pharo_launcher_image_info` | `imageName`, table options |
38
+ | `pharo_launcher_image_create` | `templateName`, `newImageName`, `templateCategory`, `dev`, `noLaunch` |
39
+ | `pharo_launcher_image_copy` | `imageName`, `newImageName` |
40
+ | `pharo_launcher_image_copy_between_profiles` | `sourceProfile`, `destinationProfile`, `sourceImageName`, `destinationImageName` |
41
+ | `pharo_launcher_image_launch` | `imageName`, `script`, `detached`, `displayMode` |
42
+ | `pharo_launcher_image_package` | `imageName`, `location`, `zip`, `vm` |
43
+ | `pharo_launcher_image_bisect` | `pharoVersion` |
44
+ | `pharo_launcher_image_create_from_build` | `buildNumber`, `pharoVersion`, `newImageName` |
45
+ | `pharo_launcher_image_create_from_pull_request` | `pullRequest`, `newImageName`, `templateName`, `templateCategory` |
46
+ | `pharo_launcher_image_create_from_repo` | `repository`, `newImageName`, `templateName`, `templateCategory`, `subfolder`, `baseline`, `group` |
47
+ | `pharo_launcher_image_create_from_sha` | `sha`, `pharoVersion`, `newImageName` |
48
+ | `pharo_launcher_image_delete` | `imageName`, `force`, `confirm: true` |
49
+ | `pharo_launcher_image_recreate` | `imageName`, `confirm: true` |
50
+
51
+ `pharo_launcher_image_create` and `pharo_launcher_image_copy` verify the target
52
+ image after Launcher returns. A successful Launcher exit is not enough: the MCP
53
+ result is successful only when the target image can be listed and inspected.
54
+
55
+ `pharo_launcher_image_launch` supports:
56
+
57
+ - `displayMode: "headless"` or `"interactive"`
58
+ - `detached: true` for detached launches with log paths in the result
59
+ - `script` for a launch script passed to Launcher, or evaluated by the profile
60
+ VM launch path
61
+
62
+ In profile mode, image launch resolves the image and VM inside the active
63
+ profile roots instead of using Launcher defaults.
64
+
65
+ ## Template Tools
66
+
67
+ | Tool | Arguments |
68
+ | --- | --- |
69
+ | `pharo_launcher_template_category_list` | table options |
70
+ | `pharo_launcher_template_list` | `templateCategory`, table options |
71
+ | `pharo_launcher_template_info` | `templateName`, `templateCategory` |
72
+ | `pharo_launcher_template_update` | none |
73
+
74
+ Table options are:
75
+
76
+ ```json
77
+ {
78
+ "format": "ston",
79
+ "brief": true,
80
+ "rowMode": true,
81
+ "delimiter": "|"
82
+ }
83
+ ```
84
+
85
+ `format` can be `ston` or `text`. The default is `ston` when a tool supports
86
+ table output.
87
+
88
+ In profile mode, `pharo_launcher_template_update` also verifies that the active
89
+ profile source list is usable and probes `template list`.
90
+
91
+ ## VM Tools
92
+
93
+ | Tool | Arguments |
94
+ | --- | --- |
95
+ | `pharo_launcher_vm_list` | `vmId`, table options |
96
+ | `pharo_launcher_vm_info` | `vmId` |
97
+ | `pharo_launcher_vm_update` | `vmId` |
98
+ | `pharo_launcher_vm_delete` | `vmId`, `confirm: true` |
99
+
100
+ VM update can download or install VM files. Use profile mode when automation
101
+ needs VM state isolated from a user's normal Launcher installation.
102
+
103
+ ## Process Tools
104
+
105
+ | Tool | Arguments |
106
+ | --- | --- |
107
+ | `pharo_launcher_process_list` | none |
108
+ | `pharo_launcher_process_kill` | exactly one of `pid` or `imageName`, plus `confirm: true` |
109
+
110
+ On Windows, process tools use PowerShell/CIM. On macOS and Linux, they use
111
+ `ps -axo pid=,args=`. Unsupported platforms return an explicit unsupported
112
+ backend error.
113
+
114
+ Prefer PID-based cleanup when a prior detached launch returned a PID. Image-name
115
+ cleanup can match more than one process if multiple command lines contain the
116
+ same image name.
117
+
118
+ ## Raw Command
119
+
120
+ `pharo_launcher_raw_command` is the escape hatch for Launcher CLI arguments not
121
+ covered by a dedicated MCP tool:
122
+
123
+ ```json
124
+ {
125
+ "args": ["image", "list", "--ston"],
126
+ "confirm": true
127
+ }
128
+ ```
129
+
130
+ It always requires `confirm: true`.
131
+
132
+ ## Result Envelope
133
+
134
+ Launcher tools return JSON shaped like this:
135
+
136
+ ```ts
137
+ {
138
+ ok: boolean;
139
+ data?: unknown;
140
+ diagnostic?: string;
141
+ action?: string;
142
+ parser: {
143
+ status: "parsed" | "unsupported" | "failed" | "skipped";
144
+ format: "ston" | "text";
145
+ message?: string;
146
+ };
147
+ raw: {
148
+ stdout: string;
149
+ stderr: string;
150
+ format: "ston" | "text";
151
+ };
152
+ command: {
153
+ args: string[];
154
+ durationMs: number;
155
+ exitCode: number | null;
156
+ timedOut: boolean;
157
+ timeoutReason?: string;
158
+ };
159
+ }
160
+ ```
161
+
162
+ Use `ok` and normalized `data` for program flow. Treat `raw.stdout` and
163
+ `raw.stderr` as diagnostics.
164
+
165
+ ## Confirmation Gates
166
+
167
+ These tools require `confirm: true`:
168
+
169
+ ```text
170
+ pharo_launcher_image_delete
171
+ pharo_launcher_image_recreate
172
+ pharo_launcher_vm_delete
173
+ pharo_launcher_process_kill
174
+ pharo_launcher_raw_command
175
+ ```
176
+
177
+ The confirmation flag only confirms that the caller meant to cross that tool's
178
+ mutation boundary. It does not prove the image, VM, profile, or process is
179
+ caller-owned.
@@ -0,0 +1,135 @@
1
+ # Troubleshooting
2
+
3
+ Start with `pharo_launcher_health` or the local CLI health check:
4
+
5
+ ```sh
6
+ npx @evref-bl/pharo-launcher-mcp --health
7
+ ```
8
+
9
+ Health checks do not invoke Pharo Launcher. They show the resolved installation,
10
+ control image, VM path, wrapper path, profile paths, and whether those paths
11
+ exist.
12
+
13
+ ## Launcher Paths Are Wrong
14
+
15
+ Set the installation paths explicitly:
16
+
17
+ ```sh
18
+ PHARO_LAUNCHER_DIR="/path/to/Pharo Launcher"
19
+ PHARO_LAUNCHER_VM="/path/to/pharo"
20
+ PHARO_LAUNCHER_IMAGE="/path/to/PharoLauncher.image"
21
+ PHARO_LAUNCHER_SCRIPT="/path/to/pharo-launcher.sh"
22
+ ```
23
+
24
+ Then run:
25
+
26
+ ```sh
27
+ npx @evref-bl/pharo-launcher-mcp --health
28
+ ```
29
+
30
+ On macOS, the server checks user and system `PharoLauncher.app` locations before
31
+ falling back to the Application Support layout. The health report includes the
32
+ selected discovery source and all attempted candidates.
33
+
34
+ ## Wrapper Is Missing
35
+
36
+ `PHARO_LAUNCHER_SCRIPT` is optional. If it is unset, the server tries the
37
+ bundled wrapper for the host platform. If that wrapper cannot be resolved, the
38
+ server invokes the VM directly with the Launcher control image.
39
+
40
+ If a selected wrapper path exists but is not executable, the command result
41
+ contains a startup diagnostic with the command, args, working directory, PATH,
42
+ and active profile variables.
43
+
44
+ ## `validate_installation` Fails
45
+
46
+ `pharo_launcher_validate_installation` runs `--version`. If it fails:
47
+
48
+ 1. Run `pharo_launcher_config` and confirm the VM and control image paths.
49
+ 2. Run `pharo_launcher_health` and check `launcherScript.exists`.
50
+ 3. If using a profile, confirm the installation control image exists. The
51
+ profile control image is copied from that source before live commands.
52
+ 4. Try `node ./dist/index.js --version-check` from a local build to separate MCP
53
+ client setup from Launcher startup.
54
+
55
+ ## Profile Configuration Is Refused
56
+
57
+ When `PHARO_LAUNCHER_MCP_STATE_ROOT` is set, the profile launcher image and
58
+ generated Launcher configuration must be inside that state root.
59
+
60
+ Use a state-root layout:
61
+
62
+ ```text
63
+ <state-root>/launcher/PharoLauncher.image
64
+ <state-root>/launcher/pharo-launcher-cli-config.ston
65
+ <state-root>/images
66
+ <state-root>/vms
67
+ <state-root>/templates
68
+ <state-root>/init-scripts
69
+ <state-root>/logs
70
+ ```
71
+
72
+ Or provide a complete explicit profile without relying on `stateRoot`. See
73
+ [Profile mode](user/profile-mode.md).
74
+
75
+ ## Template List Fails In Profile Mode
76
+
77
+ Run:
78
+
79
+ ```text
80
+ pharo_launcher_template_update
81
+ pharo_launcher_inventory
82
+ ```
83
+
84
+ `template_update` seeds the active profile source list when Launcher leaves it
85
+ missing or empty, then probes `template list`. Inventory diagnostics report
86
+ missing profile directories, missing configuration files, and failed probes.
87
+
88
+ ## Image Create Or Copy Reports An Error After Launcher Succeeds
89
+
90
+ Create and copy tools verify the target image after the command exits. The MCP
91
+ result is an error when the target image cannot be listed and inspected.
92
+
93
+ Check:
94
+
95
+ - the `createVerification` or `copyVerification` section
96
+ - `raw.stdout` and `raw.stderr`
97
+ - whether the image name already existed
98
+ - whether the active profile points at the expected images directory
99
+ - whether the Launcher template source list is valid
100
+
101
+ For copied images, the result also reports metadata repair and inspected image
102
+ metadata when available.
103
+
104
+ ## Process List Or Kill Does Not See A Process
105
+
106
+ Process tools use native host process queries:
107
+
108
+ - Windows: PowerShell/CIM
109
+ - macOS and Linux: `ps -axo pid=,args=`
110
+
111
+ The process must have a Pharo or Squeak command line that includes a `.image`
112
+ path. For cleanup, prefer a PID captured from the detached launch result. If
113
+ using `imageName`, confirm that no unrelated process command line contains the
114
+ same text.
115
+
116
+ ## Commands Time Out
117
+
118
+ Every Launcher command is bounded by a timeout. Timeout results include:
119
+
120
+ - `command.timedOut: true`
121
+ - `command.timeoutReason`
122
+ - command args
123
+ - raw stdout/stderr captured before the timeout
124
+
125
+ A timeout does not authorize broader host cleanup. Cleanup should use only
126
+ recorded image names, profile roots, and PIDs that the caller owns.
127
+
128
+ ## Profile `create_from_build` Is Refused
129
+
130
+ Profile-scoped `pharo_launcher_image_create_from_build` is refused before
131
+ Launcher starts. That Launcher path can automatically launch the image and may
132
+ download or use VMs outside `PHARO_LAUNCHER_MCP_VMS_DIR`.
133
+
134
+ Use a non-`fromBuild` creation path with explicit launch control, or run the
135
+ operation outside profile mode when using the normal Launcher state is intended.