werkmeister-core 0.93.11 → 0.94.1

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/CHANGELOG.md CHANGED
@@ -1,5 +1,27 @@
1
1
  # sandbox-core
2
2
 
3
+ ## 0.94.1
4
+
5
+ ### Patch Changes
6
+
7
+ - 03c1389: Generated `.werkmeister/pr-rules.md` no longer names Changesets outside the two places that explain changesets-only behaviour: the release-bot example, the merged-PR release note and the quoted `skip_release` example now say "release entry". The repo-agnostic test now checks every markdown file `workspace init` writes (skills, `_shared/`, `CLAUDE.md`), not only the stage contracts.
8
+ - 448cb50: `werkmeister-context.md` § Test commands now prints the test of a container that holds the real `~/.werkmeister` or the docker socket, and mounts the workspace folder at its host path, under the temp HOME: `docker exec -w /app <container> <ws>/.werkmeister/bin/with-temp-home --no-wait sh -c '…'`, as its Validation text requires. Other containers (a docker.sock-only one cannot see `<ws>/.werkmeister/bin`) keep the bare `docker exec` line, and the allow rules are unchanged. Rerun `werkmeister workspace init` to regenerate the file.
9
+ - db0280e: The implement stage contracts name one way to serve a static HTML page for a browser check (the Chrome tool refuses `file://`): `python3 -I -u -m http.server 0 -b 127.0.0.1 -d <dir>` as a background job, stopped by its task ID, recorded in `exercise.md` as the method.
10
+ - 8223702: The implement stage contracts say the Chrome window does not size below 477 px, and check a narrower width (e.g. 375 px) in a same-origin iframe built with the JS tool: a screenshot plus `scrollWidth === clientWidth` inside the frame.
11
+
12
+ ## 0.94.0
13
+
14
+ ## 0.93.12
15
+
16
+ ### Patch Changes
17
+
18
+ - 034f5e5: `machine migrate` now rewrites a workspace's `with-temp-home` wrapper whenever it differs from the one this CLI writes, even when the workspace's hooks and permission rules are already current. `machine migrate --check` reports such a workspace as stale (SW-416).
19
+ - d8d8593: `machine config --write`, `machine setup` and `machine migrate` now refuse to write the machine config or `env.sh` from inside any container, even with `WERKMEISTER_FEATURE` unset, the same way compose generation has refused since SW-554. The two guards are now one, `refuseInsideContainer`, and `WERKMEISTER_CONFIG_FILE` still lets a scratch run write (SW-572).
20
+ - 28242eb: `WERKMEISTER_CONFIG_FILE` now moves all of werkmeister's state with the config: locks, reconcile state, the issue cache, the daemon's `mcp-token`, its pid and log files, workspace tokens, VS Code terminal pid files and the legacy `slots.json`. Before, these stayed in the real `~/.werkmeister`. A process with a relocated config therefore no longer touches the real home. With the variable unset, every path is the same as before (SW-622).
21
+ - 23a4c40: Once `machine setup` has run on a fresh install, `machine setup --check` no longer fails with "no standards tree". When `overrides.standards_dir` is unset, the standards tree now defaults to `~/.werkmeister/standards`, which `machine setup` creates with a README describing the module layout and never overwrites; before that first run, `--check` names the folder it would create. The old default pointed inside the package, at a folder it never shipped. The "Claude Code standards access" step now offers that folder on the first run too, instead of skipping. A configured `overrides.standards_dir` is unchanged, and setup never creates it (SW-640).
22
+ - 15e1b2a: `generate-certs.sh` now pins its own locale (`LC_ALL=C`; every value it handles is an ASCII hostname), so the certificate step of `machine setup` no longer depends on the caller's locale. When the script fails, it prints the line that failed and its exit code, and setup's step points at that line instead of reporting only the exit code (SW-642).
23
+ - a962638: `machine setup` no longer installs the ponytail plugin on every machine. Like superpowers, it is now an optional plugin, and the wizard asks about each optional plugin separately. A machine that already has ponytail keeps it, setup keeps it current, and `machine setup --check` does not report it either way (SW-643).
24
+
3
25
  ## 0.93.11
4
26
 
5
27
  ### Patch Changes
@@ -14,6 +14,13 @@
14
14
  * touches the raw fields.
15
15
  */
16
16
  import { type Archetype, type ArchetypeRegistry, type ReposConfig, type ServiceEntry, type ServicesConfig } from "./config.js";
17
+ /**
18
+ * True when one of *entry*'s host binds is a docker socket (any path ending `docker.sock`, e.g. OrbStack's)
19
+ * or the werkmeister home, or a parent of either.
20
+ */
21
+ export declare function hostAccess(entry: ServiceEntry | undefined): boolean;
22
+ /** True when *entry*'s container sees host path *p* at the same path (one of its binds covers it). */
23
+ export declare function seesHostPath(entry: ServiceEntry | undefined, p: string): boolean;
17
24
  /**
18
25
  * Return the normalized archetype dict for one service definition.
19
26
  *
@@ -43,7 +50,7 @@ export declare function serviceNoTests(svcDef: ServiceEntry | null | undefined):
43
50
  * worktree's `node_modules` live. werkmeister-context.md and the workspace's
44
51
  * `permissions.allow` rule both use it, so the rule matches what the agent runs.
45
52
  */
46
- export declare function containerTestCommand(feature: string, svc: string, cmd: string): string;
53
+ export declare function containerTestCommand(feature: string, svc: string, cmd: string, tempHome?: string): string;
47
54
  /** True when *cmd* is simple commands joined only by `&&`: no group, pipe, `||`, `;`, `&`, newline or substitution. */
48
55
  export declare function isPlainChain(cmd: string): boolean;
49
56
  /**
@@ -13,7 +13,36 @@
13
13
  * Everything downstream reads through `resolveServiceArchetype` and never
14
14
  * touches the raw fields.
15
15
  */
16
- import { loadArchetypes, } from "./config.js";
16
+ import * as fs from "node:fs";
17
+ import * as path from "node:path";
18
+ import { expandUser, loadArchetypes, sandboxHome, } from "./config.js";
19
+ const realPath = (p) => {
20
+ try {
21
+ return fs.realpathSync(p);
22
+ }
23
+ catch {
24
+ return path.resolve(p);
25
+ }
26
+ };
27
+ /** Host sources of *entry*'s bind mounts (named volumes skipped), symlinks resolved (`/var` → `/private/var` on macOS). */
28
+ const hostBinds = (entry) => (entry?.extra_volumes ?? [])
29
+ .map((spec) => spec.split(":")[0])
30
+ .filter((src) => src.includes("/"))
31
+ .map((src) => realPath(expandUser(src)));
32
+ const within = (p, dir) => p === dir || p.startsWith(`${dir}${path.sep}`) || dir === "/";
33
+ /**
34
+ * True when one of *entry*'s host binds is a docker socket (any path ending `docker.sock`, e.g. OrbStack's)
35
+ * or the werkmeister home, or a parent of either.
36
+ */
37
+ export function hostAccess(entry) {
38
+ const targets = ["/var/run/docker.sock", sandboxHome()].map(realPath);
39
+ return hostBinds(entry).some((host) => path.basename(host) === "docker.sock" || targets.some((t) => within(t, host)));
40
+ }
41
+ /** True when *entry*'s container sees host path *p* at the same path (one of its binds covers it). */
42
+ export function seesHostPath(entry, p) {
43
+ const target = realPath(p);
44
+ return hostBinds(entry).some((host) => within(target, host));
45
+ }
17
46
  function isDict(value) {
18
47
  return typeof value === "object" && value !== null && !Array.isArray(value);
19
48
  }
