@pareto4/pp-core 1.9.0 → 1.11.0

package/pp-core/bin/lib/vault.cjs

@@ -35,14 +35,14 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const git_provider_cjs_1 = require("./git-provider.cjs");
+const vault_coordinates_cjs_1 = require("./vault-coordinates.cjs");
 const CLONE_TIMEOUT_MS = 60_000; // explicit cap so a hung clone surfaces as failed → next tier
 const REVPARSE_TIMEOUT_MS = 10_000;
 // Default built-in config values — Phase 12 reads-with-default because the
 // capability.json that declares these keys lands in plan 12-03. The impl must
 // never depend on the registry supplying them.
 const DEFAULT_TTL_HOURS = 24;
-const DEFAULT_FALLBACK_REPO = 'pareto4/pareto-vault';
-const DEFAULT_FALLBACK_REF = 'main';
 // ─── Default exec seam ──────────────────────────────────────────────────────────
 const _defaultExec = {
     glab: (args, opts = {}) => (0, shell_command_projection_cjs_1.execTool)('glab', args, opts),
@@ -175,12 +175,27 @@ function atomicSwap(stageDir, finalDir) {
  *   - fallback tier → always whole-repo (glab→git); never applies vaultPaths.
  * Returns a coarse ok/fail classification; the raw stderr is recorded for diagnosis.
  */
+// `isLiteralCloneTarget` — the single definition lives in `src/git-provider.cts`
+// (imported above). Do not reintroduce a local copy here: a read/write
+// divergence in this predicate was defect P-1 in Phase 29.
+/**
+ * Doc comment: cloneTier's sparse, whole-repo and fallback paths all route
+ * through the provider seam now — composition (`composeCloneTarget`), host
+ * env (`cloneEnv`), and whether a host CLI may be spawned (`providerUsesHostCli`)
+ * are all provider-driven. `glab` is only ever attempted when the resolved
+ * provider has one (gitlab); azure (and any future host-CLI-less provider)
+ * goes straight to git.
+ */
 function cloneTier(tier, exec, destDir, warnings) {
-    const { repo, ref, host } = tier;
-    const url = `https://${host}/${repo}.git`;
+    const { repo, ref, host, provider } = tier;
+    const literal = (0, git_provider_cjs_1.isLiteralCloneTarget)(repo.trim());
+    const composed = (0, git_provider_cjs_1.composeCloneTarget)(provider, repo, host);
+    if (composed.warnings.length > 0)
+        warnings.push(...composed.warnings);
+    const url = composed.url;
     // Sparse path (client tier with explicit vaultPaths) — git only.
     if (tier.kind === 'client' && tier.paths && tier.paths.length > 0) {
-        const cl = exec.git(['clone', '--no-checkout', '--depth', '1', '--branch', ref, '--single-branch', url, destDir], { env: { GITLAB_HOST: host }, timeout: CLONE_TIMEOUT_MS });
+        const cl = exec.git(['clone', '--no-checkout', '--depth', '1', '--branch', ref, '--single-branch', '--', url, destDir], { env: (0, git_provider_cjs_1.cloneEnv)(provider, host), timeout: CLONE_TIMEOUT_MS });
         if (cl.exitCode !== 0)
             return { ok: false, stderr: cl.stderr };
         exec.git(['sparse-checkout', 'init', '--cone'], { cwd: destDir, timeout: CLONE_TIMEOUT_MS });
@@ -193,18 +208,31 @@ function cloneTier(tier, exec, destDir, warnings) {
     if (tier.kind === 'client') {
         warnings.push('fetching whole vault repo — set client.vaultPaths to limit');
     }
-    // Whole-repo clone: glab first (uses stored glab auth), then git fallback
-    // (credential-helper). A missing glab binary surfaces as exitCode 127.
-    const g = exec.glab(['repo', 'clone', repo, destDir, '--', '--depth', '1', '--branch', ref, '--single-branch'], { env: { GITLAB_HOST: host }, timeout: CLONE_TIMEOUT_MS });
-    if (g.exitCode === 0)
-        return { ok: true };
-    // Reset the dest before the git attempt so a partially-populated dir from a
-    // failed glab clone can't make `git clone` fail on a non-empty target.
-    safeRm(destDir);
-    const gi = exec.git(['clone', '--depth', '1', '--branch', ref, '--single-branch', url, destDir], { env: { GITLAB_HOST: host }, timeout: CLONE_TIMEOUT_MS });
+    // A literal path/URL is not a glab coordinate — go straight to git. Trying
+    // glab first would only spend a failed subprocess before the same fallback.
+    if (literal) {
+        const direct = exec.git(['clone', '--depth', '1', '--branch', ref, '--single-branch', '--', url, destDir], { env: (0, git_provider_cjs_1.cloneEnv)(provider, host), timeout: CLONE_TIMEOUT_MS });
+        return direct.exitCode === 0 ? { ok: true } : { ok: false, stderr: direct.stderr };
+    }
+    // Whole-repo clone: the host CLI first (uses its own stored auth), when the
+    // resolved provider has one, then git fallback (credential-helper). A
+    // provider with no host CLI (azure) skips straight to git — no glab
+    // attempt, no partially-populated dir to reset.
+    let hostCliStderr = '';
+    if ((0, git_provider_cjs_1.providerUsesHostCli)(provider)) {
+        const g = exec.glab(['repo', 'clone', repo, destDir, '--', '--depth', '1', '--branch', ref, '--single-branch'], { env: (0, git_provider_cjs_1.cloneEnv)(provider, host), timeout: CLONE_TIMEOUT_MS });
+        if (g.exitCode === 0)
+            return { ok: true };
+        hostCliStderr = g.stderr;
+        // Reset the dest before the git attempt so a partially-populated dir from
+        // a failed host-CLI clone can't make `git clone` fail on a non-empty
+        // target.
+        safeRm(destDir);
+    }
+    const gi = exec.git(['clone', '--depth', '1', '--branch', ref, '--single-branch', '--', url, destDir], { env: (0, git_provider_cjs_1.cloneEnv)(provider, host), timeout: CLONE_TIMEOUT_MS });
     if (gi.exitCode === 0)
         return { ok: true };
-    return { ok: false, stderr: gi.stderr || g.stderr };
+    return { ok: false, stderr: gi.stderr || hostCliStderr };
 }
 // ─── Degrade (never-abort terminal states) ─────────────────────────────────────
 function priorContentExists(vaultDirPath) {
@@ -280,43 +308,82 @@ function vaultFetch(cwd, deps = {}) {
         if (!node_fs_1.default.existsSync(node_path_1.default.join(cwd, '.platform-bindings.json'))) {
             return degrade(finalDir, 'no .platform-bindings.json', warnings);
         }
+        // PROV-01: resolve the configured provider once per fetch, from
+        // `.planning/config.json` alone — never inferred from a host/repo string.
+        // Any warning (e.g. an unrecognized value) is folded into the same
+        // `warnings` array the rest of this function already accumulates.
+        const providerResolution = (0, git_provider_cjs_1.resolveProvider)(cwd);
+        const provider = providerResolution.provider;
+        if (providerResolution.warnings.length > 0)
+            warnings.push(...providerResolution.warnings);
         const client = isObject(bindings.client) ? bindings.client : null;
-        const platform = isObject(bindings.platform) ? bindings.platform : null;
-        const clientRepo = client && typeof client.vaultRepo === 'string' ? client.vaultRepo : null;
-        const clientRef = client && typeof client.vaultRef === 'string' && client.vaultRef ? client.vaultRef : 'main';
-        const clientHost = client && typeof client.vaultHost === 'string' && client.vaultHost ? client.vaultHost : null;
         const clientPaths = client && Array.isArray(client.vaultPaths)
             ? client.vaultPaths.filter((p) => typeof p === 'string' && p.length > 0)
             : null;
-        const platformHost = platform && typeof platform.host === 'string' && platform.host ? platform.host : null;
-        // Config (read-with-default; capability declaration lands in 12-03).
+        // CFG-01: every read-path coordinate (repo, ref, host) for both tiers now
+        // comes from the single resolver in ./vault-coordinates.cjs — no inline
+        // host-fallback chain and no compiled-in shared-repo/ref constant survive
+        // here. Each resolution's `warnings` are folded into the same
+        // accumulator the provider resolution's warnings already reach; the
+        // shared fold is deduped against what the client fold already added so a
+        // `platform.host` read from `.planning/config.json` (D-09), which both
+        // resolutions can independently surface, reaches the manifest exactly
+        // once rather than twice.
+        const clientCoord = (0, vault_coordinates_cjs_1.resolveClientCoordinates)(cwd, provider);
+        if (clientCoord.warnings.length > 0)
+            warnings.push(...clientCoord.warnings);
+        const sharedCoord = (0, vault_coordinates_cjs_1.resolveSharedCoordinates)(cwd, provider);
+        for (const w of sharedCoord.warnings) {
+            if (!warnings.includes(w))
+                warnings.push(w);
+        }
+        // D-02: kept in a local rather than folded into `fallbackReason` here —
+        // composed at the terminal degrade call below, where it must join
+        // whichever client-tier failure reason (if any) is already in play
+        // without clobbering it.
+        const suppressedReason = sharedCoord.suppressedReason;
+        // Config (read-with-default; capability declaration lands in 12-03). TTL
+        // is not a coordinate — the resolver does not own it.
         const ttlRaw = cfgGet(cwd, 'vault.cache_ttl_hours', DEFAULT_TTL_HOURS);
         const ttlHours = Number.isFinite(Number(ttlRaw)) ? Number(ttlRaw) : DEFAULT_TTL_HOURS;
-        const fbRepoRaw = cfgGet(cwd, 'vault.fallback_repo', DEFAULT_FALLBACK_REPO);
-        const fbRepo = typeof fbRepoRaw === 'string' ? fbRepoRaw : DEFAULT_FALLBACK_REPO;
-        const fbRefRaw = cfgGet(cwd, 'vault.fallback_ref', DEFAULT_FALLBACK_REF);
-        const fbRef = typeof fbRefRaw === 'string' && fbRefRaw ? fbRefRaw : DEFAULT_FALLBACK_REF;
-        // Build the ladder, skipping empty entries.
+        // Build the ladder, skipping empty entries. One resolved provider per
+        // project — attached to BOTH the client and the fallback tier, never
+        // re-resolved per tier (D-01: one provider per project is a permanent
+        // decision; a client does not straddle two providers). T-30-14's
+        // consequence is now materially narrower than it was: previously an
+        // azure-provider project addressed the shared fallback tier with the
+        // azure form because a built-in gitlab-only default was always applied;
+        // now `resolveSharedCoordinates` suppresses the shared tier entirely for
+        // a non-gitlab project with no `vault.fallback_repo` configured (D-02),
+        // so there is no fallback tier to address at all in that case. The fix
+        // for the azure-composes-a-gitlab-URL hazard is per-client shared
+        // coordinates (`vault.fallback_repo` / `vault.fallback_host`), not
+        // per-tier provider selection — PROV-03 still forbids a provider
+        // spawning another provider's CLI, so an azure project that DOES
+        // configure a gitlab shared vault still fetches it with plain git rather
+        // than glab.
         const ladder = [];
-        if (clientRepo) {
+        if (clientCoord.repo) {
             ladder.push({
-                repo: clientRepo,
-                ref: clientRef,
+                repo: clientCoord.repo,
+                ref: clientCoord.ref,
                 kind: 'client',
-                host: clientHost || platformHost || 'gitlab.com',
+                host: clientCoord.host,
                 paths: clientPaths && clientPaths.length > 0 ? clientPaths : null,
+                provider,
             });
         }
-        if (fbRepo) {
+        if (sharedCoord.repo) {
             ladder.push({
-                repo: fbRepo,
-                ref: fbRef,
+                repo: sharedCoord.repo,
+                ref: sharedCoord.ref,
                 kind: 'fallback',
-                host: platformHost || 'gitlab.com',
+                host: sharedCoord.host,
                 paths: null,
+                provider,
             });
         }
-        let fallbackReason = clientRepo ? null : 'no client vault configured';
+        let fallbackReason = clientCoord.repo ? null : 'no client vault configured';
         // Cache-freshness short-circuit (no clone). Fresh ⇔ prior was a real fetch,
         // ttl > 0, age within ttl, and the ref matches the top tier we'd fetch.
         const prior = readManifest(finalDir);
@@ -385,14 +452,26 @@ function vaultFetch(cwd, deps = {}) {
                 fetchedAt: new Date().toISOString(),
                 files,
                 fallbackReason: tier.kind === 'fallback' ? fallbackReason : null,
+                host: tier.host,
             };
             if (warnings.length > 0)
                 manifest.warnings = warnings.slice();
             writeManifest(finalDir, manifest);
             return manifest;
         }
-        // All tiers failed/empty — keep prior cache or record a miss. Never throws.
-        return degrade(finalDir, fallbackReason, warnings);
+        // All tiers failed/empty — keep prior cache or record a miss. Never
+        // throws. D-02: when the shared tier was suppressed, that reason joins
+        // whichever client-tier failure reason is already in `fallbackReason`
+        // (or stands alone when there is none) rather than replacing it, so a
+        // degraded manifest on a non-gitlab project with no shared vault
+        // configured explains both why the client tier failed and why there was
+        // no fallback to try.
+        const degradeReason = suppressedReason
+            ? fallbackReason
+                ? `${fallbackReason}; ${suppressedReason}`
+                : suppressedReason
+            : fallbackReason;
+        return degrade(finalDir, degradeReason, warnings);
     }
     catch (e) {
         // Any unexpected throw must degrade, never propagate to a non-zero exit.
@@ -648,28 +727,63 @@ function vaultSummary(cwd) {
  * (Layer 1); this in-process assertion is advisory only and exists so a buggy
  * caller cannot resolve a write to the wrong repo without tripping a hard throw.
  *
- * Reuses the in-scope binding/config readers (no new imports). Throws when:
+ * D-10 (Phase 31, CFG-02): identity is the resolved `(repo, host)` pair for
+ * BOTH tiers, not the repo slug alone — the same `group/project` path on two
+ * different hosts is two different vaults, so comparing repo strings only
+ * left a hole the moment the host became configurable. Both pairs are
+ * resolved through the one coordinate resolver in `./vault-coordinates.cjs`
+ * (the same resolver the read path uses) rather than read here a second
+ * time.
+ *
+ * D-11: the shared-tier check is SKIPPED, not failed, when no shared
+ * coordinates resolve (`resolveSharedCoordinates(...).repo === null`, e.g.
+ * `vault.fallback_repo` set to the empty string, or unset on a non-gitlab
+ * provider). Failing closed was rejected — it would block a client from
+ * promoting until their own shared vault exists, breaking ROADMAP SC3. The
+ * residual risk is bounded three ways: the client-pair match check below
+ * still gates every write regardless of whether the shared check ran; a
+ * refusal caused by the skip says so explicitly in its message rather than
+ * silently; and this whole guard is only the advisory Layer-2 control — the
+ * authoritative write-isolation boundary remains the host's group/role
+ * topology, which is what makes the permissive branch acceptable.
+ *
+ * Throws when:
  *   - no client vault is configured;
- *   - the target is the shared fallback vault; or
- *   - the target is any repo other than the configured client vault.
+ *   - the target pair equals the resolved shared pair (the built-in Pareto
+ *     default or a project-configured shared vault); or
+ *   - the target pair is not the resolved client pair.
  *
  * @param cwd        Project root (parent of `.planning/`).
  * @param targetRepo The `group/project` slug a write-back would push to.
+ * @param targetHost The host a write-back would push to. Required, with no
+ *                    default: an optional host on a security control means a
+ *                    caller that forgets it gets a check that trivially
+ *                    passes, which is the silent-bypass shape D-10 exists to
+ *                    remove.
  */
-function assertVaultWriteTarget(cwd, targetRepo) {
-    const bindings = readBindings(cwd);
-    const client = isObject(bindings.client) ? bindings.client : null;
-    const clientRepo = client && typeof client.vaultRepo === 'string' ? client.vaultRepo : null;
-    const fbRepoRaw = cfgGet(cwd, 'vault.fallback_repo', DEFAULT_FALLBACK_REPO);
-    const fbRepo = typeof fbRepoRaw === 'string' ? fbRepoRaw : DEFAULT_FALLBACK_REPO;
+function assertVaultWriteTarget(cwd, targetRepo, targetHost) {
+    const provider = (0, git_provider_cjs_1.resolveProvider)(cwd).provider;
+    const clientCoord = (0, vault_coordinates_cjs_1.resolveClientCoordinates)(cwd, provider);
+    const sharedCoord = (0, vault_coordinates_cjs_1.resolveSharedCoordinates)(cwd, provider);
+    const clientRepo = clientCoord.repo;
+    const clientHost = clientCoord.host;
+    const sharedRepo = sharedCoord.repo;
+    const sharedHost = sharedCoord.host;
     if (!clientRepo) {
-        throw new Error(`vault write refused: no client.vaultRepo configured — cannot resolve a write target (got "${targetRepo}").`);
+        throw new Error(`vault write refused: no client.vaultRepo configured — cannot resolve a write target (got "${targetRepo}" at "${targetHost}").`);
     }
-    if (targetRepo === fbRepo) {
-        throw new Error(`vault write refused: target "${targetRepo}" is the shared Pareto vault, which is strictly read-only.`);
+    if (sharedRepo !== null && targetRepo === sharedRepo && targetHost === sharedHost) {
+        if (sharedRepo === vault_coordinates_cjs_1.DEFAULT_SHARED_REPO) {
+            throw new Error(`vault write refused: target "${targetRepo}" at "${targetHost}" is the shared Pareto vault, which is strictly read-only.`);
+        }
+        throw new Error(`vault write refused: target "${targetRepo}" at "${targetHost}" is this project's configured shared vault, which is strictly read-only — the same protection the shared Pareto vault has.`);
     }
-    if (targetRepo !== clientRepo) {
-        throw new Error(`vault write refused: target "${targetRepo}" does not match the configured client vault "${clientRepo}".`);
+    if (targetRepo !== clientRepo || targetHost !== clientHost) {
+        let message = `vault write refused: target "${targetRepo}" at "${targetHost}" does not match the configured client vault "${clientRepo}" at "${clientHost}".`;
+        if (sharedRepo === null) {
+            message += ' No shared vault is configured, so the shared-vault check was not applied.';
+        }
+        throw new Error(message);
     }
 }
 module.exports = {
@@ -683,4 +797,9 @@ module.exports = {
     usableFiles,
     cfgGet,
     readBindings,
+    // Additive exports (Phase 24-01): both functions already existed above —
+    // this only widens the export list so src/vault-practices.cts can reuse
+    // them instead of re-implementing a second bounded-read/secret-filter.
+    readHeadBounded,
+    isSecretFile,
 };

package/pp-core/bin/pp-tools.cjs

@@ -193,6 +193,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const readline = require('readline');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 const io = require('./lib/io.cjs');
 const { error, ERROR_REASON, setJsonErrorMode, output } = io;
@@ -210,6 +211,9 @@ const roadmap = require('./lib/roadmap.cjs');
 const verify = require('./lib/verify.cjs');
 const config = require('./lib/config.cjs');
 const platformBindings = require('./lib/platform-bindings.cjs');
+const composeBindings = require('./lib/compose-bindings.cjs');
+const initContract = require('./lib/init-contract.cjs');
+const initInteractive = require('./lib/init-interactive.cjs');
 const template = require('./lib/template.cjs');
 const milestone = require('./lib/milestone.cjs');
 const commands = require('./lib/commands.cjs');
@@ -520,10 +524,10 @@ async function main() {
   // phase / roadmap / milestone / progress / etc.
   const TOP_LEVEL_USAGE = 'Usage: pp-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>] [--json-errors]\n' +
     'Commands: agent, agent-skills, audit-open, audit-uat, check, check-commit, commit, commit-to-subrepo, ' +
-    'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, ' +
+    'compose-bindings, config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, ' +
     'current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
     'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
-    'generate-client-context, generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
+    'generate-client-context, generate-dev-preferences, generate-slug, graphify, history-digest, init, init-contract, intel, ' +
     'capability, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, platform-bindings, profile-questionnaire, ' +
     'profile-sample, progress, prompt-budget, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, state, ' +
     'task, template, user-story, validate, validate-bindings, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
@@ -533,6 +537,10 @@ async function main() {
     '  --cwd <path>       Override working directory for project-root resolution\n' +
     '  --ws <name>        Override active workstream (or set GSD_WORKSTREAM)\n' +
     '  --json-errors      Emit structured JSON error objects on stderr (or set GSD_JSON_ERRORS=1)\n\n' +
+    'Note on `init`: `pp-tools init` (bare, or with only --offline/--reset) runs the interactive\n' +
+    '/pp-init identity+binding prompt against a real terminal. `pp-tools init <subcommand>` (e.g.\n' +
+    'execute-phase, plan-phase, new-project) and `pp-tools query init.<subcommand>` are a separate,\n' +
+    'distinct family of workflow-orchestration verbs — they do not prompt.\n\n' +
     'For command-specific argument requirements, invoke the command without args ' +
     '(e.g. `pp-tools phase add`) — the resulting error lists what is required.';
 
@@ -612,6 +620,7 @@ async function main() {
 function captureStdoutSyncWrites(run) {
   const originalWriteSync = fs.writeSync;
   let captured = '';
+  let settled = false;
 
   fs.writeSync = function patchedWriteSync(fd, data, ...rest) {
     if (fd === 1) {
@@ -632,12 +641,37 @@ function captureStdoutSyncWrites(run) {
     fs.writeSync = originalWriteSync;
   };
 
+  // Safety net (#3097-adjacent, D-16 refusal contract): a router can call
+  // io.error() -> process.exit() synchronously from deep inside run() (e.g.
+  // an action command that emits a structured verdict to stdout and THEN
+  // refuses). process.exit() tears the process down before the .then()/
+  // .catch() below ever runs, so the fd-1 monkey-patch above would silently
+  // swallow every byte the command wrote to stdout before it errored —
+  // never flushed to the REAL fd 1. process.exit() still synchronously
+  // fires 'exit' listeners before the process truly terminates, so
+  // restoring fs.writeSync and flushing the captured buffer here is safe.
+  // The `settled` guard prevents a double-write: the normal completion path
+  // below removes this listener before it can fire.
+  const flushOnExit = () => {
+    if (settled) return;
+    settled = true;
+    restore();
+    if (captured.length > 0) {
+      originalWriteSync.call(fs, 1, resolveAtFileOutput(captured));
+    }
+  };
+  process.on('exit', flushOnExit);
+
   return Promise.resolve()
     .then(() => run())
     .then(() => {
+      process.removeListener('exit', flushOnExit);
+      settled = true;
       restore();
       return captured;
     }, (err) => {
+      process.removeListener('exit', flushOnExit);
+      settled = true;
       restore();
       throw err;
     });
@@ -671,6 +705,43 @@ function extractField(obj, fieldPath) {
   return current;
 }
 
+/**
+ * The production `Prompter` (src/init-interactive.cts's injectable seam)
+ * for `pp-tools init` — a real terminal via `node:readline`. Deliberately
+ * the ONLY place in this codebase that constructs a readline interface for
+ * `runInitInteractive`; the module itself never imports `node:readline`
+ * (Phase 34-09's own design hazard) so the interactive flow stays testable
+ * with a scripted fake and no pty.
+ */
+function createReadlinePrompter() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return {
+    ask(question) {
+      let rendered = question.prompt;
+      if (question.options && question.options.length > 0) {
+        const optionsRendered = question.options
+          .map((opt) =>
+            opt === question.preselected ? `${opt} (${question.preselectedLabel || 'preselected'})` : opt,
+          )
+          .join(' / ');
+        rendered += `\n  Options: ${optionsRendered}`;
+      }
+      if (question.optionalAnswer) {
+        rendered += '\n  (press Enter to skip)';
+      }
+      return new Promise((resolve) => {
+        rl.question(`${rendered}\n> `, (answer) => resolve(answer));
+      });
+    },
+    print(text) {
+      process.stdout.write(`${text}\n`);
+    },
+    close() {
+      rl.close();
+    },
+  };
+}
+
 async function runCommand(command, args, cwd, raw, defaultValue, originalCommand, workstreamContext = null) {
   switch (command) {
     case 'agent': {
@@ -709,6 +780,108 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
+    case 'compose-bindings': {
+      // compose-bindings [--write] [--offline]
+      // A bare invocation is a dry run — it composes, validates, and reports
+      // provenance/drift without touching disk (D-10). Only --write applies.
+      const cbArgs = args.slice(1);
+      const unrecognizedCbFlag = cbArgs.find(
+        (a) => a.startsWith('--') && !composeBindings.COMPOSE_BINDINGS_FLAGS.includes(a),
+      );
+      if (unrecognizedCbFlag !== undefined) {
+        error(
+          `Unrecognized flag "${unrecognizedCbFlag}" for compose-bindings. Supported: --write, --offline.`,
+          ERROR_REASON.SDK_FAIL_FAST,
+        );
+        break;
+      }
+      const cbOptions = {};
+      for (let i = 0; i < cbArgs.length; i++) {
+        const a = cbArgs[i];
+        if (a === '--write') {
+          cbOptions.write = true;
+        } else if (a === '--offline') {
+          cbOptions.offline = true;
+        }
+      }
+      composeBindings.cmdComposeBindings(cwd, cbOptions, raw);
+      break;
+    }
+
+    case 'init-contract': {
+      // init-contract [--questions] [--verify] [--session-next]
+      //   [--session-answer <stepId>=<value>] [--session-reset] [--offline]
+      // --questions (also the no-flag default, D-05): read-only, always
+      // exits 0, prints the canonical /pp-init question set as data.
+      // --verify: runs the end-state invariant check (Phase 34-07 gap
+      // closure) and exits non-zero when any invariant is violated — a
+      // data verdict, never a usage error; the JSON body still reaches
+      // stdout either way so init.md can show every violation verbatim.
+      // --session-next / --session-answer / --session-reset (Phase 34-08
+      // gap closure): the session relay an agent drives one step at a time
+      // — see src/init-contract.cts's session-machine header for why this
+      // exists. --session-answer takes its "<stepId>=<value>" payload as
+      // the NEXT argv token (same convention as --cwd/--pick), extracted
+      // BEFORE the unrecognized-flag scan below since the payload itself
+      // is not a flag. --offline forwards to every composeBindings call
+      // the session makes (parity with compose-bindings --offline).
+      const icArgs = args.slice(1);
+      let sessionAnswerRaw;
+      const saIdx = icArgs.indexOf('--session-answer');
+      if (saIdx !== -1) {
+        sessionAnswerRaw = icArgs[saIdx + 1];
+        if (!sessionAnswerRaw || sessionAnswerRaw.startsWith('--')) {
+          error(
+            'Missing value for --session-answer. Usage: --session-answer <stepId>=<value>',
+            ERROR_REASON.SDK_MISSING_ARG,
+          );
+          break;
+        }
+        icArgs.splice(saIdx, 2);
+      }
+      const unrecognizedIcFlag = icArgs.find(
+        (a) => a.startsWith('--') && !initContract.INIT_CONTRACT_FLAGS.includes(a),
+      );
+      if (unrecognizedIcFlag !== undefined) {
+        error(
+          `Unrecognized flag "${unrecognizedIcFlag}" for init-contract. Supported: --questions, --verify, --session-next, --session-answer, --session-reset, --offline.`,
+          ERROR_REASON.SDK_FAIL_FAST,
+        );
+        break;
+      }
+      const icOptions = {};
+      for (let i = 0; i < icArgs.length; i++) {
+        const a = icArgs[i];
+        if (a === '--questions') {
+          icOptions.questions = true;
+        } else if (a === '--verify') {
+          icOptions.verify = true;
+        } else if (a === '--session-next') {
+          icOptions.sessionNext = true;
+        } else if (a === '--session-reset') {
+          icOptions.sessionReset = true;
+        } else if (a === '--offline') {
+          icOptions.offline = true;
+        }
+      }
+      if (sessionAnswerRaw !== undefined) {
+        const eqIdx = sessionAnswerRaw.indexOf('=');
+        if (eqIdx === -1) {
+          error(
+            `Invalid --session-answer value "${sessionAnswerRaw}" — expected <stepId>=<value>.`,
+            ERROR_REASON.USAGE,
+          );
+          break;
+        }
+        icOptions.sessionAnswer = {
+          stepId: sessionAnswerRaw.slice(0, eqIdx),
+          value: sessionAnswerRaw.slice(eqIdx + 1),
+        };
+      }
+      initContract.cmdInitContract(cwd, icOptions, raw);
+      break;
+    }
+
     case 'banner': {
       // Pareto brand banner (Phase 17 / UIBR-02). Workflows shell out via
       // `pp_run banner <phaseKey> "<STAGE TEXT>"`. The banner reaches the
@@ -1297,6 +1470,56 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
     }
 
     case 'init': {
+      // `pp-tools init [--offline] [--reset]` (Phase 34-09 gap closure) —
+      // the user-facing interactive entry point that drives the 34-08
+      // session machine (src/init-interactive.cts) against a real
+      // terminal. Deliberately DISTINCT from `pp-tools query init.*`
+      // (init-command-router.cjs's execute-phase/plan-phase/new-project/...
+      // workflow-orchestration verbs, unchanged below) — args[1] decides
+      // which: a bare invocation or a flag starting with "--" is always
+      // this interactive command; anything else (a bare subcommand word
+      // like "execute-phase") routes to the existing family untouched.
+      const initSub = args[1];
+      const isInteractiveInvocation = initSub === undefined || initSub.startsWith('--');
+      if (isInteractiveInvocation) {
+        const INIT_INTERACTIVE_FLAGS = ['--offline', '--reset'];
+        const unrecognizedInitFlag = args.slice(1).find((a) => !INIT_INTERACTIVE_FLAGS.includes(a));
+        if (unrecognizedInitFlag !== undefined) {
+          error(
+            `Unrecognized flag "${unrecognizedInitFlag}" for init. Supported: --offline, --reset. ` +
+              'For init workflow subcommands (execute-phase, plan-phase, new-project, ...), use "pp-tools query init.<subcommand>".',
+            ERROR_REASON.SDK_FAIL_FAST,
+          );
+          break;
+        }
+        // Refuse to prompt when stdin is not a TTY — never block on stdin
+        // in CI; a hang here would be worse than a failure (T-34-71).
+        if (!process.stdin.isTTY) {
+          error(
+            '"pp-tools init" requires an interactive terminal (stdin is not a TTY) and will not prompt. ' +
+              'For a non-interactive/CI-driven session, use "pp-tools query init-contract --session-next" / ' +
+              '"--session-answer <stepId>=<value>" directly instead.',
+            ERROR_REASON.INIT_NON_INTERACTIVE,
+          );
+          break;
+        }
+        if (args.includes('--reset')) {
+          initContract.initSessionReset(cwd);
+        }
+        const prompter = createReadlinePrompter();
+        try {
+          const result = await initInteractive.runInitInteractive(cwd, prompter, {
+            offline: args.includes('--offline'),
+          });
+          output(result, raw);
+          if (!result.ok) {
+            process.exitCode = 1;
+          }
+        } finally {
+          prompter.close();
+        }
+        break;
+      }
       routeInitCommand({
         init,
         args,