@principles/workbuddy-adapter 0.2.13 → 0.2.15

package/dist/codec/input-decoder.d.ts

@@ -13,18 +13,21 @@ export declare class WorkBuddyDecoderError extends Error {
  * SPEC §4.2 failure normalization: WorkBuddy marks tool failure through
  * explicit shapes — `{is_error:true,...}` (Read failures), Bash
  * `{exitCode>0, error}` — while SUCCESS may be a bare STRING (rendered Read
- * output). A string carries no failure marker and is passed through
- * faithfully (the frozen fixtures show string === Read success; asserting
- * success-or-failure from string-ness alone would be fabrication).
+ * output).
  *
- * The shared production pain path (production-pain-evidence normalizeOutcome)
- * detects failure from an `error` field or a non-zero `exitCode` on the
- * envelope/result. `{is_error:true}` WITHOUT either (the read-iserror fixture
- * shape) would silently classify as success there — so this decoder wraps
- * every DETECTED failure in an explicit envelope
- * `{result: <original>, error: <explicit>}`, preserving the raw response
- * inside `result` while guaranteeing the failure is never missed. Missing
- * exitCode on a detected failure NEVER defaults to success.
+ * SPEC-RULECODE-HOST-PROMOTION-001 R2: on the PostToolUse channel the FROZEN
+ * host contract (Phase 0 baseline; see the channel table at the top of this
+ * file) is itself completion evidence — PostToolUseFailure is a SEPARATE
+ * registration and "PostToolUse never fires for that failure class". A
+ * response with NO failure marker on THIS channel is therefore a completed
+ * success, not an unconfirmed shape: the durable tool_calls row must record
+ * `success` so the WorkBuddy rule-context provider can assemble a real
+ * history window (an `unknown` row is rejected by the shared history
+ * validator, which would leave the provider permanently unavailable on this
+ * host). String-ness ALONE still proves nothing on any other channel — the
+ * classification rides on the channel contract, and every DETECTED failure
+ * is still wrapped `{result, error}` so the shared classifier can never
+ * miss it. Missing exitCode on a detected failure NEVER defaults to success.
  */
 export declare function normalizeWorkbuddyToolResponse(toolResponse: unknown, eventForDiagnostics: string): unknown;
 export declare function decodeWorkbuddyInput(raw: unknown): HostEvent;

package/dist/codec/input-decoder.js

@@ -127,22 +127,33 @@ function field(value, key) {
  * SPEC §4.2 failure normalization: WorkBuddy marks tool failure through
  * explicit shapes — `{is_error:true,...}` (Read failures), Bash
  * `{exitCode>0, error}` — while SUCCESS may be a bare STRING (rendered Read
- * output). A string carries no failure marker and is passed through
- * faithfully (the frozen fixtures show string === Read success; asserting
- * success-or-failure from string-ness alone would be fabrication).
+ * output).
  *