@@ -80,8 +109,12 @@ export function serviceNoTests(svcDef) {
80
109
  * worktree's `node_modules` live. werkmeister-context.md and the workspace's
81
110
  * `permissions.allow` rule both use it, so the rule matches what the agent runs.
82
111
  */
83
- export function containerTestCommand(feature, svc, cmd) {
84
- return `docker exec ${feature}-${svc} sh -c '${cmd.split("'").join(`'\\''`)}'`;
112
+ export function containerTestCommand(feature, svc, cmd, tempHome) {
113
+ const quoted = `sh -c '${cmd.split("'").join(`'\\''`)}'`;
114
+ // SW-769: a container holding the real ~/.werkmeister runs its tests under a temp HOME, as Validation says.
115
+ return tempHome
116
+ ? `docker exec -w /app ${feature}-${svc} ${tempHome} --no-wait ${quoted}`
117
+ : `docker exec ${feature}-${svc} ${quoted}`;
85
118
  }
86
119
  /** True when *cmd* is simple commands joined only by `&&`: no group, pipe, `||`, `;`, `&`, newline or substitution. */
87
120
  export function isPlainChain(cmd) {
package/dist/cache.js CHANGED
@@ -19,11 +19,10 @@
19
19
  * at worst re-fetches one key). Go SQLite only if entries reach the thousands.
20
20
  */
21
21
  import { promises as fs } from "node:fs";
22
- import os from "node:os";
23
22
  import path from "node:path";
24
- import { dotDir, envVar } from "./config.js";
23
+ import { envVar, sandboxHome } from "./config.js";
25
24
  function cacheFilePath() {
26
- return envVar("CACHE_FILE") || path.join(dotDir(os.homedir()), "issue-cache.json");
25
+ return envVar("CACHE_FILE") || path.join(sandboxHome(), "issue-cache.json");
27
26
  }
28
27
  async function readStore() {
29
28
  try {
@@ -5,10 +5,8 @@
5
5
  * Built-in `fetch` only — this ships inside the extension bundle.
6
6
  */
7
7
  import * as fs from "node:fs";
8
- import * as os from "node:os";
9
8
  import * as path from "node:path";
10
- import { envVar } from "./config.js";
11
- import { dotDir } from "./dot_dir.js";
9
+ import { envVar, sandboxHome } from "./config.js";
12
10
  import { SandboxError } from "./errors.js";
13
11
  import { load } from "./global_config.js";
14
12
  import { warn } from "./reporter.js";
@@ -50,7 +48,7 @@ function readToken(file) {
50
48
  export function daemonToken(workspaceRoot) {
51
49
  return (envVar("MCP_TOKEN") ||
52
50
  (workspaceRoot ? readToken(workspaceTokenFile(workspaceRoot)) : null) ||
53
- readToken(path.join(dotDir(os.homedir()), "mcp-token")));
51
+ readToken(path.join(sandboxHome(), "mcp-token")));
54
52
  }
55
53
  /**
56
54
  * Thrown when the werkmeister daemon is not reachable: nothing is listening at {@link daemonUrl},
@@ -36,14 +36,6 @@ export declare function loadWorkspaceEnvVars(workspaceRoot: string): Record<stri
36
36
  * start one for a repo with no container running.
37
37
  */
38
38
  export declare function onDemandServices(servicesConfig: Record<string, unknown>, localServices: string[], workspaceRoot: string): string[];
39
- /**
40
- * SW-554: the host's Docker reads the compose file, but inside a container `sandboxRoot()`
41
- * is the container's /app, so the install's script mount would name a path the host lacks
42
- * and the install would run an empty script and exit 0. `WERKMEISTER_FEATURE` cannot be the
43
- * test (a caller may unset it); Docker's marker is. A relocated config is a scratch run, as
44
- * for the machine config (SW-354).
45
- */
46
- export declare function refuseComposeInsideContainer(dockerenv?: string): void;
47
39
  /**
48
40
  * Generate `<workspace>/compose.yml` for *feature*.
49
41
  *
package/dist/generate.js CHANGED
@@ -18,9 +18,9 @@ import { candidateServiceNames } from "./archetypes.js";
18
18
  import { applyCaches } from "./build_caches.js";
19
19
  import { projectName } from "./compose.js";
20
20
  import { COMPOSE_FILE, migrateWorkspaceCompose } from "./compose_file.js";
21
- import { baselineUpstream, containerOf, DEFAULT_CPUS, DEFAULT_SETUP_CPUS, dotDir, envVar, IDLE_SERVICE_TYPES, infraRoot, loadArchetypes, loadCaches, loadPorts, loadReposConfig, loadServices, loadSetupServices, resolveWorkspace, SHARED_VOLUME_MARKER, sandboxRoot, stateInfraRoot, } from "./config.js";
22
- import { SandboxError } from "./errors.js";
21
+ import { baselineUpstream, containerOf, DEFAULT_CPUS, DEFAULT_SETUP_CPUS, dotDir, IDLE_SERVICE_TYPES, infraRoot, loadArchetypes, loadCaches, loadPorts, loadReposConfig, loadServices, loadSetupServices, resolveWorkspace, SHARED_VOLUME_MARKER, sandboxRoot, stateInfraRoot, } from "./config.js";
23
22
  import { loadFeatureRouters } from "./feature_routing.js";
23
+ import { refuseInsideContainer } from "./global_config.js";
24
24
  import { buildSandboxContextMd } from "./harness/claude/claude_md.js";
25
25
  import { sandboxLock } from "./locks.js";
26
26
  import { workspaceServices } from "./registry_sync.js";
@@ -728,27 +728,13 @@ function renderFeatureCompose(feature, slot, localServices, config, workspaceOve
728
728
  const body = YAML.stringify(compose, { indentSeq: false, singleQuote: true });
729
729
  return [outPath, header + body, "built-in"];
730
730
  }
731
- /**
732
- * SW-554: the host's Docker reads the compose file, but inside a container `sandboxRoot()`
733
- * is the container's /app, so the install's script mount would name a path the host lacks
734
- * and the install would run an empty script and exit 0. `WERKMEISTER_FEATURE` cannot be the
735
- * test (a caller may unset it); Docker's marker is. A relocated config is a scratch run, as
736
- * for the machine config (SW-354).
737
- */
738
- export function refuseComposeInsideContainer(dockerenv = "/.dockerenv") {
739
- if (fs.existsSync(dockerenv) && !envVar("CONFIG_FILE")) {
740
- throw new SandboxError(`Refusing to write ${COMPOSE_FILE} from inside a container: the host's Docker reads it, ` +
741
- `and the werkmeister root here is the container's (${sandboxRoot()}).\n` +
742
- " Run it from the host, or set WERKMEISTER_CONFIG_FILE to a scratch file.", "INSIDE_CONTAINER");
743
- }
744
- }
745
731
  /**
746
732
  * Generate `<workspace>/compose.yml` for *feature*.
747
733
  *
748
734
  * Returns the path to the generated workspace compose file.
749
735
  */
750
736
  export function generateFeatureCompose(feature, slot, localServices, config = null, workspaceOverride = null, source = "werkmeister CLI") {
751
- refuseComposeInsideContainer();
737
+ refuseInsideContainer(COMPOSE_FILE);
752
738
  const [outPath, content, kind] = renderFeatureCompose(feature, slot, localServices, config, workspaceOverride, source);
753
739
  fs.writeFileSync(outPath, content);
754
740
  success(`Generated compose (${kind}): ${outPath}`);
@@ -783,7 +769,7 @@ export const GATE_COMPOSE_FILE = "compose.gate.yml";
783
769
  * compose.yml's: their running containers lack the branch's container settings (SW-118).
784
770
  */
785
771
  export function renderGateCompose(feature, slot, localServices, services, workspace) {
786
- refuseComposeInsideContainer();
772
+ refuseInsideContainer(COMPOSE_FILE);
787
773
  const [outPath, content] = renderFeatureCompose(feature, slot, localServices, { services }, workspace, "werkmeister pr gate");
788
774
  const gate = YAML.parse(content)?.services ?? {};
789
775
  const current = YAML.parse(fs.readFileSync(outPath, "utf8"))?.services ?? {};
@@ -51,26 +51,24 @@ export { configPath, modelPricingYamlPath, portsYamlPath, sandboxHome, servicesL
51
51
  export declare function envShPath(): string;
52
52
  /**
53
53
  * Root of the code-standards source tree (`overrides.standards_dir` →
54
- * `<werkmeister root>/docs/standards`).
54
+ * `~/.werkmeister/standards`).
55
55
  *
56
56
  * The standards are one organization's *content*; the CLI is a reusable tool.
57
57
  * This is the seam between them — point it at any directory laid out the way
58
58
  * `loadStandardsModules` expects and `werkmeister standards check` gates it there
59
- * too. Unlike the registry files above it has no `~/.werkmeister` default: the
60
- * bundled tree ships with the checkout, so an unconfigured install keeps
61
- * working.
59
+ * too. The default sits beside the registry files, outside the package: the
60
+ * tree must stay writable (`notes graduate` commits into it) and survive an
61
+ * upgrade, and `machine setup` seeds it (SW-640).
62
62
  */
63
63
  export declare function standardsDirPath(): string;
64
64
  /**
65
65
  * Describe why the standards tree is unusable, or "" when it is fine.
66
66
  *
67
- * The fallback above is a convention (a tree bundled beside the CLI), not a
68
- * promise — this repo no longer ships one, so an unconfigured install resolves
69
- * a directory that does not exist. The loader treats that as "no modules" and
70
- * carries on, which is right for a hook that must never block a launch and
71
- * wrong for anything a human is watching: a workspace inits with an empty
72
- * routing table and no standards skills, and nothing says so. Every
73
- * human-facing entry point reports this; the fail-open paths still don't.
67
+ * A missing tree reads as "no modules" to the loader, which carries on: right
68
+ * for a hook that must never block a launch, wrong for anything a human is
69
+ * watching (a workspace inits with an empty routing table and no standards
70
+ * skills, and nothing says so). Every human-facing entry point reports this;
71
+ * the fail-open paths still don't.
74
72
  */
75
73
  export declare function standardsDirProblem(): string;
76
74
  /**
@@ -191,12 +189,21 @@ export declare const _GITHUB_ORG_PROMPT: PromptSpec;
191
189
  /** Ingress prompts — driven by `werkmeister machine setup`, alongside `_CONFIG_PROMPTS`. */
192
190
  export declare const _INGRESS_PROMPTS: readonly PromptSpec[];
193
191
  /**
194
- * True inside any workspace container: compose exports `WERKMEISTER_FEATURE`
195
- * (`SANDBOX_FEATURE` before SW-106) and Docker writes `/.dockerenv`. The
196
- * feature-agnostic twin of `lifecycle.ts` `insideOwnContainer`, kept here so the
197
- * config layer does not import compose, docker and k8s.
192
+ * True inside any container: Docker writes `/.dockerenv`. Not the feature env
193
+ * (`WERKMEISTER_FEATURE`): a caller can unset it, and another workspace's
194
+ * container or a devcontainer lacks it (SW-554, SW-572).
198
195
  */
199
- export declare function insideContainer(env?: NodeJS.ProcessEnv, dockerenv?: string): boolean;
196
+ export declare function insideContainer(dockerenv?: string): boolean;
197
+ /**
198
+ * Refuse to write a host file from inside a container. A workspace container
199
+ * runs with HOME set to the host home and the host's `~/.werkmeister`
200
+ * bind-mounted read-write, and its werkmeister root is the container's /app: a
201
+ * machine config written there pins the host to /app (SW-354), and a compose.yml
202
+ * names /app paths the host's Docker lacks (SW-554). A relocated config
203
+ * (`WERKMEISTER_CONFIG_FILE`) is a scratch run and writes, and so is a file
204
+ * under the container's own temp dir (a temp-HOME test, e.g. `machine migrate`).
205
+ */
206
+ export declare function refuseInsideContainer(file: string, dockerenv?: string): void;
200
207
  /** Write the config YAML (creating ~/.werkmeister/ as needed). */
201
208
  export declare function save(cfg: GlobalConfig): string;
202
209
  /** Render the `export WERKMEISTER_*=…` shell text from the config. */
@@ -24,7 +24,7 @@ import * as fs from "node:fs";
24
24
  import * as os from "node:os";
25
25
  import * as path from "node:path";
26
26
  import * as YAML from "yaml";
27
- import { configPath, dotDir, envVar, expandUser, loadConfig, modelPricingYamlPath, portsYamlPath, sandboxHome, sandboxRoot, servicesLocalYamlPath, servicesYamlPath, } from "./config.js";
27
+ import { configPath, DOT_DIR, envVar, expandUser, loadConfig, modelPricingYamlPath, portsYamlPath, sandboxHome, servicesLocalYamlPath, servicesYamlPath, } from "./config.js";
28
28
  import { SandboxError } from "./errors.js";
29
29
  // biome-ignore lint/suspicious/noImportCycles: global_config↔projects; SW-411
30
30
  import { projectProblems } from "./projects.js";
@@ -53,32 +53,30 @@ export function envShPath() {
53
53
  // Those exports (see _ENV_MAP) remain as the fallback for a shell.
54
54
  /**
55
55
  * Root of the code-standards source tree (`overrides.standards_dir` →
56
- * `<werkmeister root>/docs/standards`).
56
+ * `~/.werkmeister/standards`).
57
57
  *
58
58
  * The standards are one organization's *content*; the CLI is a reusable tool.
59
59
  * This is the seam between them — point it at any directory laid out the way
60
60
  * `loadStandardsModules` expects and `werkmeister standards check` gates it there
61
- * too. Unlike the registry files above it has no `~/.werkmeister` default: the
62
- * bundled tree ships with the checkout, so an unconfigured install keeps
63
- * working.
61
+ * too. The default sits beside the registry files, outside the package: the
62
+ * tree must stay writable (`notes graduate` commits into it) and survive an
63
+ * upgrade, and `machine setup` seeds it (SW-640).
64
64
  */
65
65
  export function standardsDirPath() {
66
66
  const override = load()["overrides"]?.["standards_dir"];
67
67
  if (override) {
68
68
  return path.resolve(expandUser(String(override)));
69
69
  }
70
- return path.join(sandboxRoot(), "docs", "standards");
70
+ return path.join(sandboxHome(), "standards");
71
71
  }
72
72
  /**
73
73
  * Describe why the standards tree is unusable, or "" when it is fine.
74
74
  *
75
- * The fallback above is a convention (a tree bundled beside the CLI), not a
76
- * promise — this repo no longer ships one, so an unconfigured install resolves
77
- * a directory that does not exist. The loader treats that as "no modules" and
78
- * carries on, which is right for a hook that must never block a launch and
79
- * wrong for anything a human is watching: a workspace inits with an empty
80
- * routing table and no standards skills, and nothing says so. Every
81
- * human-facing entry point reports this; the fail-open paths still don't.
75
+ * A missing tree reads as "no modules" to the loader, which carries on: right
76
+ * for a hook that must never block a launch, wrong for anything a human is
77
+ * watching (a workspace inits with an empty routing table and no standards
78
+ * skills, and nothing says so). Every human-facing entry point reports this;
79
+ * the fail-open paths still don't.
82
80
  */
83
81
  export function standardsDirProblem() {
84
82
  const dir = standardsDirPath();
@@ -390,24 +388,28 @@ const _HEADER = "# Global werkmeister configuration — single source of truth.\
390
388
  "# Managed by `werkmeister machine config`; safe to hand-edit, then run " +
391
389
  "`werkmeister machine config --check`.\n";
392
390
  /**
393
- * True inside any workspace container: compose exports `WERKMEISTER_FEATURE`
394
- * (`SANDBOX_FEATURE` before SW-106) and Docker writes `/.dockerenv`. The
395
- * feature-agnostic twin of `lifecycle.ts` `insideOwnContainer`, kept here so the
396
- * config layer does not import compose, docker and k8s.
391
+ * True inside any container: Docker writes `/.dockerenv`. Not the feature env
392
+ * (`WERKMEISTER_FEATURE`): a caller can unset it, and another workspace's
393
+ * container or a devcontainer lacks it (SW-554, SW-572).
397
394
  */
398
- export function insideContainer(env = process.env, dockerenv = "/.dockerenv") {
399
- return Boolean(env.WERKMEISTER_FEATURE ?? env.SANDBOX_FEATURE) && fs.existsSync(dockerenv);
395
+ export function insideContainer(dockerenv = "/.dockerenv") {
396
+ return fs.existsSync(dockerenv);
400
397
  }
401
398
  /**
402
- * SW-354: a workspace container runs with HOME set to the host home and the
403
- * host's `~/.werkmeister` bind-mounted read-write, so writing the default config
404
- * from inside pins the host's werkmeister_root to the container's /app. A
405
- * relocated config (`WERKMEISTER_CONFIG_FILE`, what every test sets) is still written.
399
+ * Refuse to write a host file from inside a container. A workspace container
400
+ * runs with HOME set to the host home and the host's `~/.werkmeister`
401
+ * bind-mounted read-write, and its werkmeister root is the container's /app: a
402
+ * machine config written there pins the host to /app (SW-354), and a compose.yml
403
+ * names /app paths the host's Docker lacks (SW-554). A relocated config
404
+ * (`WERKMEISTER_CONFIG_FILE`) is a scratch run and writes, and so is a file
405
+ * under the container's own temp dir (a temp-HOME test, e.g. `machine migrate`).
406
406
  */
407
- function refuseInsideContainer(file) {
408
- if (insideContainer() && !envVar("CONFIG_FILE")) {
409
- throw new SandboxError(`Refusing to write ${file} from inside a workspace container: it is the host's ` +
410
- "machine config, bind-mounted here, and the running checkout is the container's /app.\n" +
407
+ export function refuseInsideContainer(file, dockerenv = "/.dockerenv") {
408
+ // Absolute only: compose callers pass the bare name, which must not resolve against a /tmp cwd.
409
+ const scratch = path.isAbsolute(file) && file.startsWith(os.tmpdir() + path.sep);
410
+ if (insideContainer(dockerenv) && !envVar("CONFIG_FILE") && !scratch) {
411
+ throw new SandboxError(`Refusing to write ${file} from inside a container: the host's werkmeister reads it, ` +
412
+ "and the werkmeister root here is the container's /app.\n" +
411
413
  " Run it from the host, or set WERKMEISTER_CONFIG_FILE to a scratch file.", "INSIDE_CONTAINER");
412
414
  }
413
415
  }
@@ -503,7 +505,8 @@ export function writeEnvSh(cfg) {
503
505
  // ~/.zshenv managed block
504
506
  // ---------------------------------------------------------------------------
505
507
  function managedBlock() {
506
- const home = path.basename(dotDir(os.homedir()));
508
+ // The shell reads it at login, before any WERKMEISTER_CONFIG_FILE: the default home's name.
509
+ const home = DOT_DIR;
507
510
  return (`${_ZSH_BEGIN}\n` +
508
511
  "# Managed by `werkmeister machine config` — do not edit; regenerated on `werkmeister machine config`.\n" +
509
512
  `[ -f "$HOME/${home}/env.sh" ] && . "$HOME/${home}/env.sh"\n` +
@@ -11,7 +11,7 @@
11
11
  */
12
12
  import * as fs from "node:fs";
13
13
  import * as path from "node:path";
14
- import { containerTestCommand, serviceNoTests, serviceTestCommand, validationRows, wrappedTestCommand, } from "../../archetypes.js";
14
+ import { containerTestCommand, hostAccess, seesHostPath, serviceNoTests, serviceTestCommand, validationRows, wrappedTestCommand, } from "../../archetypes.js";
15
15
  import { cacheSource } from "../../build_caches.js";
16
16
  import { baselineUpstream, loadArchetypes, loadCaches, } from "../../config.js";
17
17
  import { ingressHostnames, loadFeatureRouters } from "../../feature_routing.js";
@@ -255,13 +255,15 @@ Hit a bug, or need to log a feature or task, in the \`werkmeister\` tool or a re
255
255
  // ---------------------------------------------------------------------------
256
256
  // werkmeister-context.md generation
257
257
  // ---------------------------------------------------------------------------
258
- function testCommandLine(feature, svc, servicesConfig, archetypes, lint) {
258
+ // SW-769: wrap where the real ~/.werkmeister is at risk, but only if the container sees <ws> (a docker.sock-only one would exit 127).
259
+ const withTempHome = (entry, tempHome) => tempHome && hostAccess(entry) && seesHostPath(entry, tempHome) ? tempHome : "";
260
+ function testCommandLine(feature, svc, servicesConfig, archetypes, lint, tempHome = "") {
259
261
  const cmd = serviceTestCommand(svc, servicesConfig[svc], archetypes);
260
262
  const noTests = serviceNoTests(servicesConfig[svc]);
261
263
  if (noTests)
262
264
  return `- \`${svc}\`: no tests (registry: ${noTests})`;
263
265
  return cmd
264
- ? `- \`${svc}\`: \`${containerTestCommand(feature, svc, lint ? `${lint} && ${cmd}` : cmd)}\``
266
+ ? `- \`${svc}\`: \`${containerTestCommand(feature, svc, lint ? `${lint} && ${cmd}` : cmd, withTempHome(servicesConfig[svc], tempHome))}\``
265
267
  : `- \`${svc}\`: no test command registered (add \`test:\` to its registry entry)`;
266
268
  }
267
269
  /** SW-720: in sw-700 host `node`, a compound line and `docker exec … node <script>` were each denied before this form ran. */
@@ -463,7 +465,7 @@ The registry's \`test:\` for each service (or its archetype's), run in its conta
463
465
  ? " A line starting with `<lint> &&` first runs the repo's lint, the PR gate's lint row, so a `docs:check` or format failure shows here, before the tests, and not first at the gate."
464
466
  : ""}
465
467
 
466
- ${svcs.map((s, i) => testCommandLine(feature, s, servicesConfig, archetypes ?? loadArchetypes(), svcLint[i])).join("\n")}
468
+ ${svcs.map((s, i) => testCommandLine(feature, s, servicesConfig, archetypes ?? loadArchetypes(), svcLint[i], tempHome)).join("\n")}
467
469
  ${sharedCachesLine(caches)}
468
470
  `;
469
471
  }
@@ -44,8 +44,8 @@
44
44
  import * as fs from "node:fs";
45
45
  import * as path from "node:path";
46
46
  import { parse as parseYaml } from "yaml";
47
- import { candidateServiceNames, containerTestCommand, isPlainChain, serviceTestCommand, wrappedTestCommand, } from "../../archetypes.js";
48
- import { dotDir, expandUser, getReposRoot, loadArchetypes, loadReposConfig, loadServices, sandboxHome, sandboxRoot, } from "../../config.js";
47
+ import { candidateServiceNames, containerTestCommand, hostAccess, isPlainChain, serviceTestCommand, wrappedTestCommand, } from "../../archetypes.js";
48
+ import { dotDir, getReposRoot, loadArchetypes, loadReposConfig, loadServices, sandboxRoot, } from "../../config.js";
49
49
  import { frozenInstalls } from "../../fragment_detect/workspace.js";
50
50
  import { load as loadGlobalConfig } from "../../global_config.js";
51
51
  import { workspaceServices } from "../../registry_sync.js";
@@ -464,30 +464,6 @@ hostServices = [], reposConfig = {}) {
464
464
  .map((r) => `${wrapped}--no-wait ${r.slice(wrapped.length)}`));
465
465
  return [...new Set([...rules, ...READ_ONLY_GIT_RULES])];
466
466
  }
467
- /**
468
- * True when one of *entry*'s host binds is a docker socket (any path ending `docker.sock`, e.g. OrbStack's)
469
- * or the werkmeister home, or a parent of either; symlinks resolved (`/var` → `/private/var` on macOS).
470
- */
471
- function hostAccess(entry) {
472
- const real = (p) => {
473
- try {
474
- return fs.realpathSync(p);
475
- }
476
- catch {
477
- return path.resolve(p);
478
- }
479
- };
480
- const targets = ["/var/run/docker.sock", sandboxHome()].map(real);
481
- return (entry?.extra_volumes ?? []).some((spec) => {
482
- const src = spec.split(":")[0];
483
- if (!src.includes("/"))
484
- return false; // a named volume
485
- const host = real(expandUser(src));
486
- if (path.basename(host) === "docker.sock")
487
- return true;
488
- return targets.some((t) => t === host || t.startsWith(`${host}${path.sep}`) || host === "/");
489
- });
490
- }
491
467
  /**
492
468
  * SW-845: *registry* with each entry's `extra_volumes` widened to every bind compose mounts: the
493
469
  * branch's own fragment and the workspace's `dev_links` too (both agent-editable), variables
package/dist/locks.js CHANGED
@@ -27,11 +27,10 @@
27
27
  * insufficient.
28
28
  */
29
29
  import * as fs from "node:fs";
30
- import * as os from "node:os";
31
30
  import * as path from "node:path";
32
31
  import { setTimeout as sleep } from "node:timers/promises";
33
- import { dotDir } from "./config.js";
34
- const lockDir = () => path.join(dotDir(os.homedir()), "locks");
32
+ import { sandboxHome } from "./config.js";
33
+ const lockDir = () => path.join(sandboxHome(), "locks");
35
34
  // Poll interval (seconds) for the retry loop.
36
35
  const _RETRY_INTERVAL = 0.1;
37
36
  /** True when the PID recorded in the lock file no longer belongs to a live process. */
@@ -14,11 +14,9 @@
14
14
  * this repo serves at `.claude-plugin/marketplace.json`) — carries the
15
15
  * ops skills. An install of its old name (`sandbox-tools@sandbox`) is // name-check: ignore
16
16
  * swapped out once the new one is in;
17
- * * the **ponytail plugin** (user scope) — the w9r-* entry skills reference
18
- * it, with graceful fallback, so absence degrades rather than breaks;
19
- * * the **superpowers plugin** (user scope, OPTIONAL) — installed only when
20
- * the wizard asks and the answer is yes. Nothing references it, so a
21
- * decline is reported ok rather than as drift;
17
+ * * the **optional plugins** (user scope: superpowers, ponytail) — each
18
+ * installed only when the wizard asks and the answer is yes, then kept
19
+ * current. A decline is reported ok rather than as drift;
22
20
  * * the **companion sandbox-workspace checkout** under the repos root —
23
21
  * `werkmeister workspace new` creates each workspace root as a worktree of it
24
22
  * (plain-directory fallback with a warning when it is missing). Which repo
@@ -500,8 +498,8 @@ export interface RunSetupOptions {
500
498
  skipSudo?: boolean;
501
499
  /** Install Telepresence via Homebrew when it is missing or stale. */
502
500
  installTelepresence?: boolean;
503
- /** Install the optional plugins (superpowers) when they are missing. */
504
- installOptionalPlugins?: boolean;
501
+ /** Names from OPTIONAL_PLUGINS to install when missing (the wizard asks for each). */
502
+ optionalPlugins?: readonly string[];
505
503
  /** Map the werkmeister YAML schemas in VS Code's user settings (the wizard asks first). */
506
504
  mapEditorSchemas?: boolean;
507
505
  /** Install the bundled Werkmeister Workspaces VS Code extension (the wizard asks first). */
@@ -14,11 +14,9 @@
14
14
  * this repo serves at `.claude-plugin/marketplace.json`) — carries the
15
15
  * ops skills. An install of its old name (`sandbox-tools@sandbox`) is // name-check: ignore
16
16
  * swapped out once the new one is in;
17
- * * the **ponytail plugin** (user scope) — the w9r-* entry skills reference
18
- * it, with graceful fallback, so absence degrades rather than breaks;
19
- * * the **superpowers plugin** (user scope, OPTIONAL) — installed only when
20
- * the wizard asks and the answer is yes. Nothing references it, so a
21
- * decline is reported ok rather than as drift;
17
+ * * the **optional plugins** (user scope: superpowers, ponytail) — each
18
+ * installed only when the wizard asks and the answer is yes, then kept
19
+ * current. A decline is reported ok rather than as drift;
22
20
  * * the **companion sandbox-workspace checkout** under the repos root —
23
21
  * `werkmeister workspace new` creates each workspace root as a worktree of it
24
22
  * (plain-directory fallback with a warning when it is missing). Which repo
@@ -55,12 +53,12 @@ import * as path from "node:path";
55
53
  import { applyEdits, modify, parse as parseJsonc } from "jsonc-parser";
56
54
  import { expandUser, getReposRoot, isFixture, sandboxHome, sandboxRoot, servicesLocalYamlPath, } from "./config.js";
57
55
  import { daemonUrl } from "./daemon_client.js";
58
- import { configPath, loadIngress, loadJira, loadPaths as loadPathsSection, loadWorkspaceRepo, modelPricingYamlPath, portsYamlPath, secretsPath, standardsDirPath, } from "./global_config.js";
56
+ import { configPath, load, loadIngress, loadJira, loadPaths as loadPathsSection, loadWorkspaceRepo, modelPricingYamlPath, portsYamlPath, secretsPath, standardsDirPath, } from "./global_config.js";
59
57
  import { JIRA_PLACEHOLDERS } from "./jira-rest.js";
60
58
  import { LEGACY_PLUGIN_NAME, PLUGIN_NAME, pluginDriftWarnings } from "./plugin_check.js";
61
59
  import { ProcError, run } from "./proc.js";
62
60
  import { syncRegistry } from "./registry_sync.js";
63
- import { DEFAULT_MODEL_PRICING_YAML, DEFAULT_PORTS_YAML, renderSecretsEnv, renderServicesLocalYaml, seedFile, } from "./scaffold.js";
61
+ import { DEFAULT_MODEL_PRICING_YAML, DEFAULT_PORTS_YAML, renderSecretsEnv, renderServicesLocalYaml, STANDARDS_README, seedFile, } from "./scaffold.js";
64
62
  import { BREW_FORMULA, DOWNLOAD_HINT, INSTALL_HINT, MIN_VERSION, parseVersion, versionLt, } from "./telepresence.js";
65
63
  import { PLAYWRIGHT_VERSION } from "./test_run.js";
66
64
  import { appEntry, DAEMON_LABEL, daemonPlistPath, MCP, stop as stopWebServer, } from "./web_servers.js";
@@ -83,11 +81,6 @@ export const REQUIRED_PLUGINS = [
83
81
  marketplace: "werkmeister",
84
82
  source: "jbbz-sandbox/werkmeister@main",
85
83
  },
86
- {
87
- name: "ponytail",
88
- marketplace: "ponytail",
89
- source: "DietrichGebert/ponytail",
90
- },
91
84
  ];
92
85
  /**
93
86
  * The plugin and marketplace as named before SW-9. Claude Code has no alias for a
@@ -171,6 +164,13 @@ export const OPTIONAL_PLUGINS = [
171
164
  source: "anthropics/claude-plugins-official",
172
165
  note: "brainstorming/planning skills; writes plans under docs/superpowers/",
173
166
  },
167
+ {
168
+ // A coding-style plugin: opt-in, not required (SW-643). A machine that has it keeps it current.
169
+ name: "ponytail",
170
+ marketplace: "ponytail",
171
+ source: "DietrichGebert/ponytail",
172
+ note: "smallest-change coding style; the ICM contracts use it when loaded",
173
+ },
174
174
  ];
175
175
  // The workspace ROOT is itself a worktree of this dedicated repo on the same
176
176
  // <user>/<workspace> branch as the repo worktrees inside it. Everything
@@ -711,8 +711,36 @@ export function syncRegistryConfigs(checkOnly, options = {}) {
711
711
  steps.push({ label, ok: false, detail: `could not write ${secrets}: ${e}` });
712
712
  }
713
713
  }
714
+ steps.push(seedStandardsDir(checkOnly));
714
715
  return steps;
715
716
  }
717
+ /**
718
+ * SW-640: seed the default standards tree, so a fresh install has one. A
719
+ * configured `overrides.standards_dir` is the person's to provide: `machine
720
+ * config --check` names it when missing, and this never creates it.
721
+ */
722
+ function seedStandardsDir(checkOnly) {
723
+ const label = "config standards/";
724
+ const dir = standardsDirPath();
725
+ if (load()["overrides"]?.["standards_dir"]) {
726
+ return { label, ok: true, detail: `overrides.standards_dir → ${dir}` };
727
+ }
728
+ if (fs.existsSync(dir))
729
+ return { label, ok: true, detail: `present at ${dir}` };
730
+ if (checkOnly)
731
+ return { label, ok: true, detail: `absent — would create ${dir}` };
732
+ try {
733
+ seedFile(path.join(dir, "README.md"), STANDARDS_README);
734
+ return {
735
+ label,
736
+ ok: true,
737
+ detail: `created ${dir} — add standard modules, or point overrides.standards_dir at a shared tree`,
738
+ };
739
+ }
740
+ catch (e) {
741
+ return { label, ok: false, detail: `could not write ${dir}: ${e}` };
742
+ }
743
+ }
716
744
  // --- TLS certificates for the ingress hostnames -----------------------------
717
745
  /**
718
746
  * Locate `bin/generate-certs.sh`, walking up from the CLI package root.
@@ -794,7 +822,13 @@ export function syncIngressCerts(checkOnly, options, interactive) {
794
822
  }
795
823
  const rc = (interactive ?? defaultInteractiveRunner)(cmd);
796
824
  if (rc !== 0) {
797
- return [{ label, ok: false, detail: `generate-certs.sh failed (exit ${rc})` }];
825
+ return [
826
+ {
827
+ label,
828
+ ok: false,
829
+ detail: `generate-certs.sh failed (exit ${rc}); its failing line is printed above`,
830
+ },
831
+ ];
798
832
  }
799
833
  const detail = `${ingress.certs_dir} covers ${hostnames.join(", ")}`;
800
834
  if (options.skipSudo) {
@@ -1785,7 +1819,7 @@ export async function runSetup(options = {}) {
1785
1819
  steps.push({
1786
1820
  label: "claude CLI",
1787
1821
  ok: false,
1788
- detail: `not found on PATH — the ${PLUGIN_NAME} and ponytail plugins cannot be ` +
1822
+ detail: "not found on PATH — the Claude Code plugins cannot be " +
1789
1823
  "installed without it. Install Claude Code from " +
1790
1824
  "https://claude.com/claude-code (the VS Code extension alone does not " +
1791
1825
  "put `claude` on PATH), then re-run `werkmeister machine setup`.",
@@ -1804,7 +1838,7 @@ export async function runSetup(options = {}) {
1804
1838
  }
1805
1839
  }
1806
1840
  for (const spec of OPTIONAL_PLUGINS) {
1807
- steps.push(...syncOptionalPlugin(spec, claudePluginsDir, runner, checkOnly, options.installOptionalPlugins ?? false));
1841
+ steps.push(...syncOptionalPlugin(spec, claudePluginsDir, runner, checkOnly, options.optionalPlugins?.includes(spec.name) ?? false));
1808
1842
  }
1809
1843
  }
1810
1844
  // Fall back to the gh-derived default so a machine configured before this
package/dist/migrate.js CHANGED
@@ -14,7 +14,7 @@ import * as os from "node:os";
14
14
  import * as path from "node:path";
15
15
  import { parse as parseYaml } from "yaml";
16
16
  import { COMPOSE_FILE, LEGACY_COMPOSE_FILE } from "./compose_file.js";
17
- import { configPath, envVar, expandUser, servicesLocalYamlPath, servicesYamlPath, workspacesRoot, } from "./config.js";
17
+ import { configPath, envVar, expandUser, sandboxHome, servicesLocalYamlPath, servicesYamlPath, workspacesRoot, } from "./config.js";
18
18
  import { docker } from "./docker.js";
19
19
  import { DOT_DIR, dotDir } from "./dot_dir.js";
20
20
  import { writeFixtureWrapper } from "./fixture_workspace.js";
@@ -24,7 +24,7 @@ import { HARNESS_IDS } from "./harness/types.js";
24
24
  import { installPrWatchSchedule, prWatchScheduleState, } from "./machine_setup.js";
25
25
  import { resolveModel } from "./model_tiers.js";
26
26
  import { syncRegistry } from "./registry_sync.js";
27
- import { tempHomeWrapper, writeTempHomeWrapper } from "./temp_home.js";
27
+ import { TEMP_HOME_SCRIPT, tempHomeWrapper, writeTempHomeWrapper } from "./temp_home.js";
28
28
  import { writeWorkspaceConfig } from "./workspace_init.js";
29
29
  import { readModel, readWorkspaceField } from "./workspace_prompts.js";
30
30
  export const LEGACY_DOT_DIR = ".sandbox";
@@ -289,9 +289,8 @@ export async function migrate(opts = {}) {
289
289
  steps.push(...nounGroupSteps(wsRoot, checkOnly), modelStep(wsRoot, checkOnly));
290
290
  return steps;
291
291
  }
292
- // What the CLI wrote with a pre-SW-186 spelling: hook commands and with-temp-home's load wait.
292
+ // What the CLI wrote with a pre-SW-186 spelling: hook commands.
293
293
  const PRE_SW186_HOOK = /werkmeister (?:hooks (?:gate|pr-guard|agent-state)|stop --if-idle)/;
294
- const PRE_SW186_WAIT = "werkmeister wait-load";
295
294
  function readJson(file) {
296
295
  try {
297
296
  return JSON.parse(fs.readFileSync(file, "utf8"));
@@ -300,7 +299,7 @@ function readJson(file) {
300
299
  return null;
301
300
  }
302
301
  }
303
- /** True when *dir*'s hooks, permission rules or with-temp-home predate SW-186's spellings. */
302
+ /** True when *dir*'s hooks or permission rules are out of date, or its with-temp-home differs from this CLI's (SW-416). */
304
303
  function workspaceStale(dir) {
305
304
  const settingsFile = path.join(dir, ".claude", "settings.json");
306
305
  // Never inited by this CLI: `workspace init` writes it, not migrate.
@@ -332,7 +331,7 @@ function workspaceStale(dir) {
332
331
  workspaceDenyRules(dir).some((r) => !deny.has(r)) ||
333
332
  askWanted.some((r) => !ask.has(r)) ||
334
333
  recordedAsk.some((r) => !askWanted.includes(r)) ||
335
- (fs.existsSync(wrapper) && fs.readFileSync(wrapper, "utf8").includes(PRE_SW186_WAIT)));
334
+ (fs.existsSync(wrapper) && fs.readFileSync(wrapper, "utf8") !== TEMP_HOME_SCRIPT));
336
335
  }
337
336
  /**
338
337
  * SW-161: drop the pre-rename `SANDBOX_MCP_TOKEN` and set `WERKMEISTER_MCP_TOKEN` from
@@ -345,7 +344,7 @@ function secretsStep(checkOnly) {
345
344
  if (!/^\s*SANDBOX_MCP_TOKEN=/m.test(text)) {
346
345
  return { label, ok: true, detail: "no pre-rename keys" };
347
346
  }
348
- const tokenFile = path.join(dotDir(os.homedir()), "mcp-token");
347
+ const tokenFile = path.join(sandboxHome(), "mcp-token");
349
348
  const token = fs.existsSync(tokenFile) ? fs.readFileSync(tokenFile, "utf8").trim() : "";
350
349
  if (!token) {
351
350
  return {
@@ -2709,7 +2709,7 @@ export function abandonWorkspace(ws, why) {
2709
2709
  fs.writeFileSync(path.join(ws, "closeout.md"), renderCloseout(files, "not closed (abandoned)", `Abandoned: ${why}`));
2710
2710
  }
2711
2711
  /** The VS Code extension's terminal.ts writes one file per session shell pid here, holding its cwd (SW-421). */
2712
- const vscodeTerminalsDir = () => path.join(dotDir(os.homedir()), "vscode-terminals");
2712
+ const vscodeTerminalsDir = () => path.join(sandboxHome(), "vscode-terminals");
2713
2713
  const isIn = (ws, dir) => dir === ws || dir.startsWith(ws + path.sep);
2714
2714
  /** Shell pid → cwd of the extension's session terminals whose cwd is in *ws*. */
2715
2715
  function vscodeSessionsIn(ws, dir) {
package/dist/pr_rules.js CHANGED
@@ -31,7 +31,7 @@ These hold for every PR this workspace produces, whatever skill or command was a
31
31
  3. **Gate.** Before a PR opens, all of these hold: every earlier stage/phase is done; every follow-up a decided question in \`decisions.md\` promises names its issue key; the PR file's acceptance table is all PASS (MANUAL rows pass and the gate lists them); the code worktree is clean; a branch not yet pushed is not behind \`origin/<base>\` (the gate fetches it first; a pushed one passes with a note, rule 5; when behind, rebase with \`git -C <repo> rebase origin/<base>\` and rerun the tests, before the first push so no force-push is needed); each touched service's registry test command passes (\`.werkmeister/werkmeister-context.md\`); the exercise evidence is all PASS (or \`skip_exercise\` gives the reason); the code review in \`review.md\` is all PASS (or \`skip_review\` gives the reason; only in a workspace whose build stage has the review step); the repo's release check passes; the PR file reads \`status: approved\`. The PR-file checks (stages, acceptance table, approved, exercise evidence, review) and the base check run first; if one fails, the gate stops before any test command. With the tests the gate can run past a 10-minute tool call. Run \`pr open\`, and \`pr gate\` or \`pr gate --tests\` too, alone as a background job your harness tracks (Claude Code: \`run_in_background\`), with only its log redirect and no \`cd\`, pipe or other command around it, so an allow rule for it matches (an autonomous run has one; an interactive one asks): \`werkmeister pr open > <absolute workspace path>/.werkmeister/pr-open.log 2>&1\`, or \`werkmeister pr gate --tests > <absolute workspace path>/.werkmeister/gate-run.log 2>&1\`. The log path is absolute because the shell's cwd can drift into a code worktree, which would write the log there as an untracked file. Wait for its completion notice, which carries the exit code, then read the log's end. A bare \`&\` dies when the tool call returns, and \`nohup … &\` sends no notice when it ends.
32
32
  4. **Only \`werkmeister pr open\` opens PRs.** \`gh pr create\`, \`/create-pr\` and \`finishing-a-development-branch\` are blocked inside a workspace.
33
33
  5. **Auto-fix is always on.** \`werkmeister pr watch\` wakes the session that opened the PR when a check fails, a review comes in or the PR conflicts with its base, with the cause in the message. On a conflict, rebase onto \`origin/<base>\`; never merge the base into the branch, or GitHub can't rebase-merge it. A conflict in a generated file (a snapshot, a lockfile): take the base's copy and regenerate it with the repo's generator (\`.werkmeister/werkmeister-context.md\` names it); never hand-merge it. The agent can't force-push, so give the person \`git -C <absolute worktree path> push --force-with-lease=<branch>:<old sha>\`, where \`<old sha>\` is the PR head before the rebase; the wake message prints it filled in. With no wake message (a manual second rebase), run \`git fetch\` and take \`<old sha>\` from the output of \`git rev-parse origin/<branch>\`, pasted verbatim: never shortened or retyped, or the push fails \`stale info\`. ${DESKTOP_AUTOFIX_RULE} Never turn on auto-merge.
34
- 6. **Merge is the person's act.** Tooling never merges. On a repo with a merge queue, the queue's method decides how every PR merges (\`gh api repos/<repo>/rules/branches/<base>\`, the \`merge_queue\` rule's \`merge_method\`); without one, squash is the default. A PR that needs another method says so at the top of its body, and the person merges it that way, bypassing the queue: a grouped PR (\`group\` in \`workspace.yml\`) says "Rebase and merge, not squash" and keeps its per-ticket commits (\`werkmeister pr gate\` warns when the base won't allow it); a PR whose commit SHAs must survive (e.g. a commit listed in \`.git-blame-ignore-revs\`) says "Merge with a merge commit", since squash and rebase both rewrite SHAs. A PR that must wait for a step outside the code (e.g. a ruleset applied after its CI goes green) sets \`hold: <reason>\` in its PR file: \`werkmeister pr open\` then opens it as a draft, which GitHub won't merge, with \`Don't merge until: <reason>\` at the top of the body. The session that does the step runs \`gh pr ready <url>\` and empties \`hold:\`. A PR the repo's own automation queues (a release bot's version PR, e.g. Changesets' "version packages") is the exception: leave it to that automation, and don't tell the person it's theirs to merge.
34
+ 6. **Merge is the person's act.** Tooling never merges. On a repo with a merge queue, the queue's method decides how every PR merges (\`gh api repos/<repo>/rules/branches/<base>\`, the \`merge_queue\` rule's \`merge_method\`); without one, squash is the default. A PR that needs another method says so at the top of its body, and the person merges it that way, bypassing the queue: a grouped PR (\`group\` in \`workspace.yml\`) says "Rebase and merge, not squash" and keeps its per-ticket commits (\`werkmeister pr gate\` warns when the base won't allow it); a PR whose commit SHAs must survive (e.g. a commit listed in \`.git-blame-ignore-revs\`) says "Merge with a merge commit", since squash and rebase both rewrite SHAs. A PR that must wait for a step outside the code (e.g. a ruleset applied after its CI goes green) sets \`hold: <reason>\` in its PR file: \`werkmeister pr open\` then opens it as a draft, which GitHub won't merge, with \`Don't merge until: <reason>\` at the top of the body. The session that does the step runs \`gh pr ready <url>\` and empties \`hold:\`. A PR the repo's own automation queues (a release bot's version PR) is the exception: leave it to that automation, and don't tell the person it's theirs to merge.
35
35
  7. **Close out only when every PR file is \`shipped\`, \`closed\` or \`abandoned\`, and after the post-mortem:** the werkmeister \`postmortem\` skill writes \`postmortem.md\` at the workspace root. \`werkmeister workspace close\` refuses without it unless \`--skip-postmortem "<reason>"\`.
36
36
 
37
37
  ## PR file — \`${prFileDir}pr-<worktree>[-<slug>].md\`
@@ -50,7 +50,7 @@ merge_sha: # written by werkmeister pr status
50
50
  release: # release tag that shipped it, written by werkmeister pr status; \`none\` for a merged skip_release PR with no changeset (changesets repos), else set it yourself for a change that ships nothing
51
51
  reason: "" # required for closed / abandoned
52
52
  skip_tests: {} # <service>: <reason> — for a service with no test command or no running container (a service that has no tests says \`test: none: <reason>\` in its registry entry instead); tests: <reason> when no service maps to the changed files
53
- skip_release: "" # <reason> — skips the gate's release check; a ship: tag repo still waits for its release tag unless release: none, or the merged PR has no changeset
53
+ skip_release: "" # <reason> — skips the gate's release check; a ship: tag repo still waits for its release tag unless release: none, or the merged PR has no release entry
54
54
  skip_exercise: "" # <reason> — skips the gate's exercise check, e.g. a doc deliverable with nothing to run
55
55
  skip_review: "" # <reason> — skips the gate's review check, e.g. a doc deliverable with no code to review
56
56
  hold: "" # <reason> — pr open opens the PR as a draft, body starting "Don't merge until: <reason>"; when the step is done, gh pr ready <url> and empty this (rule 6)
@@ -59,7 +59,7 @@ hold: "" # <reason> — pr open opens the PR as a draft, body sta
59
59
  <PR body: summary, test and exercise results, acceptance table, Fixes <issue>>
60
60
  \`\`\`
61
61
 
62
- **Quote free-text values.** \`reason\`, \`skip_*\` (each \`skip_tests\` entry too) and \`hold\` take a double-quoted string, e.g. \`skip_release: "no changeset: docs only"\`. An unquoted value that contains \`: \` is invalid YAML and \`werkmeister pr open\` fails on it.
62
+ **Quote free-text values.** \`reason\`, \`skip_*\` (each \`skip_tests\` entry too) and \`hold\` take a double-quoted string, e.g. \`skip_release: "no release entry: docs only"\`. An unquoted value that contains \`: \` is invalid YAML and \`werkmeister pr open\` fails on it.
63
63
 
64
64
  **Acceptance table.** One row per criterion. The result cell holds exactly \`PASS\` or \`FAIL\` and nothing else; evidence goes in its own column. A criterion only the reviewer can check (it needs a real PR, the desktop app or the real machine) reads \`MANUAL\`, with why in the evidence: the gate passes it and lists it, and never \`PASS\` for a check nobody ran. Only this table takes \`MANUAL\`; exercise and review rows are PASS or FAIL. \`| criterion | PASS: repro.md §1 |\` fails the gate.
65
65
 
package/dist/sandbox.js CHANGED
@@ -1140,7 +1140,7 @@ export async function resolveWorkspaceDir(name) {
1140
1140
  return target;
1141
1141
  }
1142
1142
  /** Root for throwaway PR-reconcile session dirs (one per `<repo>-<number>`). */
1143
- const reconcileRoot = () => path.join(dotDir(os.homedir()), "reconcile");
1143
+ const reconcileRoot = () => path.join(sandboxHome(), "reconcile");
1144
1144
  /** A chat-session key that names a PR-reconcile dir instead of a workspace. */
1145
1145
  const RECONCILE_PREFIX = "reconcile:";
1146
1146
  /** Map a reconcile key (`reconcile:<slug>`) to its dir under `reconcileRoot`. */
@@ -44,6 +44,8 @@ export declare function renderServicesLocalYaml(k8sContext: string): string;
44
44
  * machine without touching them.
45
45
  */
46
46
  export declare function seedFile(target: string, content: string, mode?: number): SeedResult;
47
+ /** The README `machine setup` seeds into the default standards tree (SW-640). */
48
+ export declare const STANDARDS_README = "# Coding standards\n\nwerkmeister reads this folder's standard modules into each workspace. Each\nworkspace gets a routing table, the `w9r-*-standard` skills and the\n`_shared/standards.md` rows. `werkmeister standards check` validates the folder.\n\nA module is `<domain>.md` or `<domain>/STANDARD.md`, with frontmatter:\n\n ---\n domain: testing\n applies_to: [\"**/*.test.ts\"]\n phase: [implement, review]\n summary: One line on what the module covers.\n ---\n\nTo share one tree across a team, clone it and set `overrides.standards_dir`\nto its path in `~/.werkmeister/config.yaml`. `machine setup` writes this\nfile only when it is missing and never overwrites it.\n";
47
49
  /**
48
50
  * The `archetypes:` and `mcp_servers:` registries. Owned by werkmeister, not
49
51
  * by any app repo: `standards:` keys must match a docs/standards/<key>.md
package/dist/scaffold.js CHANGED
@@ -127,6 +127,26 @@ export function seedFile(target, content, mode = 0o644) {
127
127
  fs.chmodSync(target, mode);
128
128
  return { path: target, status: "created" };
129
129
  }
130
+ /** The README `machine setup` seeds into the default standards tree (SW-640). */
131
+ export const STANDARDS_README = `# Coding standards
132
+
133
+ werkmeister reads this folder's standard modules into each workspace. Each
134
+ workspace gets a routing table, the \`w9r-*-standard\` skills and the
135
+ \`_shared/standards.md\` rows. \`werkmeister standards check\` validates the folder.
136
+
137
+ A module is \`<domain>.md\` or \`<domain>/STANDARD.md\`, with frontmatter:
138
+
139
+ ---
140
+ domain: testing
141
+ applies_to: ["**/*.test.ts"]
142
+ phase: [implement, review]
143
+ summary: One line on what the module covers.
144
+ ---
145
+
146
+ To share one tree across a team, clone it and set \`overrides.standards_dir\`
147
+ to its path in \`~/.werkmeister/config.yaml\`. \`machine setup\` writes this
148
+ file only when it is missing and never overwrites it.
149
+ `;
130
150
  // ---------------------------------------------------------------------------
131
151
  // Registry defaults (werkmeister-owned; merged under every repo's fragment)
132
152
  // ---------------------------------------------------------------------------
package/dist/slots.js CHANGED
@@ -19,11 +19,10 @@
19
19
  * Every lease read-modify-write is under `~/.werkmeister/locks/allocate.lock`.
20
20
  */
21
21
  import * as fs from "node:fs";
22
- import * as os from "node:os";
23
22
  import * as path from "node:path";
24
23
  // biome-ignore lint/suspicious/noImportCycles: compose↔slots; SW-411
25
24
  import { workspaceForFeature } from "./compose.js";
26
- import { baselineUpstream, dotDir, loadPorts, loadServices, slotPortRange } from "./config.js";
25
+ import { baselineUpstream, loadPorts, loadServices, sandboxHome, slotPortRange } from "./config.js";
27
26
  import { docker } from "./docker.js";
28
27
  import { SandboxError } from "./errors.js";
29
28
  import { sandboxLock } from "./locks.js";
@@ -393,7 +392,7 @@ export async function featureServices(feature) {
393
392
  * as forgotten -- they have no live state to migrate.
394
393
  */
395
394
  export async function migrateSlotsJson() {
396
- const legacy = path.join(dotDir(os.homedir()), "slots.json");
395
+ const legacy = path.join(sandboxHome(), "slots.json");
397
396
  if (!fs.existsSync(legacy)) {
398
397
  return;
399
398
  }
@@ -24,8 +24,9 @@ import { _INPUT_FIELDS, isTrue, loadConfigFile, loadSandboxServiceConfigs, } fro
24
24
  import { stageDecisions } from "./icm_decisions.js";
25
25
  import { askLine, prDir, proposeDir, SELF_CHECK, stageDirs, templateFor, } from "./icm_templates.js";
26
26
  import { renderIssueRef } from "./issue_section.js";
27
- const PONYTAIL_ROW = "| ponytail | already loaded: the ponytail plugin's SessionStart hook prints `PONYTAIL MODE ACTIVE` " +
28
- "in every session. Invoke the `ponytail` skill only if that line is missing from your session context " +
27
+ const PONYTAIL_ROW = "| ponytail | optional plugin (SW-643): when installed, its SessionStart hook prints `PONYTAIL MODE ACTIVE` " +
28
+ "in every session. Invoke the `ponytail` skill only if that line is missing and the skill is listed; " +
29
+ "without the plugin, make the smallest change that fully solves the task " +
29
30
  "| any code edit |";
30
31
  function list(s) {
31
32
  return (s ?? "")
@@ -16,6 +16,10 @@ const RELOAD_RULE = "If the container is not running, run `werkmeister feature u
16
16
  "they are slower, and init rewrites the stage contracts.";
17
17
  // SW-612: sw-588 fell back to a published port after `feature up` warned a routed hostname did not resolve.
18
18
  const HOSTNAME_RULE = "If `werkmeister feature up` warns that a routed hostname does not resolve to 127.0.0.1 (its last warning line points to `werkmeister machine setup`), stop before any browser check and ask the person to run `werkmeister machine setup` (it needs sudo for the hosts entries and certificate trust). Never click through or bypass a certificate warning. Use the container's published port instead only when the person says to skip setup, and record it in `exercise.md` as a deviation.";
19
+ // SW-791: sw-772 hand-ran http.server to check a docs page; the Chrome tool refuses file://.
20
+ const STATIC_PAGE_RULE = "A static HTML page with no service to load it from is served for the browser check, since the Chrome tool refuses `file://`: run `python3 -I -u -m http.server 0 -b 127.0.0.1 -d <dir>` as a background Bash job (never without `-b 127.0.0.1`: it binds every interface by default), open the port its first line prints, and stop the job by its task ID when the check ends. Record it in `exercise.md` as the method.";
21
+ // SW-792: Chrome won't size its window below 477 px, so sw-772's 375 px check ran at 477.
22
+ const NARROW_VIEWPORT_RULE = 'The Chrome window does not size below 477 px, so check a narrower width in an iframe on the same origin: open the server\'s root, then with the JS tool replace the body with `<iframe src="<page>" width="375" height="812">`, screenshot it, and check `frame.contentDocument.documentElement.scrollWidth === frame.contentDocument.documentElement.clientWidth`. A page on another origin can\'t be read in the frame: ask the person for that row.';
19
23
  // SW-143: a library or CLI has nothing to restart. How to exercise one is the service's (or its archetype's)
20
24
  // `validate:` text, so app-specific steps stay out of the generic templates.
21
25
  const NO_SERVICE_RULE = "A library or CLI has no service to restart: build it, then exercise the built artifact exactly as its Validation text in `werkmeister-context.md` § How to validate says.";
@@ -297,7 +301,7 @@ const feature = [
297
301
  implementReview(v),
298
302
  GATE_STEP,
299
303
  REVIEW_DELTA,
300
- `Reload the running code: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} Then exercise the change as the How-to-validate section of \`werkmeister-context.md\` describes for each service touched, and capture the output. ${NO_SERVICE_RULE} ${PROBE_RULE} ${EXERCISE_WORKAROUND} ${TIMING_CLAIM}`,
304
+ `Reload the running code: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} ${STATIC_PAGE_RULE} ${NARROW_VIEWPORT_RULE} Then exercise the change as the How-to-validate section of \`werkmeister-context.md\` describes for each service touched, and capture the output. ${NO_SERVICE_RULE} ${PROBE_RULE} ${EXERCISE_WORKAROUND} ${TIMING_CLAIM}`,
301
305
  `Write \`output/exercise.md\`: \`git diff --stat\` for each repo you touched, the host and \`pr gate --tests\` exit codes and summary lines, ${PER_SERVICE}, ${SKIPPED}, any deviation from \`spec.md\` with its reason, and the exercise checks as ${exerciseFormat("evidence")}.`,
302
306
  MANUAL_STEP,
303
307
  ],
@@ -401,7 +405,7 @@ const bugfix = [
401
405
  ],
402
406
  doNotLoad: "`BRIEF.md` (`repro.md` carries the settled scope), `.werkmeister/*.yml`.",
403
407
  process: [
404
- `Reload the running code: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} ${NO_SERVICE_RULE} ${PROBE_RULE}`,
408
+ `Reload the running code: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} ${STATIC_PAGE_RULE} ${NARROW_VIEWPORT_RULE} ${NO_SERVICE_RULE} ${PROBE_RULE}`,
405
409
  "Rerun the reproduction steps from `repro.md` exactly. Capture the output.",
406
410
  `Exercise one neighbouring path through each caller \`repro.md\` listed. Capture the output. ${EXERCISE_WORKAROUND} ${TIMING_CLAIM}`,
407
411
  `Write \`output/exercise.md\`: steps 2–3 as ${exerciseFormat("detail")}.`,
@@ -474,7 +478,7 @@ const refactor = [
474
478
  implementReview(v),
475
479
  GATE_STEP,
476
480
  REVIEW_DELTA,
477
- `After the last step, reload and exercise the service: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} ${NO_SERVICE_RULE} ${PROBE_RULE} ${EXERCISE_WORKAROUND} ${TIMING_CLAIM}`,
481
+ `After the last step, reload and exercise the service: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} ${STATIC_PAGE_RULE} ${NARROW_VIEWPORT_RULE} ${NO_SERVICE_RULE} ${PROBE_RULE} ${EXERCISE_WORKAROUND} ${TIMING_CLAIM}`,
478
482
  `Write \`output/exercise.md\`: \`git diff --stat\` per repo, the test result after each step, the \`pr gate --tests\` exit code, ${PER_SERVICE}, ${SKIPPED}, and the final exercise checks as ${exerciseFormat("evidence")}.`,
479
483
  MANUAL_STEP,
480
484
  ],
@@ -24,7 +24,7 @@ import * as fs from "node:fs";
24
24
  import * as net from "node:net";
25
25
  import * as os from "node:os";
26
26
  import * as path from "node:path";
27
- import { dotDir, monorepoRoot, sandboxRoot } from "./config.js";
27
+ import { monorepoRoot, sandboxHome, sandboxRoot, sharedProxySkipReason } from "./config.js";
28
28
  import { daemonPort } from "./daemon_client.js";
29
29
  import { ProcError, run } from "./proc.js";
30
30
  import { error, info, success, warn } from "./reporter.js";
@@ -139,7 +139,7 @@ async function freePort(port) {
139
139
  }
140
140
  }
141
141
  function stateDir() {
142
- const d = dotDir(os.homedir());
142
+ const d = sandboxHome();
143
143
  fs.mkdirSync(d, { recursive: true });
144
144
  return d;
145
145
  }
@@ -345,6 +345,13 @@ export function appEntryPath(app) {
345
345
  * without it, an already-running server that still serves is left as-is.
346
346
  */
347
347
  export async function start(app = DASHBOARD, build = true, force = false) {
348
+ // The servers own fixed machine ports; a relocated home can't see their PID files,
349
+ // so it would free the port out from under the host's (SW-622, as for Caddy in SW-279).
350
+ const skip = sharedProxySkipReason();
351
+ if (skip) {
352
+ info(`${app.label}: ${skip}; leaving the machine's server on port ${app.port} alone`);
353
+ return serves(app.port);
354
+ }
348
355
  const [running, pid] = isRunning(app);
349
356
  // Never bounce ourselves. `werkmeister infra connect` is a tool on apps/werkmeister-mcp, and it
350
357
  // reaches infra.up() -> startAll(): a stale dist/ would otherwise make this
@@ -476,6 +483,11 @@ export async function stop(app = DASHBOARD) {
476
483
  info(`${app.label} is kept up by launchd (${DAEMON_LABEL}); leaving it running`);
477
484
  return false;
478
485
  }
486
+ const skip = sharedProxySkipReason();
487
+ if (skip) {
488
+ info(`${app.label}: ${skip}; leaving the machine's server on port ${app.port} alone`);
489
+ return false;
490
+ }
479
491
  const [running, pid] = isRunning(app);
480
492
  if (!running || pid === null) {
481
493
  fs.rmSync(pidFile(app), { force: true });
@@ -10,12 +10,12 @@
10
10
  */
11
11
  import { randomBytes } from "node:crypto";
12
12
  import * as fs from "node:fs";
13
- import * as os from "node:os";
14
13
  import * as path from "node:path";
14
+ import { sandboxHome } from "./config.js";
15
15
  import { dotDir } from "./dot_dir.js";
16
16
  export const WORKSPACE_TOKEN_FILE = "token";
17
17
  export function tokensDir() {
18
- return path.join(dotDir(os.homedir()), "tokens");
18
+ return path.join(sandboxHome(), "tokens");
19
19
  }
20
20
  /** The token a container in this workspace sends, git-ignored (worktrees.ts). */
21
21
  export function workspaceTokenFile(workspaceRoot) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "werkmeister-core",
3
- "version": "0.93.11",
3
+ "version": "0.94.1",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "description": "werkmeister's shared library. Its public API is werkmeister-core/sdk; every other entry point is internal.",