heyspex 0.2.0 → 0.2.2

package/scripts/cursor-hooks/manifest.mjs

@@ -55,10 +55,13 @@ export const HOOKS = [
   { event: 'sessionStart', hook: 'wip-checkpoint', why: 'Surface the previous session WIP handoff before work resumes.' },
   { event: 'sessionStart', hook: 'inject-dev-server-awareness', why: 'Once-per-session reminder that dev-server status is a tool call, not a guess.' },
   { event: 'sessionStart', hook: 'inject-coo-seat', why: 'Inject the dev-factory COO seat mandate when the COO window is open.' },
+  { event: 'sessionStart', hook: 'inject-doctrine', why: 'Inject the baseline SpexCode Doctrine edition at session start.' },
   { event: 'sessionStart', hook: 'coo-guard-check', why: 'Warn at session start when a breakdown has not been delegated.' },
   { event: 'sessionStart', hook: 'check-auto-memory-budget', why: 'Self-heal and budget-check the auto-memory index.' },
   { event: 'sessionStart', hook: 'check-claude-md-budget', why: 'Advisory budget check on the always-loaded agent contract.' },
   { event: 'sessionStart', hook: 'check-mcp-freshness-hook', why: 'Warn when the running MCP server is stale versus vendor.' },
+  { event: 'sessionStart', hook: 'git-reflog-audit', why: 'Session-start git audit (stash/reset/rebase witness).' },
+  { event: 'sessionStart', hook: 'vault-mirror-catchup', why: 'Cloud write mode: detached hs pull --apply closes a stale disk mirror (HS-XJFQ).' },
 
   // ── Compaction ──────────────────────────────────────────────────────────
   // Claude re-runs SessionStart(source: compact) after compaction; Cursor fires
@@ -74,6 +77,7 @@ export const HOOKS = [
   { event: 'beforeSubmitPrompt', hook: 'preflight-reminder', why: 'Name the required procedure before a filing/destructive/protocol turn.' },
   { event: 'beforeSubmitPrompt', hook: 'intent-classifier-trigger', why: 'Route capture / research / settings / defer intents to the right skill.' },
   { event: 'beforeSubmitPrompt', hook: 'inject-communication-style', why: 'Re-assert the plain-language communication rules each turn.' },
+  { event: 'beforeSubmitPrompt', hook: 'inject-vault-context', timeout: 10, why: 'Lexical vault retrieval for the prompt (surfaced as a user message).' },
 
   // ── Before every tool call (any tool) ───────────────────────────────────
   { event: 'preToolUse', matcher: '.*', hook: 'emit-claim-status', args: ['--event=PreToolUse'], why: 'Claim liveness heartbeat to the console.' },
@@ -86,22 +90,28 @@ export const HOOKS = [
   // the vault guard because removing a profile file is the loss it exists to
   // prevent, and Claude had no separate delete tool to list.
   { event: 'preToolUse', matcher: 'Write|Delete', hook: 'env-vault-guard', why: 'Block destructive writes to the encrypted env vault (ALWAYS ON).' },
+  { event: 'preToolUse', matcher: 'Write', hook: 'vault-write-tier-guard', why: 'Deny disk writes to vault specs in cloud write mode (HS-FCNH).' },
   { event: 'preToolUse', matcher: 'Write', hook: 'settings-write-gate', why: 'Require approval before .heyspex/config.yaml changes.' },
   { event: 'preToolUse', matcher: 'Write', hook: 'enforce-vault-naming', why: 'Block vault filenames that violate the naming registry.' },
   { event: 'preToolUse', matcher: 'Write', hook: 'guard-auto-memory-writes', why: 'Block new topic files in the auto-memory directory.' },
   { event: 'preToolUse', matcher: 'Write', hook: 'preflight-reminder', why: 'Preflight reminder on the edit path itself.' },
   { event: 'preToolUse', matcher: 'Write', hook: 'claim-before-code-gate', why: 'Deny the first code edit after plan exit with no claim.' },
+  { event: 'preToolUse', matcher: 'Write', hook: 'directive-obligation-gate', why: 'Deny product-code writes while a capture_on_idea obligation is unmet, and (claim-before-build) with no claim/capture (HS-20SW).' },
 
   // ── Before a shell command ──────────────────────────────────────────────
   // beforeShellExecution, not preToolUse/Shell: it is the only event guaranteed
   // to carry the command string, and Cursor honors allow/deny/ask on it.
   { event: 'beforeShellExecution', hook: 'env-vault-guard', why: 'Block shell writes/exfiltration targeting the env vault (ALWAYS ON).' },
+  { event: 'beforeShellExecution', hook: 'vault-write-tier-guard', why: 'Deny shell writes to vault specs in cloud write mode (HS-FCNH).' },
   { event: 'beforeShellExecution', hook: 'settings-write-gate', why: 'Catch shell writes to .heyspex/config.yaml.' },
   { event: 'beforeShellExecution', hook: 'enforce-vault-naming', why: 'Catch vault files created via the shell.' },
   { event: 'beforeShellExecution', hook: 'guard-auto-memory-writes', why: 'Catch auto-memory topic files created via the shell.' },
   { event: 'beforeShellExecution', hook: 'preflight-reminder', why: 'Preflight reminder on rm -rf / force-push shaped commands.' },
   { event: 'beforeShellExecution', hook: 'dev-server-task-reminder', timeout: 10, why: 'Dev-server start/stop hard gate plus DB-safety reminder.' },
   { event: 'beforeShellExecution', hook: 'git-stash-gate', timeout: 10, why: 'Always ask before a mutating git stash.' },
+  { event: 'beforeShellExecution', hook: 'git-identity-guard', why: 'Agents never write git identity (owner ruling 2026-09-19, ALWAYS ON).' },
+  { event: 'beforeShellExecution', hook: 'capture-execution-gate', why: 'Block dev-factory research/paid-model/routing shell commands past an ungrounded capture (HS-KNJ8, platform).' },
+  { event: 'beforeShellExecution', hook: 'directive-obligation-gate', why: 'Deny build commands and product-code shell writes while a capture obligation is unmet (HS-20SW).' },
 
   // ── Before specific MCP tools ───────────────────────────────────────────
   // Cursor fires preToolUse for MCP tools too (matcher `MCP:<name>`), so these
@@ -112,6 +122,8 @@ export const HOOKS = [
   { event: 'preToolUse', matcher: '.*', tool: 'heyspex_file_spec$', hook: 'capture-workflow-gate', timeout: 8, why: 'Deny filing an implementation spec straight out of an open capture.' },
   { event: 'preToolUse', matcher: '.*', tool: 'heyspex_settings_set$', hook: 'settings-write-gate', why: 'Require approval for settings changes made through MCP.' },
   { event: 'preToolUse', matcher: '.*', tool: '[Nn]eon__(prepare_database_migration|complete_database_migration|reset_from_parent|delete_branch)$', hook: 'dev-server-task-reminder', timeout: 10, why: 'DB-safety gate on Neon migration/reset/delete tools.' },
+  { event: 'preToolUse', matcher: '.*', tool: 'heyspex_file_spec$', hook: 'diagnose-capture-reminder', why: 'Warn when a diagnose is filed with no capture holding the owner words (HS-IK2D).' },
+  { event: 'preToolUse', matcher: '.*', tool: '^(Workflow|Skill)$', hook: 'research-method-guard', why: 'Research method guard on Skill/Workflow launches (HS-EN4F, ALWAYS ON).' },
   { event: 'preToolUse', matcher: '.*', tool: '^(Workflow|Skill)$', hook: 'deep-research-cost-gate', why: 'Cost confirmation before a paid deep-research harness launch.' },
   { event: 'preToolUse', matcher: '.*', tool: '^(WebSearch|WebFetch|web_search|web_fetch)$|heyspex_save_research$', hook: 'research-protocol-gate', why: 'WebSearch/WebFetch/save_research refused until the research preflight ran (HS-K0ZP, HS-EN4F).' },
 
@@ -119,10 +131,13 @@ export const HOOKS = [
   // subagentStart over preToolUse/Task: it carries subagent_type and the model,
   // which is exactly what the routing gate decides on, and it can deny.
   { event: 'subagentStart', hook: 'agent-spawn-delegation-gate', why: 'Block a build/breakdown/critic subagent on an off-routing model.' },
+  { event: 'subagentStart', hook: 'capture-execution-gate', why: 'Block a dev-factory subagent spawn past an ungrounded capture (HS-KNJ8, platform).' },
+  { event: 'subagentStart', hook: 'directive-obligation-gate', why: 'Deny a build subagent while a capture obligation is unmet or the session has no claim/capture (HS-20SW).' },
 
   // ── After every tool call ───────────────────────────────────────────────
   { event: 'postToolUse', matcher: '.*', hook: 'emit-claim-status', args: ['--event=PostToolUse'], why: 'Claim liveness heartbeat after the call resolves.' },
   { event: 'postToolUse', matcher: '.*', hook: 'log-session-activity', args: ['--event=PostToolUse'], why: 'Append the tool result row to the session log.' },
+  { event: 'postToolUse', matcher: '.*', hook: 'directive-obligation-gate', why: 'Discharge the capture obligation on a capture write; track claim acquire/release (HS-20SW).' },
   { event: 'postToolUse', matcher: '.*', hook: 'close-terminal-on-ship', why: 'Close the Launch terminal once the spec ships.' },
   { event: 'postToolUse', matcher: 'Write', hook: 'notify-status-flip', why: 'Sound on an in_review status flip.' },
   { event: 'postToolUse', matcher: 'Write', hook: 'scripts/stamp-provenance-on-edit.mjs', why: 'Stamp assisted_by provenance on direct spec edits.' },
@@ -137,7 +152,11 @@ export const HOOKS = [
   // hook re-drives the agent — the same effect as Claude's exit-2 block.
   { event: 'stop', hook: 'emit-claim-status', args: ['--event=Stop'], why: 'Mark the claim pending-on-response.' },
   { event: 'stop', hook: 'naughty-list-gate', why: 'Re-drive the turn when the final message uses banned jargon.' },
+  { event: 'stop', hook: 'id-display-format-gate', why: 'Re-drive the turn when a reply breaks the Naming V3 display-id format.' },
+  { event: 'stop', hook: 'epic-milestone-phrasing-gate', why: 'Re-drive the turn when a reply breaks the epic/milestone phrasing rules.' },
+  { event: 'stop', hook: 'git-reflog-audit', why: 'Session-close git audit backstop (stash/reset/rebase witness).' },
   { event: 'stop', hook: 'enforce-session-sequence', why: 'Re-drive the turn when work shipped without record_wip.' },
+  { event: 'stop', hook: 'directive-obligation-gate', why: 'Re-drive the turn ONCE (followup_message) when a capture obligation is still unmet (HS-20SW).' },
 
   // ── Session end ─────────────────────────────────────────────────────────
   { event: 'sessionEnd', hook: 'session-end', why: 'Release the claim and notify the console.' },
@@ -164,6 +183,33 @@ export const UNPORTABLE = [
   },
 ];
 
+/**
+ * Hooks that ARE registered above but run weaker than on Claude Code. Kept in code (like UNPORTABLE)
+ * so scripts/lib/hook-dispositions.test.mjs can hold the three-host table to it.
+ */
+export const DEGRADED = [
+  {
+    hook: 'preflight-reminder',
+    reason: 'beforeSubmitPrompt honors user_message only: the reminder surfaces in the transcript, not as invisible context.',
+  },
+  {
+    hook: 'intent-classifier-trigger',
+    reason: 'Same channel limit; the routing directive reaches the agent as a visible user message.',
+  },
+  {
+    hook: 'inject-communication-style',
+    reason: 'Same channel limit; re-asserted each turn as a visible user message.',
+  },
+  {
+    hook: 'inject-vault-context',
+    reason: 'Same channel limit; retrieved vault context appears as a visible user message.',
+  },
+  {
+    hook: 'claim-before-code-gate',
+    reason: 'Armed by plan-exit-ingest-gate, which has no Cursor trigger (UNPORTABLE), so it stays dormant.',
+  },
+];
+
 /**
  * The command string Cursor runs for one entry.
  *

package/scripts/heyspex-mode.mjs

@@ -25,6 +25,26 @@ import { fileURLToPath } from 'node:url';
 
 export const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
+/**
+ * The root the mode switch reads and writes. In the platform checkout that is REPO_ROOT (unchanged). When this file
+ * runs from an INSTALLED package (node_modules/heyspex/...) REPO_ROOT is the package, not the project the dev is
+ * working in: the switch used to write inside node_modules and the hook runner never saw it. So: the project
+ * (CLAUDE_PROJECT_DIR, else the nearest ancestor of cwd holding a state dir or .git, else cwd).
+ */
+export function resolveModeRoot(repoRoot = REPO_ROOT, env = process.env, cwd = process.cwd()) {
+  if (!repoRoot.split(path.sep).includes('node_modules')) return repoRoot;
+  const fromEnv = String(env.CLAUDE_PROJECT_DIR ?? '').trim();
+  if (fromEnv) return fromEnv;
+  let d = cwd;
+  for (;;) {
+    if (fs.existsSync(path.join(d, '.hey' + 'spex')) || fs.existsSync(path.join(d, '.git'))) return d;
+    const up = path.dirname(d);
+    if (up === d) return cwd;
+    d = up;
+  }
+}
+export const MODE_ROOT = resolveModeRoot();
+
 const STATE_REL = '.heyspex/mode.json';
 const BACKUP_DIR_REL = '.heyspex/mode-backup';
 const CLAUDE_MD_REL = 'CLAUDE.md';

package/scripts/hs-mode.mjs

@@ -9,7 +9,7 @@
 // Flags: --json (machine-readable), --quiet (exit code only).
 // Exit codes: 0 ok · 1 usage · 2 flip failed.
 
-import { REPO_ROOT, resolveMode, setMode, mcpEnabled, claudeMdStubbed } from './heyspex-mode.mjs';
+import { MODE_ROOT as REPO_ROOT, resolveMode, setMode, mcpEnabled, claudeMdStubbed } from './heyspex-mode.mjs';
 
 const argv = process.argv.slice(2).filter((a) => a !== 'mode');
 const flags = new Set(argv.filter((a) => a.startsWith('--')));

package/scripts/hs-view.mjs

@@ -12,9 +12,11 @@
  * Open = run it; close = close the window; re-run = reopen (idempotent).
  *
  * Usage:
- *   hs view pipeline                      # follow the focus pin
- *   hs view pipeline HS-I87U-CAP          # fixed anchor spec
- *   hs view docs HS-NP1Y                  # single-doc reader, live-refreshing
+ *   hs view                               # inspector, Pipeline tab, following the focus pin
+ *   hs view HLFJ                          # same, anchored on HS-HLFJ (any case, HS- optional)
+ *   hs view pipeline HS-I87U-CAP          # same — "pipeline" is the inspector's Pipeline tab
+ *   hs view inspector HS-I87U-CAP         # inspector on its default tab
+ *   hs view docs HS-NP1Y                  # doc + inspector Pipeline tab side by side
  *   hs view pipeline --follow capture     # track the capture-on-deck pin
  *   hs view pipeline --follow capture --url https://console.example.com
  *   hs view pipeline --width 510 --height 900 --browser edge|chrome
@@ -31,6 +33,13 @@ import { resolveConsoleUrl, DEFAULT_CONSOLE_URL } from './lib/console-url-resolv
 // checkout `npx hs` installs the unrelated public package hs@2.0.1
 // ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
 import { hsCommand } from './lib/hs-command.mjs';
+import {
+  complementarySide,
+  computeWindowPlacement,
+  getPrimaryWorkArea,
+  parsePlaceSide,
+  placementFlags,
+} from './lib/window-placement.mjs';
 import { collectOccupiedFamilyKeysFromVault, parseSpecId } from '../vendor/heyspex-mcp/spec-id-lib.mjs';
 
 function defaultVaultRoot() {
@@ -107,6 +116,71 @@ async function resolveSpec(base, rawSpec, vaultRoot) {
   return { ok: false, kind: 'not_found', suggestions: suggestFamilyKeys(rawSpec, vaultRoot) };
 }
 
+/**
+ * The solo surfaces `/solo/<surface>` mounts — mirror of the registry in
+ * spex-console/src/app/solo/[surface]/page.tsx. A first positional that is not
+ * one of these is read as a spec id, opened on the pipeline surface.
+ */
+export const SOLO_SURFACES = new Set([
+  'pipeline',
+  'docs',
+  'inspector',
+  'whats-next',
+  'captures',
+  'session-log',
+  'settings',
+]);
+
+/**
+ * The view a bare `hs view` / `hs view <spec-id>` opens. There is no
+ * standalone pipeline window: the inspector already carries the Pipeline tab,
+ * so "pipeline" resolves to the inspector opened on that tab (owner ruling
+ * 2026-10-10) — see {@link INSPECTOR_TAB_ALIASES}.
+ */
+export const DEFAULT_SPEC_SURFACE = 'pipeline';
+
+/**
+ * Surface words that are really an inspector tab. `hs view pipeline <id>` and
+ * every older caller still work — they land on the inspector, that tab open.
+ */
+export const INSPECTOR_TAB_ALIASES = { pipeline: 'pipeline' };
+
+/**
+ * Canonicalise a typed spec token: `hlfj`, `hs-hlfj` and `HS-HLFJ` all become
+ * `HS-HLFJ`. A missing `HS-` prefix is added (the console's family-token
+ * fallback only matches `HS-<token>-…` prefixes, so a bare `hlfj` found
+ * nothing). Only a short key form (`HLFJ`, `HLFJ-AB12`, `HLFJ-TASK`) is
+ * upper-cased; a full basename keeps its lower-case slug so it still matches
+ * exactly.
+ */
+export function normalizeSpecToken(raw) {
+  const token = String(raw ?? '').trim();
+  if (!token) return token;
+  const body = token.replace(/^hs-/i, '');
+  if (/^[a-z0-9]{4}(?:-[a-z0-9]{2,8}){0,2}$/i.test(body)) return `HS-${body.toUpperCase()}`;
+  return `HS-${body}`;
+}
+
+/**
+ * Split positionals into `{ surface, panel, spec }`. `hs view <surface> [spec]`
+ * keeps its surface; `hs view <spec>` and bare `hs view` open the inspector on
+ * its Pipeline tab, as does the `pipeline` word. The spec token is normalised.
+ */
+export function resolveSurfaceAndSpec(positionals) {
+  let [surface = null, spec = null] = positionals;
+  if (surface && !SOLO_SURFACES.has(surface.toLowerCase()) && !spec) {
+    spec = surface;
+    surface = null;
+  }
+  surface = (surface ?? DEFAULT_SPEC_SURFACE).toLowerCase();
+  let panel = null;
+  if (INSPECTOR_TAB_ALIASES[surface]) {
+    panel = INSPECTOR_TAB_ALIASES[surface];
+    surface = 'inspector';
+  }
+  return { surface, panel, spec: spec ? normalizeSpecToken(spec) : null };
+}
+
 /** Anchor sources the window can follow live. `pin` is the default behavior. */
 const FOLLOW_MODES = new Set(['pin', 'capture']);
 
@@ -117,11 +191,14 @@ export const DEFAULT_WINDOW_WIDTH = 510;
  * Surfaces that want a different opening width than the default.
  *
  * `inspector` is one narrow pane meant to sit beside a terminal — at 510 it
- * takes screen it does not need, and its one-pane layout is designed around
- * 350 ([[HS-LO2G-AQVI-TASK-one-pane-inspector-window-doc-takes-the]]).
+ * takes screen it does not need. It opens at 350 and grows leftward to the
+ * `docs` width when a doc pane opens
+ * ([[HS-I2YN-ST07-EPIC-two-pane-layout-pipeline-view-on-the]]).
  */
 export const SURFACE_WINDOW_WIDTH = {
   inspector: 350,
+  // Two panes: the doc, then the inspector rail (360) to its right.
+  docs: 960,
 };
 
 /**
@@ -139,8 +216,30 @@ export function resolveWindowWidth(surface, explicitWidth) {
   return SURFACE_WINDOW_WIDTH[surface] ?? DEFAULT_WINDOW_WIDTH;
 }
 
+/**
+ * Which half of the primary monitor's work area the window takes.
+ *
+ * Explicit `--place` wins, then `HEYSPEX_VIEW_PLACE`, then the default: the
+ * two-pane capture view (`docs --follow capture`) sits on the RIGHT so the
+ * SpexCode agent window can take the left
+ * ([[HS-I2YN-ST07-EPIC-two-pane-layout-pipeline-view-on-the]]). Every other
+ * window keeps the OS's own placement (`none`), as before.
+ */
+export function resolvePlaceSide({ place, surface, follow }, env = process.env) {
+  const explicit = parsePlaceSide(place);
+  if (explicit) return explicit;
+  const fromEnv = parsePlaceSide(env.HEYSPEX_VIEW_PLACE);
+  if (fromEnv) return fromEnv;
+  return surface === 'docs' && follow === 'capture' ? 'right' : 'none';
+}
+
+/** The side the paired agent (terminal) window should take for this view. */
+export const agentSideFor = (viewSide) => complementarySide(viewSide);
+
 function parseArgs(argv) {
   const args = {
+    place: null,
+    printOnly: false,
     surface: null,
     spec: null,
     // null until `--width` is seen; resolved per-surface once the surface is known.
@@ -150,11 +249,23 @@ function parseArgs(argv) {
     follow: null,
     url: null,
   };
+  const positionals = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--help' || a === '-h') return { help: true };
     if (a === '--width') { args.width = Number(argv[++i]) || args.width; continue; }
-    if (a === '--height') { args.height = Number(argv[++i]) || args.height; continue; }
+    if (a === '--height') { args.height = Number(argv[++i]) || args.height; args.heightExplicit = true; continue; }
+    if (a === '--place') {
+      const side = parsePlaceSide(argv[++i]);
+      if (!side) {
+        process.stderr.write('hs view: --place expects left, right or none\n');
+        process.exitCode = 2;
+        return { help: true };
+      }
+      args.place = side;
+      continue;
+    }
+    if (a === '--print' || a === '--dry-run') { args.printOnly = true; continue; }
     if (a === '--browser') { args.browser = String(argv[++i] || 'edge'); continue; }
     if (a === '--url') {
       const raw = String(argv[++i] || '').trim();
@@ -183,10 +294,9 @@ function parseArgs(argv) {
       process.exitCode = 2;
       return { help: true };
     }
-    if (!args.surface) args.surface = a;
-    else if (!args.spec) args.spec = a;
+    positionals.push(a);
   }
-  return args;
+  return { ...args, ...resolveSurfaceAndSpec(positionals) };
 }
 
 function usage() {
@@ -194,15 +304,25 @@ function usage() {
     [
       'hs view <surface> [spec-id] [--follow pin|capture] [--url https://…]',
       '                                [--width N] [--height N] [--browser edge|chrome]',
+      '                                [--place left|right|none] [--print]',
+      'hs view [spec-id]                 # inspector on its Pipeline tab',
       '',
       'Open one console surface in a chromeless app-mode browser window.',
-      'Surfaces: pipeline, docs, inspector, whats-next, captures, session-log, settings',
+      'Surfaces: inspector, docs, whats-next, captures, session-log, settings',
+      '  ("pipeline" = the inspector opened on its Pipeline tab; there is no',
+      '  standalone pipeline window.)',
       '  (registry: src/app/solo/[surface]/page.tsx).',
-      'Without a spec-id the pipeline and docs views follow the focus pin live.',
+      'Spec ids are forgiving: hlfj, hs-hlfj and HS-HLFJ are the same spec.',
+      'Without a spec-id the inspector and docs views follow the focus pin live.',
       '--follow capture tracks the capture-on-deck pin instead, so the window',
       '  re-anchors itself onto each new capture rather than opening another.',
       '--url opens against a named console (a hosted one) instead of probing for',
       '  a local dev server — the cloud-relay path the desktop companion uses.',
+      '--place pins the window to the left or right half of the primary monitor',
+      '  work area (taskbar excluded; never another monitor). Default: right for',
+      '  `docs --follow capture` (the two-pane capture view, leaving the left half',
+      '  for the SpexCode agent window), none otherwise. Env: HEYSPEX_VIEW_PLACE.',
+      '--print shows the browser command line and does not open a window.',
       '',
     ].join('\n'),
   );
@@ -223,9 +343,25 @@ function isLocalConsoleUrl(url) {
   }
 }
 
-function launchAppWindow(url, { width, height, browser }) {
+/**
+ * The exact command line a launch would run, as `{ file, args }`. Pure, so
+ * `--print` and the tests see precisely what `launchAppWindow` spawns.
+ */
+export function buildLaunchCommand(url, { width, height, browser }, placement = null, platform = process.platform) {
+  const exe = browser === 'chrome' ? 'chrome' : 'msedge';
+  const flags = [`--app=${url}`, ...(placement ? placementFlags(placement) : [`--window-size=${width},${height}`])];
+  if (platform === 'win32') return { file: 'cmd.exe', args: ['/c', 'start', '', exe, ...flags] };
+  if (platform === 'darwin') {
+    const app = browser === 'chrome' ? 'Google Chrome' : 'Microsoft Edge';
+    return { file: 'open', args: ['-na', app, '--args', ...flags] };
+  }
+  return { file: browser === 'chrome' ? 'google-chrome' : 'microsoft-edge', args: flags };
+}
+
+function launchAppWindow(url, opts, placement = null) {
+  const { width, height, browser } = opts;
   const exe = browser === 'chrome' ? 'chrome' : 'msedge';
-  const flags = [`--app=${url}`, `--window-size=${width},${height}`];
+  const flags = [`--app=${url}`, ...(placement ? placementFlags(placement) : [`--window-size=${width},${height}`])];
   let child;
   if (process.platform === 'win32') {
     // `start` resolves msedge/chrome via the App Paths registry; the empty ''
@@ -246,9 +382,8 @@ function launchAppWindow(url, { width, height, browser }) {
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
-  if (args.help || !args.surface) {
+  if (args.help) {
     usage();
-    if (!args.help) process.exitCode = 2;
     return;
   }
 
@@ -312,14 +447,42 @@ async function main() {
   const params = new URLSearchParams();
   if (args.spec) params.set('spec', args.spec);
   else if (args.follow) params.set('follow', args.follow);
+  if (args.panel) params.set('panel', args.panel);
   const search = params.toString();
   const query = search ? `?${search}` : '';
   const url = `${base}/solo/${encodeURIComponent(args.surface)}${query}`;
 
-  launchAppWindow(url, args);
+  // Placement is best-effort: no work area (non-Windows, probe failure) means
+  // no position flags and today's behavior.
+  const side = resolvePlaceSide(args);
+  const placement =
+    side === 'none'
+      ? null
+      : computeWindowPlacement({
+          workArea: getPrimaryWorkArea(),
+          side,
+          width: args.width,
+          // Full work-area height unless --height was passed.
+          height: args.heightExplicit ? args.height : undefined,
+        });
+
+  if (args.printOnly) {
+    const cmd = buildLaunchCommand(url, args, placement);
+    process.stdout.write(
+      `hs view (--print, nothing opened): place=${side}${placement ? '' : ' (no placement)'}\n` +
+        `  ${cmd.file} ${cmd.args.join(' ')}\n` +
+        (placement ? `  agent window should take: ${agentSideFor(side)}\n` : ''),
+    );
+    return;
+  }
+
+  launchAppWindow(url, args, placement);
+  const size = placement
+    ? `${placement.width}x${placement.height} at ${placement.x},${placement.y}`
+    : `${args.width}x${args.height}`;
   process.stdout.write(
     `hs view: opened ${url} in an app-mode ${args.browser === 'chrome' ? 'Chrome' : 'Edge'} window ` +
-      `(${args.width}x${args.height}). Close the window to close; re-run to reopen.\n`,
+      `(${size}). Close the window to close; re-run to reopen.\n`,
   );
 }
 

package/scripts/install-claude-code-hooks.mjs

@@ -42,11 +42,13 @@ const SESSION_ACTIVITY_MARKER = 'scripts/claude-hooks/log-session-activity.mjs';
 // makes every hook exit 0 without the settings file changing). See
 // scripts/claude-hooks/_run.mjs and docs/claude-code-setup.md.
 const SHIM = 'scripts/claude-hooks/_run.mjs';
+// Self-locating, env-independent, fail-open command (Copilot compatibility): scripts/lib/customer-kit.mjs buildBootstrap().
+import { PLATFORM_RUNNER_PREFIX } from './lib/customer-kit.mjs';
 
 /** Canonical command string for a hook: `node "$CLAUDE_PROJECT_DIR/_run.mjs" <name> [args]`. */
 function shimCommand(scriptMarker, args = '') {
   const name = scriptMarker.replace('scripts/claude-hooks/', '').replace(/\.mjs$/, '');
-  return `node "$CLAUDE_PROJECT_DIR/${SHIM}" ${name}${args}`;
+  return `${PLATFORM_RUNNER_PREFIX} ${name}${args}`;
 }
 
 /**