- * The shared production pain path (production-pain-evidence normalizeOutcome)
- * detects failure from an `error` field or a non-zero `exitCode` on the
- * envelope/result. `{is_error:true}` WITHOUT either (the read-iserror fixture
- * shape) would silently classify as success there — so this decoder wraps
- * every DETECTED failure in an explicit envelope
- * `{result: <original>, error: <explicit>}`, preserving the raw response
- * inside `result` while guaranteeing the failure is never missed. Missing
- * exitCode on a detected failure NEVER defaults to success.
+ * SPEC-RULECODE-HOST-PROMOTION-001 R2: on the PostToolUse channel the FROZEN
+ * host contract (Phase 0 baseline; see the channel table at the top of this
+ * file) is itself completion evidence — PostToolUseFailure is a SEPARATE
+ * registration and "PostToolUse never fires for that failure class". A
+ * response with NO failure marker on THIS channel is therefore a completed
+ * success, not an unconfirmed shape: the durable tool_calls row must record
+ * `success` so the WorkBuddy rule-context provider can assemble a real
+ * history window (an `unknown` row is rejected by the shared history
+ * validator, which would leave the provider permanently unavailable on this
+ * host). String-ness ALONE still proves nothing on any other channel — the
+ * classification rides on the channel contract, and every DETECTED failure
+ * is still wrapped `{result, error}` so the shared classifier can never
+ * miss it. Missing exitCode on a detected failure NEVER defaults to success.
  */
 export function normalizeWorkbuddyToolResponse(toolResponse, eventForDiagnostics) {
-    if (typeof toolResponse === 'string')
-        return toolResponse;
+    if (typeof toolResponse === 'string') {
+        // Wrap under a NON-`result` key: the shared classifier treats a record
+        // envelope as a structured completion, but a string inside `result` would
+        // still hit its text-only → unknown branch. `toolResponse` preserves the
+        // rendered text verbatim while the envelope carries the channel-contract
+        // completion.
+        return eventForDiagnostics === 'PostToolUse'
+            ? { toolResponse }
+            : toolResponse;
+    }
     if (!isRecord(toolResponse)) {
         throw new WorkBuddyDecoderError(`malformed required field "tool_response"`, `${eventForDiagnostics} tool_response must be the rendered string or the engine result object from ${HOST_CONTRACT_BASELINE}.`);
     }
@@ -152,8 +163,11 @@ export function normalizeWorkbuddyToolResponse(toolResponse, eventForDiagnostics
     const errorValue = field(toolResponse, 'error');
     const errorText = typeof errorValue === 'string' && errorValue.trim().length > 0 ? errorValue : undefined;
     const failed = isError || (exitCode !== undefined && exitCode > 0) || errorText !== undefined;
-    if (!failed)
+    if (!failed) {
+        // An object envelope is already a structured completion for the shared
+        // classifier (normalizeOutcome: record ⇒ success) — pass through.
         return toolResponse;
+    }
     const toolErrorCode = field(toolResponse, 'tool_error_code');
     let explicitError;
     if (errorText !== undefined) {

package/dist/pd-hook.js

@@ -37,7 +37,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { appendEventLogLine, redactTelemetryString, isRuleHostEvaluatedEventData } from '@principles/core/runtime-v2';
-import { createProductionHostRuntime, loadPdConfigForPlugin, parseOwnerStatementPrefix, assessWorkbuddyLiveKeyword, resolveSharedCorrectionKeywordStoreForDetection, admitTrustedWorkbuddyLiveCorrection, ensureGovernanceDiagnosticianTask } from '@principles/host-runtime';
+import { createProductionHostRuntime, createWorkbuddyRuleContextProvider, loadPdConfigForPlugin, parseOwnerStatementPrefix, assessWorkbuddyLiveKeyword, resolveSharedCorrectionKeywordStoreForDetection, admitTrustedWorkbuddyLiveCorrection, ensureGovernanceDiagnosticianTask } from '@principles/host-runtime';
 import { computeFeatureFlagsFromConfig } from '@principles/core/runtime-v2';
 import { WorkBuddyHooksHostAdapter } from './host-adapter.js';
 import { WORKBUDDY_TOOL_SEMANTICS } from './tool-semantics.js';
@@ -157,16 +157,16 @@ function recordRuleHostEvaluations(stateDir, sessionId, evaluations) {
     return diagnostics;
 }
 /**
- * PRI-780 pattern (WorkBuddy boundary, same as Codex): this host supplies no
- * runtime context provider, and the "unavailable → allow" contract is prompt
- * discipline, NOT a runtime-enforced invariant. Handing v2 rules a truthy
- * context would let a persisted rule evaluate context-blind and deny calls
- * that were previously suspended — a silent governance change. The gate skips
- * v2 rules with its structured `rule_context_v2_unavailable` warning and this
- * hook annotates the warning with the explicit host-unsupported reason before
- * it reaches stderr (明确 unsupported, never a silent skip).
+ * SPEC-RULECODE-HOST-PROMOTION-001 C: WorkBuddy now supplies a REAL V2 rule
+ * context provider over its own trajectory (see the dispatch wiring below),
+ * so the old blanket "host provides no runtime context provider" note no
+ * longer applies. The remaining honest boundary: rules whose required facts
+ * include design_approval stay suspended on this host (no WorkBuddy
+ * design-gate attestation entry exists), and unavailable history still
+ * suspends context-dependent rules through the shared-gate contract. The
+ * note below annotates exactly that residual state.
  */
-const WORKBUDDY_CONTEXT_UNSUPPORTED_NOTE = 'workbuddy_runtime_context_unsupported: the WorkBuddy host provides no runtime context provider; v2 rules stay suspended on this host';
+const WORKBUDDY_CONTEXT_UNSUPPORTED_NOTE = 'workbuddy_runtime_context_limited: WorkBuddy resolves rule context from its own trajectory only; rules requiring design_approval facts or unavailable history stay suspended on this host';
 export function annotateContextWarnings(warnings) {
     return warnings.map((warning) => warning.startsWith('rule_context_v2_unavailable')
         ? `${warning}; ${WORKBUDDY_CONTEXT_UNSUPPORTED_NOTE}`
@@ -226,6 +226,10 @@ export async function processWorkbuddyHookInvocation(rawStdin, channelEventName,
         }
         return failure;
     }
+    // Capture the decode boundary before governance or runtime work can consume
+    // time; the rule-context history window must never include rows written
+    // afterwards (same cutoff discipline as the Codex hook epoch).
+    const hookEpoch = new Date();
     // OD-07/P06 governance workspace: explicit, user-level, shared across
     // projects; never auto-created here and never falling back to another host.
     const resolution = resolveWorkbuddyWorkspace(os.homedir());
@@ -352,6 +356,23 @@ export async function processWorkbuddyHookInvocation(rawStdin, channelEventName,
             hostKind: 'workbuddy',
             toolSemantics: WORKBUDDY_TOOL_SEMANTICS,
             events: workbuddyEventEmitter(stateDir, evidenceContext),
+            // SPEC-RULECODE-HOST-PROMOTION-001 C: the V2 rule context provider over
+            // WorkBuddy's own observable trajectory (same-session tool_calls rows
+            // the shared afterToolCall path records). No designGate fact is
+            // supplied — WorkBuddy has no design-gate attestation entry point, so
+            // design_approval-dependent rules suspend with the precise
+            // `rule_required_fact_unavailable` warning rather than borrowing
+            // another host's declaration. Unavailable history (disabled flag, no
+            // project scope, first session turn) degrades through the shared
+            // suspension contract, observably.
+            ruleContextProvider: createWorkbuddyRuleContextProvider({
+                workspaceDir: resolution.workspaceDir,
+                ...(projectDir !== undefined ? { projectDir } : {}),
+                enabled: flags.rulecode_context_v2?.enabled === true,
+                cutoffAt: hookEpoch,
+                currentToolCallId: event.context.toolCallId ?? '',
+                toolSemantics: WORKBUDDY_TOOL_SEMANTICS,
+            }),
             // Remediation R2 (candidate-level admission): the diagnostician's
             // candidates are admitted ONLY with input evidence (needs_evidence
             // otherwise), and Codex-style transcript promotion does not exist on
@@ -378,8 +399,6 @@ export async function processWorkbuddyHookInvocation(rawStdin, channelEventName,
                         }],
                 };
             },
-            // PRI-780 boundary: NO context provider — v2 rules stay SUSPENDED on
-            // WorkBuddy (never loaded context-blind). See annotateContextWarnings.
         }).dispatch(event);
         const evaluationDiagnostics = recordRuleHostEvaluations(stateDir, event.context.sessionId, result.metadata?.evaluations);
         // Encode BEFORE recording an attributed deny: a runtime_verified

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/workbuddy-adapter",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "WorkBuddy host adapter for Principles Disciple — implements the HostAdapter interface for WorkBuddy's Git Bash command-hook model (ADR-0020 third host, SPEC workbuddy-host-adapter v0.3.0).",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,8 +42,8 @@
     "lint": "eslint \"src/**/*.ts\""
   },
   "dependencies": {
-    "@principles/core": "^1.297.3",
-    "@principles/host-runtime": "^0.14.0",
+    "@principles/core": "^1.297.5",
+    "@principles/host-runtime": "^0.14.2",
     "@principles/install-layout": "^0.4.0"
   },
   "devDependencies": {

package/plugin/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Principles Disciple — Owner-governed behavior internalization for AI agents (WorkBuddy host adapter, ADR-0020 third host). Requires explicit setup and host.workbuddy feature enablement; inactive until then.",
   "defaultEnabled": false
 }

