@hadooppei/hwcode 0.2.1 → 0.2.4

package/.pi/extensions/cloud.ts

@@ -8,7 +8,11 @@ import { CURSOR_MARKER, Input, type Component, type TUI } from "@earendil-works/
 
 import { checkProviderCli, formatValidationFailure, prepareCloudExecution, validateCloudCredentials, type TemporaryCredentialStore } from "../lib/cloud/adapters.ts";
 import { runProcess, truncateOutput, type ProcessResult } from "../lib/cloud/process.ts";
-import { expandCloudPromptTemplate, listCloudPromptTemplates, saveCloudPromptTemplate, type CloudPromptTemplate } from "../lib/cloud/templates.ts";
+import {
+	cloudPromptTemplateSource, expandCloudPromptTemplate, listCloudPromptTemplates, saveCloudPromptTemplate, updateCloudPromptTemplate,
+	type CloudPromptTemplate,
+} from "../lib/cloud/templates.ts";
+import { saveCloudWorkflowTemplate } from "../lib/cloud/template-save.ts";
 import {
 	CLOUD_EXECUTABLES, CLOUD_PROVIDERS, classifyCloudOperation, containsCloudCommand,
 	getCloudProvider, inaccessibleCloudCliMessage, missingCloudCliMessage, redactCredentialValues,
@@ -22,7 +26,7 @@ import {
 import { canonicalizeWorkspaceRoot } from "../lib/workflow-guard.ts";
 import { modelConfigurationIssue } from "../lib/models/readiness.ts";
 import {
-	WORKFLOW_EXTERNAL_AUDIT_TYPE, WORKFLOW_STATE_TYPE, activeWorkflow, updateWorkflowState,
+	WORKFLOW_EXTERNAL_AUDIT_TYPE, WORKFLOW_STATE_TYPE, activeWorkflow, createCloudWorkflowState, updateWorkflowState,
 	type CloudWorkflowDetails, type WorkflowState,
 } from "../lib/workflows/state.ts";
 import { evaluateCommandArgumentsAccess } from "../lib/workspace/access-policy.ts";
@@ -82,6 +86,13 @@ function cloudDetails(state: WorkflowState): CloudWorkflowDetails | undefined {
 	return state.mode === "cloud" ? state.details : undefined;
 }
 
+function formatTemplateTime(value: string): string {
+	const date = new Date(value);
+	if (Number.isNaN(date.valueOf())) return value;
+	const pad = (part: number) => String(part).padStart(2, "0");
+	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
 function restoreCloudWorkflow(ctx: ExtensionContext): WorkflowState | undefined {
 	const state = activeWorkflow(ctx.sessionManager.getEntries());
 	return state?.mode === "cloud" && state.details ? state : undefined;
@@ -121,18 +132,6 @@ function appendWorkflowState(pi: ExtensionAPI, state: WorkflowState): void {
 	pi.appendEntry<WorkflowState>(WORKFLOW_STATE_TYPE, state);
 }
 
-function createCloudWorkflowState(root: string, vendor: CloudVendorId, deploy: boolean, request: string): WorkflowState {
-	const now = new Date().toISOString();
-	return {
-		version: 2, status: "active", mode: "cloud", root, phase: "connected",
-		activatedAt: now, updatedAt: now,
-		details: {
-			vendor, deployCurrentProject: deploy, request, allowNonDeleteChanges: false,
-			failedApproaches: [], successfulSteps: [], terminalFailure: false,
-		},
-	};
-}
-
 async function secretInput(ctx: ExtensionContext, title: string): Promise<string | undefined> {
 	if (ctx.mode !== "tui") return undefined;
 	return ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => new MaskedInput(tui, theme, title, done));
@@ -190,7 +189,10 @@ async function collectCredentials(vendor: CloudVendorId, root: string, ctx: Exte
 
 function activationPrompt(state: WorkflowState): string {
 	const details = cloudDetails(state)!;
-	return `/skill:hwcode-cloud HWCode Cloud workflow activated.\n\nLocked project root: ${state.root}\nCloud provider: ${getCloudProvider(details.vendor).label}\nDeploy current project: ${details.deployCurrentProject ? "yes" : "no"}\nUser objective and reusable guidance:\n${details.request}\n\nCredentials were validated and remain outside model context. Use hwcode_cloud_exec for every cloud or infrastructure command.`;
+	const guidance = details.templateGuidance
+		? `\n\nReusable template guidance (${details.sourceTemplate?.name ?? "saved template"}):\n${details.templateGuidance}`
+		: "";
+	return `/skill:hwcode-cloud HWCode Cloud workflow activated.\n\nLocked project root: ${state.root}\nCloud provider: ${getCloudProvider(details.vendor).label}\nDeploy current project: ${details.deployCurrentProject ? "yes" : "no"}\nUser objective:\n${details.request}${guidance}\n\nCredentials were validated and remain outside model context. Use hwcode_cloud_exec for every cloud or infrastructure command.`;
 }
 
 async function approveOperation(operation: CloudOperation, params: { command: string; args: string[]; intent: string }, state: WorkflowState, ctx: ExtensionContext): Promise<"allow" | "allow-session" | "deny"> {
@@ -263,11 +265,13 @@ export default function cloudExtension(pi: ExtensionAPI) {
 			notify(ctx, "还没有本地 Cloud Prompt Template。成功执行任务后使用 /hwcode-cloud-save-template 保存。", "warning");
 			return undefined;
 		}
+		const labels = templates.map((template) => `${template.name} · ${formatTemplateTime(template.updatedAt)}`);
 		const selected = await ctx.ui.select(
 			"选择已验证的 Cloud Prompt Template",
-			templates.map((template) => `${template.id} — ${template.description}`),
+			labels,
 		);
-		return templates.find((template) => selected?.startsWith(`${template.id} —`));
+		const selectedIndex = selected ? labels.indexOf(selected) : -1;
+		return selectedIndex >= 0 ? templates[selectedIndex] : undefined;
 	}
 
 	async function activate(args: string, ctx: ExtensionCommandContext, initialTemplate?: CloudPromptTemplate): Promise<void> {
@@ -307,6 +311,7 @@ export default function cloudExtension(pi: ExtensionAPI) {
 		let vendor: CloudVendorId;
 		let deployCurrentProject: boolean;
 		let request: string;
+		let templateGuidance: string | undefined;
 		if (resumedState) {
 			const details = cloudDetails(resumedState)!;
 			vendor = details.vendor;
@@ -315,7 +320,8 @@ export default function cloudExtension(pi: ExtensionAPI) {
 		} else if (template) {
 			vendor = template.vendor;
 			deployCurrentProject = template.deployCurrentProject;
-			request = expandCloudPromptTemplate(template, args);
+			request = template.objective || template.name;
+			templateGuidance = expandCloudPromptTemplate(template, args);
 		} else {
 			const label = await ctx.ui.select("选择需要对接的云计算厂商", CLOUD_PROVIDERS.map((provider) => provider.label));
 			if (!label) return;
@@ -378,7 +384,16 @@ export default function cloudExtension(pi: ExtensionAPI) {
 		);
 		cleanupCredentialDirectories();
 		activeCredentials = credentials;
-		activeState = resumedState ?? createCloudWorkflowState(root, vendor, deployCurrentProject, request);
+		activeState = resumedState ?? createCloudWorkflowState(
+			root,
+			vendor,
+			deployCurrentProject,
+			request,
+			template && templateGuidance ? {
+				source: cloudPromptTemplateSource(template),
+				guidance: templateGuidance,
+			} : undefined,
+		);
 		appendWorkflowState(pi, activeState);
 		notify(ctx, `${vendorLabel} 连接成功。凭据已加密保存，项目根目录锁定为 ${root}。`);
 		pi.sendUserMessage(activationPrompt(activeState), { expandPromptTemplates: true });
@@ -404,15 +419,42 @@ export default function cloudExtension(pi: ExtensionAPI) {
 				notify(ctx, "当前 Cloud workflow 还没有成功执行步骤，无法生成可复用模板。", "warning");
 				return;
 			}
-			const name = args.trim() || (await ctx.ui.input("模板名称", details.request.slice(0, 48)))?.trim();
-			if (!name) return;
-			const notes = (await ctx.ui.editor("补充成功经验、必要前置条件或易错点（可留空；不得包含凭据）", ""))?.trim();
-			const safeNotes = activeCredentials && notes ? redactCredentialValues(notes, activeCredentials) : notes;
-			const safeState = activeCredentials
-				? { ...activeState, details: { ...details, request: redactCredentialValues(details.request, activeCredentials) } }
-				: activeState;
-			const template = saveCloudPromptTemplate(name, safeState, undefined, safeNotes);
-			notify(ctx, `已保存模板 ${template.id} 到 ${template.path}。使用 /hwcode-cloud-template 可立即复用。`);
+
+			const result = await saveCloudWorkflowTemplate({
+				state: activeState,
+				requestedName: args,
+				redact: activeCredentials
+					? (value) => redactCredentialValues(value, activeCredentials!)
+					: undefined,
+				interaction: {
+					async chooseSourceAction(source) {
+						const updateLabel = `更新原模板「${source.name}」`;
+						const choice = await ctx.ui.select(
+							`当前会话关联模板「${details.sourceTemplate?.name ?? source.name}」`,
+							[updateLabel, "创建新模板", "取消"],
+						);
+						if (!choice || choice === "取消") return "cancel";
+						return choice === updateLabel ? "update" : "create";
+					},
+					inputName: (defaultName) => ctx.ui.input("模板名称", defaultName),
+					editNotes: (initialNotes) => ctx.ui.editor(
+						"补充必要前置条件、成功经验及必须避免的高消耗错误路径（可留空；不得包含凭据）",
+						initialNotes,
+					),
+					sourceMissing(sourceName) {
+						notify(ctx, `本次使用的原模板「${sourceName}」已不存在，将创建新模板。`, "warning");
+					},
+				},
+				store: {
+					list: () => listCloudPromptTemplates(),
+					create: (name, state, notes) => saveCloudPromptTemplate(name, state, undefined, notes),
+					update: (template, state, notes) => updateCloudPromptTemplate(template, state, notes),
+				},
+			});
+			if (result.status === "cancelled") return;
+			activeState = replaceDetails(activeState, result.details);
+			const action = result.action === "updated" ? "已更新" : "已创建";
+			notify(ctx, `${action}模板「${result.template.name}」（${formatTemplateTime(result.template.updatedAt)}）。使用 /hwcode-cloud-template 可立即复用。`);
 		},
 	});
 

package/.pi/lib/cloud/template-save.ts

@@ -0,0 +1,107 @@
+import type { CloudPromptTemplate } from "./templates.ts";
+import { cloudPromptTemplateSource } from "./templates.ts";
+import type { CloudWorkflowDetails, WorkflowState } from "../workflows/state.ts";
+
+export type CloudTemplateSourceAction = "update" | "create" | "cancel";
+export type CloudTemplateSaveStage = "source-action" | "name" | "notes";
+
+export interface CloudTemplateSaveInteraction {
+  chooseSourceAction(source: CloudPromptTemplate): Promise<CloudTemplateSourceAction | undefined>;
+  inputName(defaultName: string): Promise<string | undefined>;
+  editNotes(initialNotes: string): Promise<string | undefined>;
+  sourceMissing(sourceName: string): void | Promise<void>;
+}
+
+export interface CloudTemplateStore {
+  list(): CloudPromptTemplate[];
+  create(name: string, state: WorkflowState, notes: string): CloudPromptTemplate;
+  update(template: CloudPromptTemplate, state: WorkflowState, notes: string): CloudPromptTemplate;
+}
+
+export type CloudTemplateSaveResult =
+  | { status: "cancelled"; stage: CloudTemplateSaveStage }
+  | {
+    status: "saved";
+    action: "created" | "updated";
+    template: CloudPromptTemplate;
+    details: CloudWorkflowDetails;
+  };
+
+export interface SaveCloudWorkflowTemplateOptions {
+  state: WorkflowState;
+  requestedName?: string;
+  interaction: CloudTemplateSaveInteraction;
+  store: CloudTemplateStore;
+  redact?: (value: string) => string;
+}
+
+/**
+ * Coordinates the save/update decision without depending on Pi UI or filesystem APIs.
+ * Storage is invoked only after every interactive step succeeds, so cancellation and
+ * storage failures cannot partially change the workflow state.
+ */
+export async function saveCloudWorkflowTemplate(
+  options: SaveCloudWorkflowTemplateOptions,
+): Promise<CloudTemplateSaveResult> {
+  const { state, interaction, store } = options;
+  if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
+  if (state.details.successfulSteps.length === 0) {
+    throw new Error("No successful Cloud execution steps are available to summarize");
+  }
+
+  const details = state.details;
+  let target: CloudPromptTemplate | undefined;
+  if (details.sourceTemplate) {
+    target = store.list().find((template) => template.id === details.sourceTemplate?.id);
+    if (target) {
+      const sourceAction = await interaction.chooseSourceAction(target);
+      if (!sourceAction || sourceAction === "cancel") {
+        return { status: "cancelled", stage: "source-action" };
+      }
+      if (sourceAction === "create") target = undefined;
+    } else {
+      await interaction.sourceMissing(details.sourceTemplate.name);
+    }
+  }
+
+  let name = target?.name;
+  if (!name) {
+    const suppliedName = options.requestedName?.trim();
+    if (suppliedName) {
+      name = suppliedName;
+    } else {
+      const defaultName = details.sourceTemplate
+        ? `${details.sourceTemplate.name} 副本`
+        : details.request.slice(0, 48);
+      name = (await interaction.inputName(defaultName))?.trim();
+    }
+    if (!name) return { status: "cancelled", stage: "name" };
+  }
+
+  const notes = await interaction.editNotes(target?.notes ?? "");
+  if (notes === undefined) return { status: "cancelled", stage: "notes" };
+
+  const redact = options.redact ?? ((value: string) => value);
+  const safeName = redact(name);
+  const safeNotes = redact(notes.trim());
+  const safeState: WorkflowState = {
+    ...state,
+    details: {
+      ...details,
+      request: redact(details.request),
+      templateGuidance: details.templateGuidance === undefined
+        ? undefined
+        : redact(details.templateGuidance),
+    },
+  };
+  const template = target
+    ? store.update(target, safeState, safeNotes)
+    : store.create(safeName, safeState, safeNotes);
+
+  return {
+    status: "saved",
+    action: target ? "updated" : "created",
+    template,
+    details: { ...details, sourceTemplate: cloudPromptTemplateSource(template) },
+  };
+}

package/.pi/lib/cloud/templates.ts

@@ -1,20 +1,33 @@
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 
 import { getCloudProvider, isCloudVendorId, type CloudVendorId } from "../cloud-providers.ts";
-import type { WorkflowState } from "../workflows/state.ts";
+import type { CloudTemplateSource, WorkflowState } from "../workflows/state.ts";
 
 export interface CloudPromptTemplate {
   id: string;
+  name: string;
   description: string;
+  createdAt: string;
+  updatedAt: string;
   vendor: CloudVendorId;
   deployCurrentProject: boolean;
   objective: string;
+  notes: string;
   body: string;
   path: string;
 }
 
+export function cloudPromptTemplateSource(template: CloudPromptTemplate): CloudTemplateSource {
+  return {
+    id: template.id,
+    name: template.name,
+    createdAt: template.createdAt,
+    updatedAt: template.updatedAt,
+  };
+}
+
 export function defaultCloudPromptDirectory(home = homedir()): string {
   return join(home, ".hwcode", "cloud", "prompts");
 }
@@ -40,6 +53,22 @@ function frontmatterValue(text: string, key: string): string | undefined {
   }
 }
 
+function normalizeTimestamp(value: string | undefined, fallback: string): string {
+  if (!value) return fallback;
+  const date = new Date(value);
+  return Number.isNaN(date.valueOf()) ? fallback : date.toISOString();
+}
+
+function legacyTemplateName(id: string): string {
+  const words = id.replace(/^hwcloud-/u, "").split("-").filter(Boolean);
+  if (words.length === 0) return "Legacy Cloud Template";
+  return words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+
+function cleanTemplateName(value: string): string {
+  return value.replace(/[\r\n]+/gu, " ").replace(/\s+/gu, " ").trim().slice(0, 80);
+}
+
 export function parseCloudPromptTemplate(path: string): CloudPromptTemplate | undefined {
   const text = readFileSync(path, "utf8");
   const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/u);
@@ -48,12 +77,20 @@ export function parseCloudPromptTemplate(path: string): CloudPromptTemplate | un
   const vendorValue = frontmatterValue(metadata, "hwcode-cloud-vendor");
   if (!vendorValue || !isCloudVendorId(vendorValue)) return undefined;
   const id = basename(path, ".md");
+  const stats = statSync(path);
+  const modifiedAt = stats.mtime.toISOString();
+  const bornAt = stats.birthtimeMs > 0 ? stats.birthtime.toISOString() : modifiedAt;
+  const name = cleanTemplateName(frontmatterValue(metadata, "hwcode-cloud-name") ?? "") || legacyTemplateName(id);
   return {
     id,
-    description: frontmatterValue(metadata, "description") ?? id,
+    name,
+    description: frontmatterValue(metadata, "description") ?? name,
+    createdAt: normalizeTimestamp(frontmatterValue(metadata, "hwcode-cloud-created-at"), bornAt),
+    updatedAt: normalizeTimestamp(frontmatterValue(metadata, "hwcode-cloud-updated-at"), modifiedAt),
     vendor: vendorValue,
     deployCurrentProject: frontmatterValue(metadata, "hwcode-cloud-deploy") === "true",
     objective: frontmatterValue(metadata, "hwcode-cloud-objective") ?? "",
+    notes: frontmatterValue(metadata, "hwcode-cloud-notes") ?? "",
     body: match[2].trim(),
     path,
   };
@@ -67,7 +104,7 @@ export function listCloudPromptTemplates(
     .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
     .map((entry) => parseCloudPromptTemplate(join(directory, entry.name)))
     .filter((template): template is CloudPromptTemplate => Boolean(template))
-    .sort((left, right) => left.description.localeCompare(right.description));
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || left.name.localeCompare(right.name));
 }
 
 export function expandCloudPromptTemplate(template: CloudPromptTemplate, argumentsText: string): string {
@@ -79,6 +116,10 @@ function inlineCode(value: string): string {
   return value.replace(/[\r\n]+/gu, " ").replaceAll("`", "\\`");
 }
 
+function singleLine(value: string): string {
+  return value.replace(/[\r\n]+/gu, " ").replace(/\s+/gu, " ").trim();
+}
+
 export function renderCloudPromptTemplate(state: WorkflowState, notes = ""): string {
   if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
   const details = state.details;
@@ -87,62 +128,121 @@ export function renderCloudPromptTemplate(state: WorkflowState, notes = ""): str
   }
   const provider = getCloudProvider(details.vendor);
   const steps = details.successfulSteps.map((step, index) => (
-    `${index + 1}. [${step.operation}] ${step.intent}\n`
-      + `   - Approach: ${step.approach}\n`
-      + `   - Reference command: \`${inlineCode([step.command, ...step.args].join(" "))}\``
+    `${index + 1}. [${step.operation}] ${singleLine(step.intent)}\n`
+      + `   - Validated approach: ${singleLine(step.approach)}\n`
+      + `   - Known-good command and path: \`${inlineCode([step.command, ...step.args].join(" "))}\``
   )).join("\n");
+  const failedPaths = details.failedApproaches.length > 0
+    ? details.failedApproaches.map((failure, index) => (
+      `${index + 1}. **DO NOT RETRY:** ${singleLine(failure.approach)}\n`
+        + `   - Recorded failure: ${singleLine(failure.reason)}`
+    )).join("\n")
+    : "No failed execution paths were recorded for this run.";
   return [
-    "Execute a reusable HWCode Cloud task based on a previously successful run.",
+    "Execute this HWCode Cloud task from a layered record of a previously successful run.",
+    "",
+    "## Layer 1 — Stable intent and boundaries",
     "",
     `Preferred provider: ${provider.label}`,
     `Deploy current project: ${details.deployCurrentProject ? "yes" : "no"}`,
     `Objective pattern: ${details.request}`,
     "",
-    "Known successful execution sequence (reference only; re-check current account state before reuse):",
+    "Preserve the objective, provider boundary, credential isolation, resource approvals, and deletion confirmations. Adapt only environment-specific values.",
+    "",
+    "## Layer 2 — Preconditions and operator knowledge",
+    "",
+    "Start with read-only discovery. Re-check the active account, region, project, resource state, tool versions, and workspace paths before making changes.",
+    ...(notes ? ["", "Validated prerequisites, lessons, and expensive pitfalls:", notes] : []),
+    "",
+    "## Layer 3 — Preferred validated execution path",
+    "",
+    "Use this path first and preserve its order unless read-only evidence requires an adaptation. The commands and paths below are the known-good reference; do not replace them with speculative alternatives.",
+    "",
     steps,
     "",
-    ...(notes ? ["Validated-run notes and pitfalls:", notes, ""] : []),
-    "Start with read-only discovery and adapt account, region, project, resource names, versions, and paths to the current environment. Present the plan and obtain all normal HWCode Cloud approvals. Never copy credentials or assume resources from the previous run still exist.",
+    "## Layer 4 — Expensive failed paths to avoid",
+    "",
+    "Do not retry any path below, including renamed or parameter-only variants. Reconsider one only when the user explicitly directs it after reviewing the recorded failure.",
+    "",
+    failedPaths,
+    "",
+    "## Layer 5 — Execution contract",
+    "",
+    "Present the adapted plan and obtain all normal HWCode Cloud approvals. Never copy credentials, assume old resources still exist, or skip current-state verification.",
     "If HWCode Cloud is not active, do not run cloud commands directly; ask the user to start this template through /hwcode-cloud-template.",
     "",
     "Additional instructions: ${@:-Use the objective and successful sequence above.}",
   ].join("\n");
 }
 
-export function saveCloudPromptTemplate(
-  requestedName: string,
+function renderTemplateFile(
+  name: string,
   state: WorkflowState,
-  directory = defaultCloudPromptDirectory(),
-  notes = "",
-): CloudPromptTemplate {
+  notes: string,
+  createdAt: string,
+  updatedAt: string,
+): string {
   if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
-  const idBase = `hwcloud-${slugify(requestedName || state.details.request)}`;
   const body = renderCloudPromptTemplate(state, notes);
-  const description = `Reuse successful ${getCloudProvider(state.details.vendor).label} workflow: ${state.details.request.slice(0, 80)}`;
-  const content = [
+  return [
     "---",
-    `description: ${JSON.stringify(description)}`,
+    `description: ${JSON.stringify(name)}`,
     'argument-hint: "[additional instructions]"',
+    `hwcode-cloud-name: ${JSON.stringify(name)}`,
+    `hwcode-cloud-created-at: ${JSON.stringify(createdAt)}`,
+    `hwcode-cloud-updated-at: ${JSON.stringify(updatedAt)}`,
     `hwcode-cloud-vendor: ${JSON.stringify(state.details.vendor)}`,
     `hwcode-cloud-deploy: ${state.details.deployCurrentProject}`,
     `hwcode-cloud-objective: ${JSON.stringify(state.details.request)}`,
+    `hwcode-cloud-notes: ${JSON.stringify(notes)}`,
     "---",
     body,
     "",
   ].join("\n");
+}
 
+function writeTemplateFile(path: string, content: string): void {
+  const directory = dirname(path);
   mkdirSync(directory, { recursive: true, mode: 0o700 });
   chmodSync(directory, 0o700);
+  const temporaryPath = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
+  chmodSync(temporaryPath, 0o600);
+  renameSync(temporaryPath, path);
+  chmodSync(path, 0o600);
+}
+
+export function saveCloudPromptTemplate(
+  requestedName: string,
+  state: WorkflowState,
+  directory = defaultCloudPromptDirectory(),
+  notes = "",
+  savedAt = new Date(),
+): CloudPromptTemplate {
+  if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
+  const name = cleanTemplateName(requestedName);
+  if (!name) throw new Error("Cloud Prompt Template name is required");
+  const idBase = `hwcloud-${slugify(name)}`;
+  const timestamp = savedAt.toISOString();
+  const content = renderTemplateFile(name, state, notes, timestamp, timestamp);
   let id = idBase;
   let path = join(directory, `${id}.md`);
   for (let suffix = 2; existsSync(path); suffix++) {
     id = `${idBase}-${suffix}`;
     path = join(directory, `${id}.md`);
   }
-  const temporaryPath = `${path}.${process.pid}.tmp`;
-  writeFileSync(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
-  chmodSync(temporaryPath, 0o600);
-  renameSync(temporaryPath, path);
-  chmodSync(path, 0o600);
+  writeTemplateFile(path, content);
   return parseCloudPromptTemplate(path)!;
 }
+
+export function updateCloudPromptTemplate(
+  template: CloudPromptTemplate,
+  state: WorkflowState,
+  notes = template.notes,
+  updatedAt = new Date(),
+): CloudPromptTemplate {
+  const timestamp = updatedAt.toISOString();
+  const content = renderTemplateFile(template.name, state, notes, template.createdAt, timestamp);
+  writeTemplateFile(template.path, content);
+  return parseCloudPromptTemplate(template.path)!;
+}

package/.pi/lib/workflow-guard.ts

@@ -11,6 +11,8 @@ export interface ExternalPathReference {
 	resolved: string;
 }
 
+const APPROVAL_FREE_EXTERNAL_PATHS = new Set(["/dev/null"]);
+
 function realpathWithMissingTail(path: string): string {
 	const tail: string[] = [];
 	let cursor = resolve(path);
@@ -41,6 +43,11 @@ export function isPathInsideRoot(root: string, candidate: string): boolean {
 	return relation === "" || (!relation.startsWith(`..${sep}`) && relation !== ".." && !isAbsolute(relation));
 }
 
+export function isPathAllowedWithoutApproval(root: string, candidate: string): boolean {
+	const resolved = realpathWithMissingTail(candidate);
+	return APPROVAL_FREE_EXTERNAL_PATHS.has(resolved) || isPathInsideRoot(root, resolved);
+}
+
 function stripTrailingShellPunctuation(value: string): string {
 	return value.replace(/[\]}),;]+$/g, "");
 }
@@ -52,7 +59,7 @@ function addExternalReference(
 	resolved: string,
 ): void {
 	const cleanResolved = realpathWithMissingTail(stripTrailingShellPunctuation(resolved));
-	if (!isPathInsideRoot(root, cleanResolved)) {
+	if (!isPathAllowedWithoutApproval(root, cleanResolved)) {
 		result.set(`${raw}\0${cleanResolved}`, { raw, resolved: cleanResolved });
 	}
 }

package/.pi/lib/workflows/state.ts

@@ -21,6 +21,13 @@ export interface CloudExecutionStep {
   completedAt: string;
 }
 
+export interface CloudTemplateSource {
+  id: string;
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
 export interface CloudWorkflowDetails {
   vendor: "aws" | "azure" | "gcp" | "huawei" | "alibaba" | "tencent";
   deployCurrentProject: boolean;
@@ -29,6 +36,8 @@ export interface CloudWorkflowDetails {
   failedApproaches: FailedApproach[];
   successfulSteps: CloudExecutionStep[];
   terminalFailure: boolean;
+  templateGuidance?: string;
+  sourceTemplate?: CloudTemplateSource;
 }
 
 export interface WorkflowState {
@@ -52,6 +61,15 @@ interface LegacyWorkflowState {
   deactivatedAt?: string;
 }
 
+function isCloudTemplateSource(value: unknown): value is CloudTemplateSource {
+  if (!value || typeof value !== "object") return false;
+  const data = value as Record<string, unknown>;
+  return typeof data.id === "string"
+    && typeof data.name === "string"
+    && typeof data.createdAt === "string"
+    && typeof data.updatedAt === "string";
+}
+
 function isCloudDetails(value: unknown): value is CloudWorkflowDetails {
   if (!value || typeof value !== "object") return false;
   const data = value as Record<string, unknown>;
@@ -61,7 +79,9 @@ function isCloudDetails(value: unknown): value is CloudWorkflowDetails {
     && typeof data.allowNonDeleteChanges === "boolean"
     && Array.isArray(data.failedApproaches)
     && Array.isArray(data.successfulSteps)
-    && typeof data.terminalFailure === "boolean";
+    && typeof data.terminalFailure === "boolean"
+    && (data.templateGuidance === undefined || typeof data.templateGuidance === "string")
+    && (data.sourceTemplate === undefined || isCloudTemplateSource(data.sourceTemplate));
 }
 
 export function decodeWorkflowState(value: unknown): WorkflowState | undefined {
@@ -124,6 +144,38 @@ export function createWorkflowState(
   };
 }
 
+export function createCloudWorkflowState(
+  root: string,
+  vendor: CloudWorkflowDetails["vendor"],
+  deployCurrentProject: boolean,
+  request: string,
+  template?: { source: CloudTemplateSource; guidance: string },
+): WorkflowState {
+  const now = new Date().toISOString();
+  return {
+    version: 2,
+    status: "active",
+    mode: "cloud",
+    root,
+    phase: "connected",
+    activatedAt: now,
+    updatedAt: now,
+    details: {
+      vendor,
+      deployCurrentProject,
+      request,
+      allowNonDeleteChanges: false,
+      failedApproaches: [],
+      successfulSteps: [],
+      terminalFailure: false,
+      ...(template ? {
+        templateGuidance: template.guidance,
+        sourceTemplate: template.source,
+      } : {}),
+    },
+  };
+}
+
 export function updateWorkflowState(
   state: WorkflowState,
   changes: Partial<Omit<WorkflowState, "version" | "mode" | "root" | "activatedAt">>,

package/.pi/lib/workspace/access-policy.ts

@@ -2,7 +2,7 @@ import { homedir, tmpdir } from "node:os";
 
 import {
   findExternalPathReferences,
-  isPathInsideRoot,
+  isPathAllowedWithoutApproval,
   resolveToolPath,
   type ExternalPathReference,
 } from "../workflow-guard.ts";
@@ -21,7 +21,7 @@ export function evaluateToolPathAccess(
 ): ExternalPathReference[] {
   if (FILE_PATH_TOOLS.has(request.toolName) && typeof request.input.path === "string") {
     const resolved = resolveToolPath(root, request.input.path, homedir());
-    return isPathInsideRoot(root, resolved)
+    return isPathAllowedWithoutApproval(root, resolved)
       ? []
       : [{ raw: request.input.path, resolved }];
   }

package/README.md

@@ -100,8 +100,9 @@ Start one of the project workflows from the Pi input:
 
 Both commands first confirm the current directory and lock project work to that
 root for the session. In-root operations run normally; each tool call that names
-an external path asks for separate approval. `/hwcode-vibe` uses short iterative
-build-and-verify loops. `/hwcode-sdd` additionally requires the current directory
+an external path asks for separate approval. The non-storage sink `/dev/null` is
+approval-free even when used by shell redirection. `/hwcode-vibe` uses short
+iterative build-and-verify loops. `/hwcode-sdd` additionally requires the current directory
 to be the Git repository root, inventories the codebase, resolves requirement
 questions, and persists approved artifacts under
 `.hwcode/specs/<requirement-slug>/` before test-first implementation begins.
@@ -138,13 +139,19 @@ remaining resources, and local changes instead of attempting a fourth approach.
 
 After at least one cloud command succeeds, run
 `/hwcode-cloud-save-template [name]` to save the objective, validated execution
-sequence, and optional lessons learned as a local Prompt Template. Templates are
-stored under `~/.hwcode/cloud/prompts/` with user-only permissions. Credential
-values are excluded and redacted before steps are persisted.
+sequence, failed approaches, prerequisites, and optional lessons learned as a
+local Prompt Template. Each template records its user-facing name plus creation
+and update timestamps. Its prompt is layered into stable intent, prerequisites,
+the preferred known-good path, expensive failed paths that must not be retried,
+and the guarded execution contract. Templates are stored under
+`~/.hwcode/cloud/prompts/` with user-only permissions. Credential values are
+excluded and redacted before steps are persisted.
 
 Use `/hwcode-cloud-template [additional instructions]` to select and start a
-saved template immediately. `/hwcode-cloud` also offers saved templates when it
-starts without an inline request. The files use a Pi-compatible
+saved template by name and last-updated time. `/hwcode-cloud` also offers saved
+templates when it starts without an inline request. If a session started from a
+template, saving again asks whether to update that source template or create a
+new one. The files use a Pi-compatible
 Markdown/frontmatter format, but HWCode intentionally keeps them out of Pi
 resource discovery so each saved template does not become another slash
 command. Templates are extension-private resources and always run through the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadooppei/hwcode",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "A customizable terminal coding agent with local-model support and HWCode workflows.",
   "type": "module",
   "bin": {