gipity 1.0.407 → 1.0.409

package/dist/banner.js

@@ -1,6 +1,21 @@
 // ── Gipity CLI Startup Banner ──────────────────────────────────────────
 // Two-panel box showing all AI models, platform tools, and sandbox capabilities.
+import { homedir } from 'os';
+import { sep } from 'path';
 import { brand, bold, faint, muted, fg } from './colors.js';
+/** Abbreviate a home-relative path to `~`, cross-platform. On Windows `HOME`
+ *  is usually unset (it's `USERPROFILE`), and `str.replace('', '~')` prepends
+ *  a stray `~`, so use os.homedir() and a real prefix check. */
+function tildify(p) {
+    const home = homedir();
+    if (!home)
+        return p;
+    if (p === home)
+        return '~';
+    if (p.startsWith(home + sep))
+        return '~' + p.slice(home.length);
+    return p;
+}
 // ── Static content ─────────────────────────────────────────────────────
 // ── Feature groups ────────────────────────────────────────────────────
 const AI_MODELS = [
@@ -174,7 +189,7 @@ function buildLeftPanel(opts, panelW) {
         leftLines.push(center(line, panelW));
     }
     if (opts.cwd) {
-        const short = leadingEllipsify(opts.cwd.replace(process.env['HOME'] || '', '~'), panelW);
+        const short = leadingEllipsify(tildify(opts.cwd), panelW);
         leftLines.push('');
         leftLines.push(center(muted(short), panelW));
         leftLines.push('');

package/dist/commands/add.js

@@ -144,7 +144,7 @@ function buildLocalPayload(rootDir) {
     return { name: path.basename(rootDir), files };
 }
 export const addCommand = new Command('add')
-    .description('Add a template (scaffold an app) or a kit (reusable building block) to the project. Pass ./path/to/dir to install a local template directly.')
+    .description('Add a template or kit')
     .argument('[name]', 'Template/kit key, OR a local directory path (./, ~/, or /abs). Omit for help; use --list for just the catalog.')
     .option('--title <title>', 'App title - templates only (defaults to project name)')
     .option('--description <desc>', 'App description for meta tags - templates only')

package/dist/commands/approval.js

@@ -21,7 +21,7 @@ function keyToIndex(key) {
     return code >= 0 && code < 26 ? code : -1;
 }
 export const approvalCommand = new Command('approval')
-    .description('List, create, answer, or cancel approvals');
+    .description('Manage approvals');
 approvalCommand
     .command('list')
     .description('List pending approvals')

package/dist/commands/claude.js

@@ -1,10 +1,9 @@
 import { Command } from 'commander';
-import { join, dirname, resolve, basename } from 'path';
+import { join, dirname, resolve, basename, sep } from 'path';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, statSync } from 'fs';
-import { spawn } from 'child_process';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
-import { resolveCommand } from '../platform.js';
+import { resolveCommand, spawnCommand } from '../platform.js';
 import { getAuth, saveAuth, sessionExpired, accessTokenExpired, refreshTokenIfNeeded } from '../auth.js';
 import { get, post, publicPost, ApiError, getAccountSlug } from '../api.js';
 import { getConfig, saveConfigAt, clearConfigCache, getApiBaseOverride, DEFAULT_API_BASE, getConfigPath } from '../config.js';
@@ -234,7 +233,7 @@ export const claudeCommand = new Command('claude')
     // Forwarded to `claude` via the unknown-arg passthrough below (NOT in the
     // gipity strip lists). Declared here only so it shows up in --help — without
     // this, callers can't discover that the session model is selectable.
-    .option('--model <model>', 'Model for the Claude session, forwarded to claude (e.g. sonnet, opus, or a full id like claude-sonnet-4-6)')
+    .option('--model <model>', 'Model for the Claude session, forwarded to claude (e.g. sonnet, opus, or a full id like claude-sonnet-5)')
     .allowUnknownOption(true)
     .allowExcessArguments(true)
     .action(async (opts) => {
@@ -822,8 +821,9 @@ export const claudeCommand = new Command('claude')
                 allArgs.push('--verbose');
             }
         }
-        // Resolve full path on Windows so we can avoid shell:true, which
-        // passes args through cmd.exe and mangles quotes/special chars.
+        // Resolve the real path on Windows; spawnCommand then routes the `.cmd`
+        // shim through cmd.exe with verbatim args (a bare `spawn` of a `.cmd`
+        // throws EINVAL on Node >=18.20.2/20.12.2 - the CVE-2024-27980 fix).
         const claudeCmd = resolveCommand('claude');
         const childEnv = { ...process.env };
         // Gate hook-based capture: when the daemon is streaming via
@@ -844,7 +844,7 @@ export const claudeCommand = new Command('claude')
         // `-p` runs skip the dialog already, so this is only needed interactively.
         if (!nonInteractive)
             markFolderTrusted(process.cwd());
-        const child = spawn(claudeCmd, allArgs, {
+        const child = spawnCommand(claudeCmd, allArgs, {
             stdio: 'inherit',
             cwd: process.cwd(),
             env: childEnv,
@@ -945,10 +945,10 @@ function formatNewProjectLabel(existingSlugs) {
     const slug = suggestProjectName(existingSlugs);
     const root = getProjectsRoot();
     const home = homedir();
-    const display = root.startsWith(home + '/') || root === home
+    const display = root === home || root.startsWith(home + sep)
         ? '~' + root.slice(home.length)
         : root;
-    return `${display}/${slug}`;
+    return `${display}${sep}${slug}`;
 }
 /** Run the size-tier scan, surface the right UX:
  *    - easy   → silent, return true.

package/dist/commands/email.js

@@ -7,7 +7,8 @@ function collect(value, prev) {
     return [...prev, value];
 }
 export const emailCommand = new Command('email')
-    .description('Send email from the Gipity platform (gipity@gipity.ai). Omit --to to self-send.')
+    .description('Send email')
+    .addHelpText('after', '\nSends from gipity@gipity.ai. Omit --to to self-send.')
     .requiredOption('--subject <subject>', 'Email subject')
     .requiredOption('--body <body>', 'Email body (plain text)')
     .option('--to <email>', 'Recipient (repeatable; omit for self-send)', collect, [])

package/dist/commands/gmail.js

@@ -3,7 +3,8 @@ import { get, post } from '../api.js';
 import { run, printList, printResult } from '../helpers/index.js';
 import { muted } from '../colors.js';
 export const gmailCommand = new Command('gmail')
-    .description('Send, reply, search, or read via your Gmail (user channel - separate from `gipity email`)');
+    .description('Use your Gmail')
+    .addHelpText('after', '\nSend, reply, search, or read via your own Gmail (separate from `gipity email`).');
 gmailCommand
     .command('search <query...>')
     .description('Search your Gmail (standard Gmail search syntax)')

package/dist/commands/init.js

@@ -22,7 +22,8 @@ function resolveTools(forFlag) {
     return SUPPORTED_TOOLS.filter(t => requested.includes(t.key) || (!t.optIn && requested.includes('all')));
 }
 export const initCommand = new Command('init')
-    .description('Link this directory to a Gipity project (writes primer files so your AI coding tool understands Gipity)')
+    .description('Link this directory to a project')
+    .addHelpText('after', '\nWrites CLAUDE.md/AGENTS.md primer files so your AI coding tool understands Gipity.')
     .argument('[name]', 'Project name/slug (defaults to current directory name)')
     .option('--agent <guid>', 'Agent GUID to use')
     .option('--for <tools>', `Which AI tool primer files to write (comma-separated). Default: all except aider (opt-in - it also writes .aider.conf.yml). Choices: ${TOOL_KEYS.join(', ')}, all`)

package/dist/commands/job.js

@@ -4,7 +4,8 @@ import { requireConfig } from '../config.js';
 import { error as clrError, bold, muted, success, warning as warn } from '../colors.js';
 import { run, printList } from '../helpers/index.js';
 export const jobCommand = new Command('job')
-    .description('Long-running jobs - CPU sandbox or GPU via Modal (gpu-small=L4, gpu-medium=A10G, gpu-large=A100, gpu-huge=H100). Declared in gipity.yaml jobs: phase; submit + poll via subcommands below.');
+    .description('Run long jobs (CPU/GPU)')
+    .addHelpText('after', '\nCPU sandbox or GPU (gpu-small=L4, gpu-medium=A10G, gpu-large=A100, gpu-huge=H100). Declared in the gipity.yaml jobs: phase; submit and poll via the subcommands below.');
 jobCommand
     .command('list')
     .description('List jobs')

package/dist/commands/login.js

@@ -34,6 +34,7 @@ export const loginCommand = new Command('login')
             process.exit(1);
         }
         await publicPost('/auth/login', { email });
+        console.log('');
         console.log('Check your email for a 6-digit code.');
         code = await prompt('Code: ');
         await verify(email, code);

package/dist/commands/notify.js

@@ -4,7 +4,8 @@ import { resolveProjectContext } from '../config.js';
 import { bold, muted, success, warning } from '../colors.js';
 import { run } from '../helpers/index.js';
 export const notifyCommand = new Command('notify')
-    .description('Gipity Notify (web push): send a test notification or inspect subscriptions');
+    .description('Web push notifications')
+    .addHelpText('after', '\nGipity Notify: send a test notification or inspect subscriptions.');
 notifyCommand
     .command('test')
     .description('Send a test push notification to yourself, a user, or everyone')

package/dist/commands/page.js

@@ -10,7 +10,7 @@ import { pageFetchCommand } from './page-fetch.js';
 // top-level surface lean and makes the siblings discoverable via `page --help`.
 // `inspect` is the rendered DOM (browser); `fetch` is the raw asset (plain HTTP).
 export const pageCommand = new Command('page')
-    .description('Inspect, evaluate, screenshot, multi-client test, and verify raw files of web pages (page inspect | eval | screenshot | test | fetch)')
+    .description('Inspect web pages')
     .addCommand(pageInspectCommand)
     .addCommand(pageEvalCommand)
     .addCommand(pageScreenshotCommand)

package/dist/commands/payments.js

@@ -19,7 +19,8 @@ function renderStatus(status) {
     }
 }
 export const paymentsCommand = new Command('payments')
-    .description('Connect Stripe so your app can charge its users (one-time + subscriptions)');
+    .description('Charge your users via Stripe')
+    .addHelpText('after', '\nAccept one-time purchases and subscriptions. Set up with `gipity payments connect`.');
 paymentsCommand
     .command('connect')
     .description('Start (or resume) Stripe onboarding for this app — prints a link to finish in your browser')

package/dist/commands/plan.js

@@ -31,7 +31,7 @@ function renderLimits(limits, indent = '') {
     }
 }
 export const planCommand = new Command('plan')
-    .description('Show your current subscription plan and limits')
+    .description('Show your plan')
     .option('--json', 'Output as JSON')
     .action((opts) => run('Plan', async () => {
     const [limitsRes, plansRes] = await Promise.all([

package/dist/commands/remove.js

@@ -7,7 +7,7 @@ import { run } from '../helpers/index.js';
 import { confirm } from '../utils.js';
 import { createProgressReporter, withSpinner } from '../progress.js';
 export const removeCommand = new Command('remove')
-    .description('Remove an installed kit from the project (inverse of `gipity add <kit>`).')
+    .description('Remove a kit')
     .argument('<kit>', 'Kit key/directory under src/packages/ to remove')
     .option('-y, --yes', 'Skip the confirmation prompt')
     .option('--json', 'Output as JSON')

package/dist/commands/secrets.js

@@ -12,7 +12,8 @@ async function scopeQuery(opts) {
     return `scope=project&app_guid=${config.projectGuid}`;
 }
 export const secretsCommand = new Command('secrets')
-    .description('Encrypted secrets (API keys, tokens) for your app — read in functions via secrets.get("NAME")');
+    .description('Manage app secrets')
+    .addHelpText('after', '\nEncrypted API keys and tokens for your app, read in functions via secrets.get("NAME").');
 secretsCommand
     .command('list')
     .alias('ls')

package/dist/commands/service.js

@@ -20,7 +20,8 @@ const SERVICES = [
     { name: 'location/geocode', method: 'POST', desc: 'Reverse geocode ({ lat, lon })' },
 ];
 export const serviceCommand = new Command('service')
-    .description('Call a Gipity app service (LLM, image, music, TTS, ...)');
+    .description('Call an app service')
+    .addHelpText('after', '\nCall a Gipity app service: LLM, image, music, TTS, and more.');
 serviceCommand
     .command('list')
     .description('List callable app services')

package/dist/commands/sync.js

@@ -3,7 +3,8 @@ import { sync } from '../sync.js';
 import { createProgressReporter } from '../progress.js';
 import { error as clrError, muted } from '../colors.js';
 export const syncCommand = new Command('sync')
-    .description('Sync files (a .gipityignore at the project root excludes paths, gitignore-style)')
+    .description('Sync files')
+    .addHelpText('after', '\nAdd a .gipityignore at the project root to exclude paths (gitignore-style).')
     .option('--plan', 'Print the plan without applying any changes')
     .option('--force', 'Bypass the bulk-deletion guard')
     .option('--prune', 'Remove files that exist on Gipity but not locally (applies the bulk deletes the guard defers)')

package/dist/commands/test.js

@@ -168,6 +168,12 @@ export const testCommand = new Command('test')
         console.log(clrError(`No tests matched filter: ${filterPath}`));
         process.exit(1);
     }
+    if (!filterPath && data.total === 0 && data.results.length === 0) {
+        console.log(muted('No tests ran - this app has no tests/*.test.js files.'));
+        console.log(muted('gipity test runs server-function tests only; a frontend-only app (no functions/) has nothing here to run.'));
+        console.log(muted('Verify a frontend app by driving the live page: gipity page inspect <url> (or gipity page eval).'));
+        return;
+    }
     if (data.status === 'failed' && data.errorMessage) {
         console.log(clrError(`Run failed: ${data.errorMessage}`));
         console.log('');

package/dist/commands/text.js

@@ -140,7 +140,8 @@ const analyzeCommand = new Command('analyze')
 // Parent namespace. One capability today (analyze); namespaced for a lean
 // top-level surface and room for future text operations.
 export const textCommand = new Command('text')
-    .description(`Deterministic text analysis - char/word counts, frequency, occurrences (${brand('text analyze')})`)
+    .description('Analyze text')
+    .addHelpText('after', `\nDeterministic char/word counts, frequency, and occurrences (${brand('text analyze')}). Local, no network.`)
     .addCommand(analyzeCommand);
 textCommand.action(() => {
     textCommand.help();

package/dist/commands/token.js

@@ -3,7 +3,8 @@ import { get, post, del } from '../api.js';
 import { bold, muted, success, warning } from '../colors.js';
 import { run, printList } from '../helpers/index.js';
 export const tokenCommand = new Command('token')
-    .description('Manage agent API tokens (gip_at_*) for headless agents and CI');
+    .description('Manage API tokens')
+    .addHelpText('after', '\nLong-lived agent API tokens (gip_at_*) for headless agents and CI.');
 const fmtDate = (d) => (d ? new Date(d).toLocaleDateString() : 'never');
 tokenCommand
     .command('create')

package/dist/config.js

@@ -134,8 +134,8 @@ export async function resolveProjectContext(opts) {
         }
         const agents = await get(`/projects/${match.short_guid}/agents`);
         const accountSlug = await getAccountSlug();
-        console.error(dim(`→ One-off mode: targeting project "${match.slug}" (--project override).`));
-        console.error(dim(`→ Files are not synced - outputs will also be downloaded to ./ for you.`));
+        console.error(dim(`→ (project: ${match.slug} · no file sync)`));
+        console.error('');
         return {
             config: {
                 projectGuid: match.short_guid,
@@ -163,8 +163,8 @@ export async function resolveProjectContext(opts) {
         console.error('Could not resolve your Home project - please contact support.');
         process.exit(1);
     }
-    console.error(dim(`→ One-off mode: no .gipity.json in cwd, using your Home project on the server.`));
-    console.error(dim(`→ Files are not synced - outputs will also be downloaded to ./ for you.`));
+    console.error(dim(`→ (project: ${res.data.projectName} · no file sync)`));
+    console.error('');
     return {
         config: {
             projectGuid: res.data.projectGuid,

package/dist/helpers/output.js

@@ -3,16 +3,38 @@
  *  can close a frame even when a command ends via process.exit() and so skips
  *  the postAction hook. */
 let frameOpen = false;
+/** Count of newlines currently at the tail of everything written to stdout. Kept
+ *  live by wrapping stdout.write so the frame can close to EXACTLY one trailing
+ *  blank line instead of blindly appending one - the blind append doubled the
+ *  blank whenever a command's own output already ended in a newline (e.g. an
+ *  agent reply printed with a trailing '\n'). */
+let trailingNewlines = 0;
+function trackTrailing(chunk) {
+    const s = typeof chunk === 'string'
+        ? chunk
+        : (chunk && typeof chunk.toString === 'function' ? String(chunk) : '');
+    if (!s.length)
+        return;
+    const run = /\n*$/.exec(s)?.[0].length ?? 0;
+    // A chunk that is all newlines extends the current run; otherwise it resets it
+    // to just this chunk's own trailing run.
+    trailingNewlines = run === s.length ? trailingNewlines + run : run;
+}
 /**
  * Bracket every human (non-JSON) command's stdout with exactly one leading and
  * one trailing blank line, so output is visually separated from the shell
  * prompt and consistent across commands. JSON output is left untouched so it
  * stays pipe/parse-clean.
  *
+ * The trailing blank is added by TOP-UP, not blind append: one blank line means
+ * the stream ends in two newlines (the content's own line terminator plus one
+ * empty line), so we only write the newlines still missing. That keeps the
+ * boundary at exactly one blank whether the command ended its output with no
+ * newline, one, or an accidental extra.
+ *
  * Centralizing the frame here is what lets individual commands stop printing
- * their own leading/trailing blank lines (and stops them doubling up at the
- * boundaries). Call once on the root program; Commander runs these lifecycle
- * hooks for the actual subcommand action too.
+ * their own leading/trailing blank lines. Call once on the root program;
+ * Commander runs these lifecycle hooks for the actual subcommand action too.
  */
 export function installOutputFrame(program) {
     // Only decorate a real terminal. When stdout is piped or redirected (a relay
@@ -20,6 +42,21 @@ export function installOutputFrame(program) {
     // colors.ts uses for ANSI. This keeps headless `claude -p` stdout empty.
     if (!process.stdout.isTTY)
         return;
+    // Wrap stdout.write to keep `trailingNewlines` current for every byte the
+    // command emits (console.log, spinner, colors all route through here).
+    const origWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (chunk, ...rest) => {
+        trackTrailing(chunk);
+        return origWrite(chunk, ...rest);
+    };
+    const closeFrame = () => {
+        if (!frameOpen)
+            return;
+        frameOpen = false;
+        const need = Math.max(0, 2 - trailingNewlines);
+        if (need > 0)
+            origWrite('\n'.repeat(need));
+    };
     program.hook('preAction', (_thisCommand, actionCommand) => {
         const opts = actionCommand.optsWithGlobals
             ? actionCommand.optsWithGlobals()
@@ -29,18 +66,10 @@ export function installOutputFrame(program) {
         process.stdout.write('\n');
         frameOpen = true;
     });
-    program.hook('postAction', () => {
-        if (frameOpen) {
-            process.stdout.write('\n');
-            frameOpen = false;
-        }
-    });
+    program.hook('postAction', closeFrame);
     // Commands that finish via process.exit() never reach postAction; close the
     // frame from the exit handler instead (sync write, fires on every exit path).
-    process.on('exit', () => {
-        if (frameOpen)
-            process.stdout.write('\n');
-    });
+    process.on('exit', closeFrame);
 }
 /**
  * Print data as JSON or formatted text.

package/dist/knowledge.js

@@ -155,8 +155,10 @@ App services skills (load before calling \`/services/*\` endpoints):
 
 App development skills:
 - \`agent-deploy\` - headless auth via agent API tokens (GIPITY_TOKEN) for unattended deploys
+- \`app-database\` - app Postgres database: migrations, the db helper, transactions, table permissions
 - \`app-debugging\` - debug a deployed app: page inspect/eval, screenshots, function logs
 - \`app-development\` - functions, database, and API
+- \`app-testing\` - testing deployed app functions (ctx.fn.call/callAs, the isolated test DB)
 - \`deploy\` - the deploy pipeline & gipity.yaml manifest
 - \`jobs\` - long-running CPU + GPU compute jobs (Python / Node / bash)
 - \`realtime-scheduled-app\` - recipe: realtime presence/messages + DB function + scheduled poster, end-to-end

package/dist/platform.js

@@ -1,12 +1,16 @@
-import { execSync } from 'child_process';
+import { execSync, spawn, spawnSync } from 'child_process';
 /**
- * Resolve a command to something Node's spawn/spawnSync can launch directly.
+ * Resolve a command to a concrete path when possible.
  *
  * On Windows, npm-installed CLIs (npm, npx, gipity, claude) are `.cmd` batch
- * shims, not `.exe`s. Node's spawn without `shell: true` cannot launch a bare
- * `npm` - it fails with ENOENT and a null exit status. Resolving the real path
- * (preferring `.exe`, falling back to `.cmd`) lets us spawn without `shell: true`
- * (which would otherwise require escaping arguments).
+ * shims, not `.exe`s. A bare `npm` fails to spawn with ENOENT, so we resolve
+ * the real path (preferring a native `.exe`, falling back to the `.cmd` shim).
+ *
+ * NOTE: resolving to the `.cmd` path is NOT enough on its own. Since Node
+ * 18.20.2 / 20.12.2 (the CVE-2024-27980 fix), `spawn`/`spawnSync` REFUSE to
+ * launch a `.cmd`/`.bat` target unless `shell: true` - they throw `EINVAL`.
+ * So always launch a resolved command through `spawnCommand` /
+ * `spawnSyncCommand` below, which route batch shims through cmd.exe safely.
  */
 export function resolveCommand(cmd) {
     if (process.platform !== 'win32')
@@ -23,4 +27,47 @@ export function resolveCommand(cmd) {
         return `${cmd}.cmd`;
     }
 }
+/** True for a Windows batch shim that Node cannot spawn without a shell. */
+export function isBatchShim(cmd) {
+    return process.platform === 'win32' && /\.(cmd|bat)$/i.test(cmd);
+}
+/**
+ * Build a cmd.exe invocation that launches a `.cmd`/`.bat` shim with its args
+ * passed through verbatim - the correct way to run a batch file post-CVE
+ * without `shell: true` mangling argument quoting.
+ *
+ * `cmd.exe /d /s /c "<line>"`: `/d` skips AutoRun, `/s` + the wrapping outer
+ * quotes make cmd strip exactly the first and last quote of the whole line
+ * (leaving each already-quoted token intact). We quote every token ourselves
+ * and set `windowsVerbatimArguments` so Node hands our line to cmd untouched.
+ */
+export function winBatchInvocation(cmd, args) {
+    const comspec = process.env.ComSpec || 'cmd.exe';
+    // Double-quote each token; escape any embedded double-quote as "" (cmd's
+    // in-quote escape). Our call sites pass flags/paths/guids with no cmd
+    // metacharacters, so this conservative quoting is sufficient and safe.
+    const quote = (t) => `"${String(t).replace(/"/g, '""')}"`;
+    const line = [cmd, ...args].map(quote).join(' ');
+    return { file: comspec, args: ['/d', '/s', '/c', `"${line}"`] };
+}
+/**
+ * Drop-in `spawn` that survives Windows batch shims. When `cmd` is a `.cmd`/
+ * `.bat` on win32, it is launched via cmd.exe with verbatim arguments;
+ * otherwise this is a plain `spawn`. Use for anything from `resolveCommand`.
+ */
+export function spawnCommand(cmd, args = [], options = {}) {
+    if (isBatchShim(cmd)) {
+        const inv = winBatchInvocation(cmd, args);
+        return spawn(inv.file, inv.args, { ...options, windowsVerbatimArguments: true });
+    }
+    return spawn(cmd, [...args], options);
+}
+/** Drop-in `spawnSync` counterpart of {@link spawnCommand}. */
+export function spawnSyncCommand(cmd, args = [], options = {}) {
+    if (isBatchShim(cmd)) {
+        const inv = winBatchInvocation(cmd, args);
+        return spawnSync(inv.file, inv.args, { ...options, windowsVerbatimArguments: true });
+    }
+    return spawnSync(cmd, [...args], options);
+}
 //# sourceMappingURL=platform.js.map

package/dist/relay/daemon.js

@@ -1,27 +1,4 @@
-/**
- * Gipity relay daemon - the `gipity-relay` long-running helper that backs
- * `gipity relay run`. Runs two concurrent loops against the paired Gipity
- * account using the device's bearer token:
- *
- *   1. Heartbeat every 60s → POST /remote-devices/heartbeat. Drives the
- *      web CLI's presence indicator.
- *   2. Long-poll → GET /remote-devices/next. On a 200 claim, look up the
- *      dispatch's project in the local allowlist, spawn `gipity claude -p
- *      "<msg>"` in that project's cwd, wait for it to exit, POST ack.
- *
- * The conversation stream (prompts, tool calls, assistant output) flows
- * back to the web CLI *automatically* via the capture hooks installed in
- * `.claude/settings.json` - the daemon itself doesn't forward content.
- *
- * Graceful exit:
- *   - SIGINT / SIGTERM → stop both loops, wait for in-flight child, exit 0.
- *   - 401 from heartbeat or /next → device was revoked; exit 0.
- *   - Any other backend error → log and retry with exponential backoff.
- *
- * See docs/feature-backlog/gipity-relay-phases.md (Phase A Step 7).
- */
-import { spawn } from 'child_process';
-import { resolveCommand } from '../platform.js';
+import { resolveCommand, spawnCommand } from '../platform.js';
 import { appendFileSync, mkdirSync, existsSync, readFileSync, writeFileSync, chmodSync, closeSync, openSync, unlinkSync } from 'fs';
 import { stat, readFile } from 'fs/promises';
 import { createInterface } from 'readline';
@@ -528,14 +505,15 @@ function isSafeSessionId(s) {
     return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(s);
 }
 /** Resolve Claude Code's on-disk transcript path for measuring resume
- *  size. Claude encodes the project cwd into a slug by replacing `/` with
- *  `-`. We only read this file cosmetically (to show "resume 5 KB" in the
- *  Invoking marker); actual capture is via stream-json. Returns null for
+ *  size. Claude encodes the project cwd into a slug by replacing every
+ *  non-alphanumeric char with `-` (so `/`, and on Windows `\` and `:`, all
+ *  collapse). We only read this file cosmetically (to show "resume 5 KB" in
+ *  the Invoking marker); actual capture is via stream-json. Returns null for
  *  a sessionId that fails the safety check. */
 function transcriptPathFor(cwd, sessionId) {
     if (!isSafeSessionId(sessionId))
         return null;
-    const slug = cwd.replace(/\//g, '-');
+    const slug = cwd.replace(/[^a-zA-Z0-9]/g, '-');
     return join(homedir(), '.claude', 'projects', slug, `${sessionId}.jsonl`);
 }
 /** `18.4s` when under a minute, `3:12.2` above. */
@@ -867,7 +845,7 @@ async function spawnSync(cwd, timeoutMs) {
     // verbatim (it may be a full path); only the default name is resolved.
     const cmd = process.env.GIPITY_RELAY_CLAUDE_CMD || resolveCommand('gipity');
     return new Promise((resolve, reject) => {
-        const child = spawn(cmd, ['sync', '--json'], {
+        const child = spawnCommand(cmd, ['sync', '--json'], {
             cwd,
             env: process.env,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -921,7 +899,7 @@ export async function spawnGipityClaude(args, cwd, d) {
     const fullArgs = [...args, '--output-format', 'stream-json', '--verbose'];
     const env = { ...process.env, GIPITY_CONVERSATION_GUID: d.conversation_guid };
     return new Promise((resolve, reject) => {
-        const child = spawn(cmd, fullArgs, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+        const child = spawnCommand(cmd, fullArgs, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
         // `exited` fires when the child fully unwinds (exit event). Callers
         // like `killRunningForConv` await this before spawning a replacement
         // so the outgoing child has a chance to post its cancelled marker

package/dist/relay/installers.js

@@ -126,6 +126,14 @@ WantedBy=default.target
 function windowsTaskPlan(cliPath) {
     const taskName = 'GipityRelay';
     const path = join(homedir(), 'AppData', 'Local', 'Gipity', 'relay-task.xml');
+    // Launch through node.exe explicitly. Task Scheduler's <Command> runs the
+    // target via CreateProcess, and a `.js` cliPath (what resolveCliPath yields)
+    // would resolve to its file association - Windows Script Host - which chokes
+    // on the shebang with "Invalid character" (800A03F6). Passing the entry as a
+    // node argument runs it under Node like every other platform.
+    const runsViaNode = /\.[cm]?js$/i.test(cliPath);
+    const command = runsViaNode ? process.execPath : cliPath;
+    const argLine = runsViaNode ? `"${cliPath}" relay run` : 'relay run';
     const content = `<?xml version="1.0" encoding="UTF-16"?>
 <Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
   <RegistrationInfo>
@@ -151,8 +159,8 @@ function windowsTaskPlan(cliPath) {
   </Settings>
   <Actions>
     <Exec>
-      <Command>${cliPath}</Command>
-      <Arguments>relay run</Arguments>
+      <Command>${command}</Command>
+      <Arguments>${argLine}</Arguments>
     </Exec>
   </Actions>
 </Task>

package/dist/setup.js

@@ -5,7 +5,7 @@ import { resolve, join, dirname } from 'path';
 import { homedir } from 'os';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { resolveCommand } from './platform.js';
+import { resolveCommand, spawnSyncCommand } from './platform.js';
 import { SKILLS_CONTENT, BUILD_VS_NON_BUILD_RULE, DEFINITION_OF_DONE } from './knowledge.js';
 export { SKILLS_CONTENT };
 /** Canonical list of workstation artifacts that are NOT part of the project.
@@ -137,7 +137,7 @@ export const GIPITY_MARKETPLACE_REPO = 'GipityAI/claude-plugin';
 // an installed plugin when the marketplace advances - only an explicit
 // `plugin install`/`update` does - so this constant is how a CLI upgrade tells
 // ensureGipityPluginInstalled() to refresh a stale user-scope install.
-export const GIPITY_PLUGIN_VERSION = '0.4.0';
+export const GIPITY_PLUGIN_VERSION = '0.4.1';
 /** True for hook commands the CLI itself wrote into settings.json in past
  *  versions. Matched by signature so migration strips exactly our own
  *  entries and never touches user-authored hooks. */
@@ -288,11 +288,11 @@ export function ensureGipityPluginInstalled() {
     // without an explicit path, so resolve it (otherwise the install silently
     // ENOENTs and the plugin's hooks never land at user scope).
     const claudeCmd = resolveCommand('claude');
-    spawnSync(claudeCmd, ['plugin', 'marketplace', 'update', GIPITY_MARKETPLACE_NAME], {
+    spawnSyncCommand(claudeCmd, ['plugin', 'marketplace', 'update', GIPITY_MARKETPLACE_NAME], {
         stdio: 'ignore',
         timeout: 120_000,
     });
-    spawnSync(claudeCmd, ['plugin', 'install', GIPITY_PLUGIN_ID, '--scope', 'user'], {
+    spawnSyncCommand(claudeCmd, ['plugin', 'install', GIPITY_PLUGIN_ID, '--scope', 'user'], {
         stdio: 'ignore',
         timeout: 120_000,
     });