package/plugin/hooks/hooks.json

@@ -42,7 +42,7 @@
           {
             "type": "command",
             "command": "node \"${CODEBUDDY_PLUGIN_ROOT}/scripts/wrapper.cjs\" UserPromptSubmit",
-            "timeout": 30
+            "timeout": 15
           }
         ]
       }

package/plugin/scripts/wrapper.cjs

@@ -23,6 +23,25 @@
  * 1 with a bounded stderr diagnostic: probe P02 established exit 1 is
  * non-blocking on WorkBuddy, and the SPEC §4.4 startup-failure row forbids
  * claiming self-blocking the wrapper cannot guarantee.
+ *
+ * SELF-DEADLINE (SPEC §4.4 timeout row): the adapter entry's own fail-open
+ * exits can never run when the HOST kills this wrapper on the hooks.json
+ * timeout — the process dies mid-flight, and the host's timeout semantics for
+ * a killed hook are undefined. So the wrapper arms a deadline STRICTLY BELOW
+ * the host budget and kills the child itself, degrading non-blocking
+ * (exit 1 + bounded stderr) instead of leaving the worst failure mode — a
+ * lost UserPromptSubmit prompt — to the host. The budget pairs are locked
+ * below the hooks.json timeouts by tests/plugin-skeleton.test.ts:
+ *   UserPromptSubmit 12000ms < 15s (prompt loss is the costliest channel);
+ *   every other channel 25000ms < 30s.
+ * PD_WORKBUDDY_HOOK_SELF_TIMEOUT_MS overrides the table (integer ms > 0, all
+ * events) for tests and field diagnostics; invalid values fall back to the
+ * table, and a valid one is CLAMPED strictly below the host budget so the
+ * override can never re-create the bug this deadline exists to fix.
+ *
+ * A killed child gets no chance to clean up (SIGTERM is TerminateProcess on
+ * Windows), so the deadline path deliberately does NOT promise adapter-side
+ * flush of evidence / SQLite locks — see SPEC §4.4.
  */
 const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
@@ -30,13 +49,42 @@ const path = require('node:path');
 
 const eventName = process.argv[2];
 
-function fail(message) {
+// hooks.json host budgets in ms. Kept here ONLY so the override below can be
+// clamped and so the guard test can prove the two tables agree with
+// hooks.json; the host remains the authority for actually killing us.
+const HOST_TIMEOUT_MS = { UserPromptSubmit: 15000, default: 30000 };
+// Margin for this process's own startup plus the degradation write, so our
+// timer always fires before the host's.
+const SELF_DEADLINE_MARGIN_MS = 3000;
+// Must stay strictly below the matching hooks.json timeout (seconds) — the
+// guard test in tests/plugin-skeleton.test.ts locks every pair.
+const SELF_TIMEOUT_MS = { UserPromptSubmit: 12000, default: 25000 };
+
+function hostBudgetMs(event) {
+  return HOST_TIMEOUT_MS[event] ?? HOST_TIMEOUT_MS.default;
+}
+
+function resolveSelfDeadlineMs(event) {
+  const budget = SELF_TIMEOUT_MS[event] ?? SELF_TIMEOUT_MS.default;
+  const override = Number.parseInt(process.env.PD_WORKBUDDY_HOOK_SELF_TIMEOUT_MS ?? '', 10);
+  if (!Number.isInteger(override) || override <= 0) return budget;
+  // Clamp, never trust: a diagnostic setting of 60000 would otherwise leave
+  // the outcome to the host's undefined timeout semantics again.
+  return Math.max(1, Math.min(override, hostBudgetMs(event) - SELF_DEADLINE_MARGIN_MS));
+}
+
+function fail(message, nextAction = 'Reinstall PD (npx create-principles-disciple) or set PD_WORKBUDDY_ADAPTER_ENTRY to the built adapter entry.') {
   try {
-    process.stderr.write(`[PD] status=degraded reason=workbuddy_wrapper:${message} nextAction=Reinstall PD (npx create-principles-disciple) or set PD_WORKBUDDY_ADAPTER_ENTRY to the built adapter entry.\n`);
+    process.stderr.write(`[PD] status=degraded reason=workbuddy_wrapper:${message} nextAction=${nextAction}\n`);
   } catch (_) { /* no channel left */ }
   process.exit(1);
 }
 
+// The adapter child was killed at OUR deadline (before the host timeout):
+// the hook result is a non-blocking degradation, so the user's prompt/tool
+// call survives — the recovery action is diagnosis, not reinstall.
+const DEADLINE_NEXT_ACTION = 'The hook degraded at its self-deadline before the host timeout (non-blocking: the prompt/tool call survived). If this repeats, inspect PD stderr and the governance workspace, and time one manual pd-hook run.';
+
 function resolveEntry() {
   const override = process.env.PD_WORKBUDDY_ADAPTER_ENTRY;
   if (override && override.trim().length > 0) {
@@ -62,18 +110,34 @@ try {
 } catch (_) {
   fail('entry_not_found:' + entry.slice(0, 120));
 }
+const deadlineMs = resolveSelfDeadlineMs(eventName);
+const startedAt = Date.now();
 const child = spawnSync(process.execPath, [entry, eventName], {
   stdio: ['inherit', 'inherit', 'inherit'],
   windowsHide: true,
+  timeout: deadlineMs,
+  killSignal: 'SIGTERM',
 });
 
 if (child.error) {
+  // spawnSync surfaces its OWN timeout kill as error.code === 'ETIMEDOUT'
+  // (status null, no child exit code) — that is the self-deadline firing,
+  // not a spawn failure. Degrade non-blocking with the observable budget.
+  if (child.error.code === 'ETIMEDOUT') {
+    fail(`entry_deadline_exceeded:${Date.now() - startedAt}ms_budget_${deadlineMs}ms`, DEADLINE_NEXT_ACTION);
+  }
   const code = child.error.code === 'ENOENT' ? 'entry_not_found' : 'spawn_failed';
   fail(`${code}:${child.error.message.slice(0, 120)}`);
 }
 if (child.status === null) {
-  // Killed by signal (e.g. host timeout): mirror as a non-blocking exit 1
-  // with the observable reason; P02 timeout semantics are host-managed.
+  // Killed by signal. When our own deadline armed first, this is the
+  // self-timeout degradation (the host kills THIS wrapper, not the child);
+  // report it distinctly so field logs separate PD-side degradation from an
+  // externally killed adapter.
+  const elapsedMs = Date.now() - startedAt;
+  if (child.signal === 'SIGTERM' && elapsedMs >= deadlineMs - 500) {
+    fail(`entry_deadline_exceeded:${elapsedMs}ms_budget_${deadlineMs}ms`, DEADLINE_NEXT_ACTION);
+  }
   fail(`entry_killed_signal:${String(child.signal).slice(0, 30)}`);
 }
 process.exit(child.status);